Migrating from nginx#

This guide replaces a packaged nginx with a packaged Angie on the same host, keeping the configuration, virtual hosts, dynamic modules, and certificates. It assumes nginx was installed from a distribution package with its configuration in /etc/nginx/, and that Angie comes from the official packages. Most nginx directives work in Angie unchanged; the exceptions are listed in Unsupported nginx Directives and handled below. Containers and builds with custom paths need adjustments this guide does not cover.

Installing Angie#

Install Angie from the official packages for your distribution, but skip the start and enable steps: nginx still holds ports 80 and 443. On Debian and Ubuntu the package starts the service by itself, and that attempt fails to bind while nginx is running; the failure is expected and does not affect the installation.

Confirm the binary:

$ angie -v
Angie version: Angie/1.12.2

The packages put the configuration in /etc/angie/ — angie.conf alongside the http.d/ and stream.d/ directories and a modules/ link to the module directory — and the logs in /var/log/angie/.

Copying and Adapting the Configuration#

The steps below use rsync; install its package if the command is missing.

Copy the entire nginx configuration to /etc/angie/:
```
$ sudo rsync -a --no-links /etc/nginx/ /etc/angie/
```
The --no-links option skips symlinks, reporting each one it passes over; you recreate the ones in sites-enabled/ and modules-enabled/ below, and a link whose target lies outside /etc/nginx/ needs its target copied separately.

Rename the main configuration file as Angie expects:

$ sudo mv /etc/angie/nginx.conf /etc/angie/angie.conf

Update the paths throughout the Angie configuration, starting with the main file. At minimum:

Any include paths that still point to /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;

The pid path, which the packaged service unit expects at /run/angie.pid:

# pid /var/run/nginx.pid;
# -- or --
# pid /run/nginx.pid;
pid /run/angie.pid;

The access log and error log paths:

# 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;

Virtual Hosts#

If virtual hosts are included from sites-enabled/, the include already points at /etc/angie/ and the files themselves are already copied, but not the symlinks, which --no-links skipped. Recreate them.

List the originals and note where they point:

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

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

Here it is /etc/nginx/sites-available/, inside /etc/nginx/, so the Angie copy is already in place. If a target lies outside that directory, copy it into /etc/angie/ as well.

Then recreate each symlink against the Angie copy:

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

Dynamic Modules#

Find the dynamic modules the nginx configuration loads:

$ sudo nginx -T | grep load_module

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

For popular third-party modules Angie ships packages: angie-module-name for Angie and angie-pro-module-name for Angie PRO; here angie-module-geoip2 provides both files. Check the package list and install one for every module the command lists; a module that is not in the list must be built for Angie.

A relative load_module path such as modules/ngx_http_geoip2_module.so resolves against the prefix /etc/angie, where modules links to the package's module directory, so it needs no change. An absolute nginx path does: rewrite it to /usr/lib/angie/modules/ on Debian and Ubuntu, or /usr/lib64/angie/modules/ on the RHEL family. Whichever layout you have, rewrite the absolute paths in the module configuration files you copy below.

Distributions wire the module configuration in one of two ways:

If dynamic modules are included via /usr/share/nginx/modules/, update the path:

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

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

Then copy the module configuration files:

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

If dynamic modules are included via /etc/nginx/modules-enabled/, the include already points at /etc/angie/. Recreate the symlinks that --no-links skipped.

List the originals and note where they point:

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

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

Here it is /usr/share/nginx/modules-available/, outside /etc/nginx/, so copy that directory as well:

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

Finally, recreate each symlink:

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

Diverging Directives#

Angie deprecates a few nginx directives and omits a few others. If your configuration relies on any of them, see Unsupported nginx Directives. An omitted directive makes angie -t fail with an unknown-directive error; a deprecated one is accepted and logs a warning naming the directive to use instead.

The one most likely to appear in an existing configuration is nginx's keepalive_min_timeout: Angie omits it, so delete it.

Root Directory (Optional)#

This step applies only if root points to /usr/share/nginx/html/. Copy the contents into the Angie directory:

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

Then update the directive:

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

User and Group (Optional)#

The user directive names the account the worker processes run as. The Angie packages create an angie account. nginx's account keeps working, so this step is optional; to switch the workers to the Angie account:

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

The master process parses the configuration and reads certificates and keys as root, so the ownership of /etc/angie/ does not change. What the workers need is access to the content they serve:

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

If the configuration has root directives pointing elsewhere, change the owner of those directories too:

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

Final Check#

Look for anything still pointing at nginx:

$ grep -rn nginx /etc/angie/

Review each hit. Comments and the stock parameter files (fastcgi_params, scgi_params, uwsgi_params) name nginx harmlessly; what matters is paths that still resolve under /etc/nginx/ or /var/log/nginx/.

Testing and Switching#

Check that Angie accepts the configuration:

$ sudo angie -t

The command loads the dynamic modules and parses every included file; fix each reported error and re-run until the test passes.

Stopping nginx, Starting Angie#

To minimize downtime, start Angie immediately after stopping nginx:

$ sudo systemctl stop nginx && sudo systemctl start angie

Enable the service so that it starts after a reboot:

$ sudo systemctl enable angie

Confirm that the answer now comes from Angie:

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

Disabling nginx#

Once Angie has run without problems, disable nginx so that it does not reclaim ports 80 and 443 after a reboot:

$ sudo systemctl disable nginx

Certificates#

If Certbot managed the certificates for nginx, it keeps working with Angie once it is pointed at the new layout.

Certbot#

The certbot nginx plugin looks for nginx.conf in the server root and reloads the server through the nginx binary. Point it at Angie before the next renewal.

Create the file name the plugin expects:

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

Re-run the plugin for the existing domains, naming Angie's server root and binary; certbot stores these parameters with the certificate and reuses them at renewal:

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

Verify that a renewal would succeed:

$ sudo certbot renew --dry-run

Renewals continue through Certbot's own timer.

Built-in ACME Client#

Angie obtains and renews certificates itself, without an external client: Automatic HTTPS shows the configuration, and Migrating from certbot covers replacing an existing Certbot setup.

Where to Go Next#

What Angie adds and Angie PRO	Features nginx does not have, in the open-source and the commercial version.
First Steps	Automatic HTTPS and the statistics API on a small example.
Modules	The reference for every directive and variable, grouped by module.
Instructions	Step-by-step guides for specific tasks: SSL, OIDC, clustering, monitoring dashboards, and custom metrics.