Mkcert: локальный доверенный SSL на Ubuntu 20.04

Логотип mkcert и терминал с командами

Что такое Mkcert

Mkcert — это небольшая утилита, которая автоматически создаёт локальный центр сертификации (CA) и подписывает сертификаты для доменов вроде localhost и 127.0.0.1. Это удобно для разработки: браузеры доверяют сертификатам, созданным локальным CA, после его установки в хранилище доверенных корневых сертификатов.

Краткое определение: локальный CA — корневой сертификат, установленный в вашей системе и браузере, который позволяет подпись создаваемых сертификатов считать доверенной.

Важно: не используйте локальный CA и mkcert в продакшене — он предназначен только для локальной разработки.

Основные варианты применения

Разработка локальных веб-приложений, где нужен HTTPS.
Тестирование работы с cookie Secure, Service Workers, HTTP/2 и т.д.
Тестирование интеграции с внешними сервисами, требующими HTTPS.

Требования

Система с Ubuntu 20.04 Desktop.
Настроен root доступ или пользователь с правами sudo.

Быстрый план действий

Обновить пакеты.
Установить зависимости (wget, libnss3-tools).
Скачать бинарник mkcert и поместить в /usr/bin.
Установить локальный CA (mkcert -install).
Сгенерировать сертификат для нужных имён (например app.example.com, localhost).
Сконфигурировать Nginx для использования сертификата.
Добавить запись в /etc/hosts и проверить в браузере.

Установка и начальная настройка

Обновите списки пакетов:

apt-get update -y

Установите необходимые пакеты:

apt-get install wget libnss3-tools

Скачайте последнюю версию mkcert (в примере используется релиз v1.4.3):

wget https://github.com/FiloSottile/mkcert/releases/download/v1.4.3/mkcert-v1.4.3-linux-amd64

Переместите бинарник в системный путь и сделайте его исполняемым:

mv mkcert-v1.4.3-linux-amd64 /usr/bin/mkcert
chmod +x /usr/bin/mkcert

Проверьте версию:

mkcert --version

Пример вывода:

v1.4.3

Создание локального CA

Сгенерируйте и установите локальный корневой сертификат в системное хранилище доверия и в хранилище браузеров:

mkcert -install

Пример ожидаемого вывода:

Created a new local CA ????
The local CA is now installed in the system trust store! ??
The local CA is now installed in the Firefox and/or Chrome/Chromium trust store (requires browser restart)! ????

Путь к директории с CA можно узнать так:

mkcert -CAROOT

Пример вывода:

/root/.local/share/mkcert

Генерация сертификата для локального сайта

Создайте сертификат и ключ для нужных имён (включая localhost и IP):

mkcert app.example.com localhost 127.0.0.1 ::1

Пример вывода:

Created a new certificate valid for the following names ????
 - "app.example.com"
 - "localhost"
 - "127.0.0.1"
 - "::1"

The certificate is at "./app.example.com+3.pem" and the key at "./app.example.com+3-key.pem" ?

It will expire on 1 November 2023 ????

Примечание: в примерах показаны имена файлов с припиской +N в случае нескольких имён. Названия файлов зависят от поданных имён и количества сертификатов в директории.

Настройка Nginx для использования сертификата

Скопируйте сгенерированные файлы в каталог /etc/ssl/:

cp app.example.com+3* /etc/ssl/

Установите владельца для веб-корня (пример для стандартного www-data):

chown -R www-data:www-data /var/www/html/

Создайте конфигурацию виртуального хоста:

nano /etc/nginx/conf.d/app.conf

Добавьте:

server {
   listen 80;
   server_name app.example.com;
   root /var/www/html;
}

server {
   listen *:443 ssl;
   root /var/www/html;
   server_name app.example.com;
   ssl_certificate /etc/ssl/app.example.com+3.pem; 
   ssl_certificate_key /etc/ssl/app.example.com+3-key.pem;
}

Проверьте конфигурацию Nginx и перезапустите сервис:

