How to migrate from nginx to Angie

If you're switching from nginx to Angie, congratulations! We have a guide for you.

Keep in mind, though, that it's tailored for a basic swap-out scenario that relies on a packaged version of Angie. If you're dealing with containers, virtual machines, custom paths, or modules, you'll need to tweak things accordingly.

Install Angie

We recommend using the official packages from our repos; see the instructions for your distribution to install Angie, but stop short of actually starting it. Instead, run sudo angie -V to make sure everything's in order:

$ sudo angie -V

  Angie version: Angie/1.8.2
  nginx version: nginx/1.27.3
  built by gcc 11.4.0
  configure arguments: --prefix=/etc/angie --conf-path=/etc/angie/angie.conf ...

As this output suggests, the configuration is located under /etc/angie/ when Angie is installed from a package.

Update Angie configuration

Angie usually requires minimal changes to an existing nginx configuration.

1. Copy the entire nginx configuration to /etc/angie/:

   $ sudo rsync -a --no-links /etc/nginx/ /etc/angie/
   

   We assume that nginx stores its configuration under /etc/nginx/; adjust the steps if your path is different.

2. Rename the main configuration file as Angie expects it to be:

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

3. Update the paths in the entire Angie configuration, starting with the main configuration file. The details vary depending on how nginx was installed, but at least you need to update the following parts.

   Any include paths that still point under /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/*;
   include /etc/angie/modules-enabled/*;
   
   # include /etc/nginx/mime.types;
   include /etc/angie/mime.types;
   

   The PID file, which is crucial for Angie PROcess management:

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

   Lastly, access log and error log:

   # 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 a directory such as sites-enabled/ is used to include virtual hosts, update it:

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

Next, recreate the symlinks under /etc/angie/sites-enabled/ to make it work.

List the original virtual host files, for example:

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

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

Note their actual location; here, it's /etc/nginx/sites-available/.

If you didn't copy them under /etc/angie/ previously, copy them now:

$ sudo rsync -a /etc/nginx/sites-available/ /etc/angie/sites-available/

Finally, recreate each symlink:

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

Dynamic modules

Find and install Angie's counterparts to all dynamic modules referenced in nginx configuration, for example:

$ sudo nginx -T | grep load_module

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

This means you need to install the angie-module-geoip2 package, and so on.

There are two popular ways to include dynamic module configuration:

/usr/share/nginx/modules//etc/nginx/modules-enabled/

If the 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;

Next, copy the module configuration files:

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

Lastly, amend the load_module path in each file:

# load_module "/usr/lib64/nginx/modules/ngx_http_geoip2_module.so";
load_module "/usr/lib64/angie/modules/ngx_http_geoip2_module.so";

Root directory (optional)

If the root directive references a directory such as /usr/share/nginx/html/, you can change it to point to Angie.

Copy the directory and update the root setting in Angie configuration:

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

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

User and group (optional)

While it's fine to leave the user directive as is, you can use separate accounts with Angie for extra flexibility.

Update the user settings in Angie configuration:

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

Next, change the owner of all configuration files, including the ones under /usr/share/angie/, for example:

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

If Angie configuration defines the root directive, change the owner of the respective directories too, for example:

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

Wrapping up

To make sure you didn't miss anything, find and fix the remaining occurrences of nginx in Angie configuration:

$ grep -rn --include='*.conf' 'nginx' /etc/angie/

Test and switch

Now that you've updated Angie configuration, the next step is to verify its syntax to make sure Angie can actually work with it, and then perform the switchover. Check that Angie can run the updated configuration:

$ sudo angie -t

The command parses the configuration and reports issues that block Angie's start; fix any problems and re-run it.

Stop nginx, start Angie

To minimize downtime, start Angie immediately after stopping nginx:

$ sudo systemctl stop nginx && sudo systemctl start angie

Optionally, enable the Angie service to start it after reboot:

$ sudo systemctl enable angie

The migration is done! That's it. You're amazing.

Disable nginx

Last, when you're sure that Angie is running smoothly, you'll need to disable or uninstall nginx to avoid conflicts.

The least you can do is disable the service:

$ sudo systemctl disable nginx

Configure Angie extras

It's safe to assume that you're migrating for a reason, so why not go a step further and configure some of the additional features that Angie and Angie PRO offer on top of nginx?