Миграция с nginx#

Это руководство заменяет пакетный nginx пакетным Angie на том же сервере, сохраняя конфигурацию, виртуальные хосты, динамические модули и сертификаты. Предполагается, что nginx установлен из пакета дистрибутива и его конфигурация лежит в /etc/nginx/, а Angie ставится из официальных пакетов. Большинство директив nginx работают в Angie без изменений; исключения перечислены в Неподдерживаемые директивы nginx и разобраны ниже. Контейнеры и сборки с нестандартными путями требуют доработок, которых это руководство не описывает.

Связанные модули

Модуль Core: пути include, pid и error_log меняются на пути Angie.
Модуль HTTP Log: пути access_log ведут в /var/log/angie/.
Модуль HTTP: перенос root из /usr/share/nginx/html/.

Установка Angie#

Установите Angie из официальных пакетов для вашего дистрибутива, но пропустите шаги запуска и включения службы: порты 80 и 443 пока заняты nginx. В Debian и Ubuntu пакет запускает службу сам; занять порты она не сможет, пока работает nginx. Это ожидаемо и на установку не влияет.

Проверьте программу:

$ sudo angie -v
Angie version: Angie/1.12.4

При установке из пакета конфигурация находится в /etc/angie/: основной файл angie.conf, директории http.d/ и stream.d/, ссылка modules/ на директорию с модулями. Журналы пишутся в /var/log/angie/.

Перенос и адаптация конфигурации#

В шагах ниже используется rsync; если команды нет, установите одноименный пакет.

Скопируйте конфигурацию nginx в /etc/angie/ целиком:
```
$ sudo rsync -a --no-links /etc/nginx/ /etc/angie/
```
Параметр --no-links пропускает символические ссылки и сообщает о каждой из них; ссылки в sites-enabled/ и modules-enabled/ вы воссоздадите ниже, а если ссылка ведет за пределы /etc/nginx/, ее цель придется скопировать отдельно.
Переименуйте основной файл конфигурации так, как ожидает Angie:
```
$ sudo mv /etc/angie/nginx.conf /etc/angie/angie.conf
```

Поправьте пути во всей конфигурации Angie, начиная с основного файла. Как минимум:

Любые пути include, которые пока указывают на /etc/nginx/:

# include /etc/nginx/conf.d/*.conf;
# include /etc/nginx/default.d/*.conf;
# include /etc/nginx/http.d/*.conf;
# include /etc/nginx/stream.d/*.conf;
include /etc/angie/conf.d/*.conf;
include /etc/angie/default.d/*.conf;
include /etc/angie/http.d/*.conf;
include /etc/angie/stream.d/*.conf;

# include /etc/nginx/sites-enabled/*;
include /etc/angie/sites-enabled/*;

# include /etc/nginx/modules-enabled/*.conf;
include /etc/angie/modules-enabled/*.conf;

# include /etc/nginx/mime.types;
include /etc/angie/mime.types;

Путь к PID-файлу — служба из пакета ожидает его в /run/angie.pid:

# pid /var/run/nginx.pid;
# -- или --
# pid /run/nginx.pid;
pid /run/angie.pid;

Пути к журналу доступа и журналу ошибок:

# access_log /var/log/nginx/access.log;
access_log /var/log/angie/access.log;

# error_log /var/log/nginx/error.log;
error_log /var/log/angie/error.log;

Виртуальные хосты#

Если виртуальные хосты подключаются из sites-enabled/, include на /etc/angie/ уже переставлен, а сами файлы уже скопированы — но не символические ссылки, которые пропустил --no-links. Воссоздайте их.

Перечислите исходные ссылки и посмотрите, куда они ведут:

$ ls -l /etc/nginx/sites-enabled/

  default -> /etc/nginx/sites-available/default

Здесь это /etc/nginx/sites-available/ — внутри /etc/nginx/, поэтому копия в /etc/angie/ уже есть. Если цель ссылки лежит вне этой директории, скопируйте ее в /etc/angie/ отдельно.

Затем воссоздайте каждую ссылку, указав на копию в /etc/angie/:

$ sudo ln -s /etc/angie/sites-available/default \
             /etc/angie/sites-enabled/default

Динамические модули#

Найдите динамические модули, которые загружает конфигурация nginx:

$ sudo nginx -T | grep load_module

  load_module modules/ngx_http_geoip2_module.so;
  load_module modules/ngx_stream_geoip2_module.so;
  ...

Для популярных сторонних модулей мы публикуем свои пакеты: angie-module-имя для Angie и angie-pro-module-имя для Angie PRO. Оба файла .so из вывода команды входят в пакет angie-module-geoip2. Сверьтесь со списком пакетов и установите пакет для каждого модуля; если модуля в списке нет, его придется самостоятельно собрать для установленного Angie или Angie PRO.

Относительный путь load_module, например modules/ngx_http_geoip2_module.so, отсчитывается от префикса /etc/angie, где modules ведет на директорию с модулями пакета, поэтому менять его не нужно. Абсолютный путь из nginx поменять придется: в Debian и Ubuntu это /usr/lib/angie/modules/, в дистрибутивах семейства RHEL — /usr/lib64/angie/modules/. Какой бы способ подключения ни использовался, поправьте абсолютные пути в файлах конфигурации модулей, которые вы копируете ниже.

Конфигурацию модулей дистрибутивы подключают одним из двух способов:

Если динамические модули подключены через /usr/share/nginx/modules/, поправьте путь:

# Load dynamic modules. See /usr/share/doc/nginx/README.dynamic.
# include /usr/share/nginx/modules/*.conf;

include /usr/share/angie/modules/*.conf;

Затем скопируйте файлы конфигурации модулей:

$ sudo rsync -a /usr/share/nginx/modules/ /usr/share/angie/modules/

Если динамические модули подключены через /etc/nginx/modules-enabled/, include на /etc/angie/ уже переставлен. Воссоздайте символические ссылки, которые пропустил --no-links.

Перечислите исходные ссылки и посмотрите, куда они ведут:

$ ls -l /etc/nginx/modules-enabled/

  mod-http-geoip2.conf -> /usr/share/nginx/modules-available/mod-http-geoip2.conf

Здесь это /usr/share/nginx/modules-available/, то есть вне /etc/nginx/, поэтому скопируйте и эту директорию:

$ sudo rsync -a /usr/share/nginx/modules-available/ /usr/share/angie/modules-available/

Наконец, воссоздайте каждую ссылку:

$ sudo ln -s /usr/share/angie/modules-available/mod-http-geoip2.conf \
             /etc/angie/modules-enabled/mod-http-geoip2.conf

Изменившиеся директивы#

Часть директив nginx в Angie объявлена устаревшими, а несколько опущены полностью. Если ваша конфигурация использует какие-либо из них, см. Неподдерживаемые директивы nginx. На опущенной директиве angie -t завершается с ошибкой о неизвестной директиве, а устаревшая принимается с предупреждением, которое называет директиву для замены.

Чаще всего в конфигурациях встречается keepalive_min_timeout: в Angie ее нет — удалите ее.

Корневая директория (необязательно)#

Этот шаг нужен, только если root указывает на /usr/share/nginx/html/. Перенесите содержимое в директорию Angie:

$ sudo rsync -a /usr/share/nginx/html/ /usr/share/angie/html/

Затем поправьте директиву:

# root /usr/share/nginx/html;
root /usr/share/angie/html;

Пользователь и группа (необязательно)#

Директива user задает учетную запись, от имени которой работают рабочие процессы. Пакеты Angie создают учетную запись angie. Учетная запись nginx продолжает работать, поэтому шаг необязателен; чтобы перевести рабочие процессы на учетную запись Angie:

# user www-data www-data;
user angie angie;

Конфигурацию, сертификаты и ключи читает главный процесс от имени root, поэтому владельца /etc/angie/ менять не нужно. Рабочим процессам нужен доступ к содержимому, которое они раздают:

$ sudo chown -R angie:angie /usr/share/angie/html/

Если директивы root в конфигурации указывают на другие директории, смените владельца и у них:

$ sudo chown -R angie:angie /var/www/html/

Итоговая проверка#

Поищите все, что еще указывает на nginx:

$ grep -rn nginx /etc/angie/

Просмотрите каждое совпадение. Комментарии и файлы параметров из пакета (fastcgi_params, scgi_params, uwsgi_params) упоминают nginx безобидно; важны пути, которые по-прежнему ведут в /etc/nginx/ или /var/log/nginx/.

Проверка и переключение#

Прежде чем переключаться, убедитесь, что Angie принимает новую конфигурацию:

$ sudo angie -t

Команда загружает динамические модули и разбирает все включенные файлы. Исправьте все, на что она укажет, и повторите проверку.

Остановка nginx и запуск Angie#

Чтобы минимизировать простой, запустите Angie сразу после остановки nginx:

$ sudo systemctl stop nginx && sudo systemctl start angie

Включите службу, чтобы она запускалась после перезагрузки:

$ sudo systemctl enable angie

Убедитесь, что теперь отвечает Angie:

$ curl -I localhost
HTTP/1.1 200 OK
Server: Angie/1.12.4
...

Отключение nginx#

Убедившись, что Angie работает без сбоев, отключите nginx, чтобы после перезагрузки он не занял порты 80 и 443:

$ sudo systemctl disable nginx

Сертификаты#

Если сертификатами для nginx управлял Certbot, он продолжит работать и с Angie, как только вы укажете ему новое расположение файлов.

Certbot#

Плагин nginx в certbot ищет nginx.conf в корневой директории сервера и перезагружает сервер через программу nginx. Настройте его на Angie до следующего продления.

Создайте имя файла, которое ожидает плагин:

$ sudo ln -s /etc/angie/angie.conf /etc/angie/nginx.conf

Запустите плагин заново для тех же доменов, указав корневую директорию и программу Angie; certbot сохранит эти параметры вместе с сертификатом и использует их при продлении:

$ sudo certbot --nginx --nginx-server-root=/etc/angie --nginx-ctl=angie -d example.com -d www.example.com

Проверьте, что продление пройдет успешно:

$ sudo certbot renew --dry-run

Продлением по-прежнему занимается собственный таймер Certbot.

Встроенный клиент ACME#

Angie получает и обновляет сертификаты сам, без внешнего клиента: конфигурация показана в шаге Автоматический HTTPS, а переход с уже настроенного Certbot описан в разделе Миграция с certbot.

Что дальше#

Возможности Angie и Angie PRO	Функции, которых нет в nginx, — в открытой и в коммерческой версии.
Первые шаги	Автоматический HTTPS и API статистики на небольшом примере.
Модули	Справочник по всем директивам и переменным, сгруппированный по модулям.
Инструкции	Пошаговые руководства по отдельным задачам: SSL, OIDC, кластеризация, панели мониторинга и пользовательские метрики.