So you have decided to use Angie as a replacement for Nginx. Where do you start? What do you need to account for during the switch? Here is the whole process, step by step.
A quick reminder: Angie is a fork of Nginx. That makes the move from Nginx to Angie much easier, because Angie supports the same features and configuration directives as Nginx. Moving back from Angie to Nginx may not be as simple once you start using Angie-specific features (such as its proxying or load-balancing capabilities).
Start by preparing the system for the migration.
Video version
There is also a video version of this article on YouTube.
Preparing for the migration
The first step is to collect the source data for the move — namely, to answer the following questions.
- Which version of Nginx is in use?
- In which directories is the configuration stored?
- Are there any differences from the standard packages (SSL library version, custom build options, non-standard static modules)?
- Which dynamic modules are loaded?
- Are there any commands tied to the service name (certificate renewal, config automation, etc.)?
To find the configuration, it is convenient to start with the file /etc/nginx/nginx.conf. Almost always this is the main configuration file, in which you can find all the include directives for the rest of the configuration files. If the main config is missing from the standard directory, check the --conf-path parameter in the output of nginx -V. To find the loaded modules and include directives, use nginx -T:
nginx -T | grep load_module
nginx -T | grep include
With the initial data collected, move on to installing Angie.
Installing Angie
Installing Angie is out of scope here. What matters in the context of the migration is that the Angie package allows a parallel install with Nginx. That means you can install Angie on a system with a running Nginx and prepare the switchover without interrupting the service.
After installing Angie, disable the service autostart to avoid problems at system startup during the transition period:
systemctl disable angie
This is because Nginx and Angie cannot run on the same socket. If Angie starts first, Nginx will not be able to start. Angie's autostart can be enabled again after the move.
To install all the additional modules, take them from the Angie repository. It is best to declare the loading of all dynamic modules in /etc/angie/angie.conf right away. For example:
load_module modules/ngx_http_brotli_static_module.so;
load_module modules/ngx_http_brotli_filter_module.so;
If you are using Docker containers, run Angie on non-overlapping ports and set aside a separate directory for the configuration on the host filesystem.
Modifying the configs
The main configuration changes are about paths. Configuration file paths change from /etc/nginx to /etc/angie, log paths from /var/log/nginx to /var/log/angie.
First, copy the main configuration files from /etc/nginx to /etc/angie. Important: the Nginx configuration in /etc/nginx must not be modified under any circumstances. It stays in place for rolling back to Nginx if something goes wrong.
To see what needs replacing, start by searching for /nginx paths:
grep -rn '/nginx' /etc/angie
Then go through the configs and replace /nginx paths with /angie:
find . -type f -name '*.conf' -exec sed --follow-symlinks -i 's|/nginx|/angie|g' {} \;
If the configs include symbolic links (for example, sites-enabled/), their paths need to be changed too. The solution below consists of several steps; there may be a more elegant way to do this (suggestions are welcome). First the commands are generated into a script, then it is run:
find /etc/angie/sites-enabled/* -type l -printf 'ln -nsf
"$(readlink "%p" | sed s!/etc/nginx/sites-available!/etc/angie/sites-available!)"
"$(echo "%p" | sed s!/etc/nginx/sites-available!/etc/angie/sites-available!)"\n'
> script.sh
chmod +x script.sh
./script.sh
Test the generated configuration:
sudo angie -t
If there are no errors, you can move on to the next stage. Keep in mind that the configuration test checks only the syntax of the configuration files and does not guarantee a successful server start; errors must be tracked in error_log.
Switching to Angie
Full testing of the configuration requires starting Angie. The goal during the switch is to minimize downtime. Again, a reminder to test the configuration:
sudo angie -t
Then stop Nginx and start Angie with the following:
sudo systemctl stop nginx && sudo systemctl start angie
If you run into problems or the system behaves incorrectly, roll back to Nginx and deal with the issues calmly:
sudo systemctl stop angie && sudo systemctl start nginx
Monitor the system and watch for errors in error_log. If the switch went through successfully, update the autostart settings for the services:
sudo systemctl disable nginx
sudo systemctl enable angie
After some time you can remove the Nginx packages, the configuration in /etc/nginx and the logs in /var/log/nginx.
Also do not forget about the external utilities that worked with Nginx: certificate-renewal commands that trigger a reload, log rotation settings, monitoring checks — if they relied on the process name or the Server header in the response. There are two ways to switch them to Angie: update the scripts and checks to the new process and service, or create symbolic links and aliases so that the old Nginx commands keep working. For example, for the angie service unit you can create an nginx alias using a symbolic link:
sudo ln -s /usr/lib/systemd/system/angie.service /etc/systemd/system/nginx.service
sudo systemctl daemon-reload
sudo systemctl reload nginx
You can also create symbolic links for paths if needed.
The move to Angie can now be considered complete. If you have ideas about what else could be added to this process, feel free to share them.