nginx -t
systemctl restart nginx

Ожидаемый пример вывода проверки:

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

Затем отредактируйте файл /etc/hosts и укажите привязку домена к локальному IP:

nano /etc/hosts

Добавьте:

your-server-ip app.example.com

Замените your-server-ip на 127.0.0.1 или на локальный IP машины, где запущен Nginx.

Проверка SSL для домена

Откройте браузер и перейдите по адресу https://app.example.com. Должна отображаться защищённая связь — зеленый замок или метка “Защищено”.

Страница Nginx с защищённым соединением

Нажмите на значок замка, чтобы посмотреть детали сертификата:

Детали SSL-сертификата в браузере

Отладка и типичные проблемы

Браузер всё ещё показывает предупреждение о недоверенном сертификате: перезапустите браузер и убедитесь, что локальный CA установлен в системное и браузерное хранилище. Для Firefox может потребоваться ручная установка в отдельное хранилище Firefox.
Неправильный путь к сертификату в конфигурации Nginx: проверьте пути в директивах ssl_certificate и ssl_certificate_key.
Права доступа: Nginx (www-data) должен иметь доступ к файлам сертификата. Не выставляйте права 777 — достаточно чтения у пользователя www-data.
Конфликт адресов: если Nginx слушает 443 на другом интерфейсе, убедитесь, что listen настроен корректно.

Роли и чек-листы

Разработчик:

Установить mkcert локально.
Сгенерировать сертификат для нужных имён (localhost, специфичные домены).
Проверить работу приложения по HTTPS.

Администратор/DevOps:

Поместить сертификаты в /etc/ssl/ и настроить права.
Настроить Nginx и проверить конфигурацию.
Обеспечить резервную копию локального CA, если нужно восстановление.

Мини-методология: шаги для повторения в проекте

Подготовить список доменов и IP (например: app.local, localhost, 127.0.0.1).
Установить mkcert и зависимости.
Выполнить mkcert -install (один раз на машине разработчика/CI).
Генерировать сертификаты по мере необходимости и хранить их в защищенной папке проекта.
Настроить локальный веб-сервер и проверить в браузере.

Безопасность и ограничения

Mkcert создает локальный корневой сертификат, который доверяет всем сертификатам, подписанным им. Никогда не устанавливайте этот CA на чужие машины или в продакшн.
Храните приватные ключи в защищённых местах; не отправляйте приватные ключи в публичные репозитории.
Для продакшена используйте официальные CA (Let’s Encrypt, коммерческие центры сертификации).

Советы по совместимости и миграции

На CI обычно не устанавливают локальный CA в системное хранилище; вместо этого тесты используют инструменты, игнорирующие проверку сертификата, или мок-сервисы.
Для тестирования в контейнерах убедитесь, что mkcert установлен в контейнере или что контейнер доверяет CA хоста.
Firefox хранит сертификаты отдельно — для автоматизации установки CA в Firefox могут понадобиться дополнительные шаги.

Критерии приёмки

Сертификат успешно сгенерирован и файлы находятся в /etc/ssl/.
Nginx запускается без ошибок, nginx -t возвращает успешный тест.
При обращении по https://app.example.com браузер показывает защищённое соединение и данные сертификата подписаны локальным CA.

Контрольный список для быстрой проверки

mkcert установлен и доступен в PATH
mkcert -install выполнен
Сгенерированы .pem и -key.pem файлы
Файлы скопированы в /etc/ssl/ с корректными правами
Nginx настроен и перезапущен
/etc/hosts содержит запись для домена
Браузер доверяет сертификату

Заключение

Mkcert — быстрый и надёжный инструмент для подписи локальных сертификатов, который экономит время при разработке и тестировании HTTPS-функций. Следуйте рекомендациям по безопасности, используйте mkcert только в локальной среде и храните приватные ключи в безопасности.

Важно: для публичных и производственных систем применяйте сертификаты от официальных центров сертификации.