Migrating from nginx to Angie

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

Keep in mind that it's tailored for a basic replacement scenario that relies on a packaged version of Angie. If you're working with containers, virtual machines, custom paths, or modules, you'll need additional adjustments.

Installing Angie

We recommend using the official packages from our repositories; see the installation steps for Angie for your distribution. Don't start the server yet; instead, check it with the command sudo angie -V:

$ sudo angie -V

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

As this shows, the configuration is located in /etc/angie/ when Angie is installed from a package.

Updating Angie Configuration

Angie usually requires minimal changes to existing nginx configuration.

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

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

   We assume nginx configuration is stored in /etc/nginx/; adjust the steps if you have a different path.

2. Rename the main configuration file as Angie expects:

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

3. Update paths throughout the Angie configuration, starting with the main configuration file. Details depend on how nginx was installed, but at minimum you need to update the following.

   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/*;
   include /etc/angie/modules-enabled/*;
   
   # include /etc/nginx/mime.types;
   include /etc/angie/mime.types;
   

   The PID file, which is important for Angie process management:

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

   Finally, 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 the sites-enabled/ directory is used to include virtual hosts, update it as well:

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

Then recreate the symlinks in /etc/angie/sites-enabled/ to make everything 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 to /etc/angie/ earlier, 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 equivalents for 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 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/

Finally, change 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 root points to the /usr/share/nginx/html/ directory, you can change the directive to point to Angie.

Copy the directory and update the root value 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 sufficient to leave the user directive as is, you can use Angie accounts for flexibility.

Update the user settings in Angie configuration:

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

Change the owner of all configuration files, including files in /usr/share/angie/, for example:

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

If the Angie configuration has root directives, change the owner of the directories specified there, for example:

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

Wrapping Up

To make sure nothing is missed, find and fix remaining mentions of nginx in Angie configuration:

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

Testing and Switching

After updating Angie configuration, the next step is to check its syntax to ensure Angie can work with it, and then switch over. Verify that Angie accepts the new configuration:

$ sudo angie -t

This command parses the configuration and reports errors that would block Angie startup; fix any issues and re-run the command.

Stopping nginx, Starting Angie

To minimize downtime, start Angie immediately after stopping nginx:

$ sudo systemctl stop nginx && sudo systemctl start angie

If needed, enable the Angie service to start after reboot:

$ sudo systemctl enable angie

Migration complete! That's it; you're awesome.

Disabling nginx

After confirming that Angie is running stably, you can disable or remove nginx to avoid conflicts.

The minimum you can do is disable the service:

$ sudo systemctl disable nginx

Configuring Angie Features

It's safe to assume you're migrating for a reason. Why not go further and configure some of the additional features available in Angie and Angie PRO that aren't in nginx?