<!-- review: finished -->

<a id="migration"></a>

# 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](https://en.angie.software//angie/docs/installation/docker.md#docker-images),
virtual machines, custom paths, or
[modules](https://en.angie.software//angie/docs/installation/index.md#install-dynamicmodules),
you'll need additional adjustments.

<a id="installing-angie"></a>

## Installing Angie

We recommend using the official packages
from [our repositories](https://en.angie.software//angie/docs/installation/index.md#install-packages);
see the installation steps for Angie for your distribution.
Don't start the server yet;
instead, check it with the command **sudo angie -V**:

```console
$ sudo angie -V

  Angie version: Angie/|version|
  nginx version: nginx/|nginxversion|
  built by gcc 11.4.0
  configure arguments: --prefix=/etc/angie --conf-path=/etc/angie/angie.conf ...
```

As this shows,
the [configuration](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)
is located in `/etc/angie/`
when Angie is installed from a package.

<a id="updating-angie-configuration"></a>

## Updating Angie Configuration

Angie usually requires minimal changes to existing nginx configuration.

1. Copy the entire nginx configuration to `/etc/angie/`:
   ```console
   $ 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:
   ```console
   $ 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](https://en.angie.software//angie/docs/configuration/modules/core.md#include) paths that still point to `/etc/nginx/`:
   ```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](https://en.angie.software//angie/docs/configuration/modules/core.md#pid) file, which is important for Angie process management:
   ```nginx
   # pid /var/run/nginx.pid;
   # -- or --
   # pid /run/nginx.pid;
   pid /run/angie.pid;
   ```

   Finally,
   [access log](https://en.angie.software//angie/docs/configuration/modules/http/http_log.md#access-log) and [error log](https://en.angie.software//angie/docs/configuration/modules/core.md#error-log):
   ```nginx
   # 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;
   ```

<a id="migration-sites"></a>

### Virtual Hosts

If the `sites-enabled/` directory is used to include virtual hosts,
update it as well:

```nginx
# 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:

```console
$ 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:

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

Finally, recreate each symlink:

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

<a id="dynamic-modules"></a>

### Dynamic Modules

Find and [install](https://en.angie.software//angie/docs/installation/index.md#install-dynamicmodules)
Angie equivalents for all dynamic modules
referenced in nginx configuration, for example:

```console
$ 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/`

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

```nginx
# 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:

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

Finally, change the [load_module](https://en.angie.software//angie/docs/configuration/modules/core.md#load-module) path in each file:

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

`/etc/nginx/modules-enabled/`

If dynamic modules are included via
`/etc/nginx/modules-enabled/`,
update the path:

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

Then recreate the symlinks in `/etc/angie/modules-enabled/`
to make everything work.

List the original module configuration files, for example:

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

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

Note their actual location;
here it's `/usr/share/nginx/modules-available/`.

Copy them to `/usr/share/angie/`:

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

Finally, recreate each symlink:

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

<a id="root-directory-optional"></a>

### Root Directory (Optional)

If [root](https://en.angie.software//angie/docs/configuration/modules/http/index.md#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:

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

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

<a id="user-and-group-optional"></a>

### User and Group (Optional)

While it's sufficient to leave the [user](https://en.angie.software//angie/docs/configuration/modules/core.md#user) directive as is,
you can use Angie accounts for flexibility.

Update the `user` settings in Angie configuration:

```nginx
# user www-data www-data;
user angie angie;
```

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

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

If the Angie configuration has [root](https://en.angie.software//angie/docs/configuration/modules/http/index.md#root) directives,
change the owner of the directories specified there,
for example:

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

<a id="wrapping-up"></a>

### Wrapping Up

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

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

<a id="testing-and-switching"></a>

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

```console
$ sudo angie -t
```

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

<a id="stopping-nginx-starting-angie"></a>

### Stopping nginx, Starting Angie

To minimize downtime, start Angie immediately after stopping nginx:

```console
$ sudo systemctl stop nginx && sudo systemctl start angie
```

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

```console
$ sudo systemctl enable angie
```

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

<a id="disabling-nginx"></a>

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

```console
$ sudo systemctl disable nginx
```

<a id="working-with-ssl-certificates"></a>

## Working with SSL Certificates

If you used Certbot to manage SSL certificates with nginx,
it will continue to work with Angie.

<a id="using-certbot-with-angie"></a>

### Using Certbot with Angie

Supporting Angie in Certbot requires minimal effort,
since Angie is backward compatible with nginx.
For Certbot to work, it's sufficient to create a symlink
and specify the appropriate parameters:

```console
# Create a symlink for Certbot compatibility
$ sudo ln -s /etc/angie/angie.conf /etc/angie/nginx.conf

# Obtain a certificate for a domain
$ sudo certbot --nginx --nginx-server-root=/etc/angie --nginx-ctl=angie -d example.com -d www.example.com

# Automatically renew certificates
$ sudo certbot renew

# Check certificate status
$ sudo certbot certificates
```

After migrating to Angie, Certbot will continue to automatically renew certificates
through configured **cron** jobs or **systemd** timers.

<a id="migrating-from-certbot-to-the-built-in-acme-module"></a>

### Migrating from Certbot to the Built-in ACME Module

Angie includes a built-in [ACME module](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#http-acme),
which allows you to automatically obtain and renew SSL certificates
without using external tools like Certbot.

Advantages of the built-in ACME module:

- full integration with Angie configuration;
- automatic certificate renewal without additional services;
- support for HTTP and DNS validation;
- ability to obtain wildcard certificates.

For detailed instructions on migrating from Certbot to the built-in ACME module,
see the [Migrating from certbot](https://en.angie.software//angie/docs/configuration/acme.md#acme-config-certbot) section.

<a id="configuring-angie-features"></a>

## 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](https://en.angie.software//angie/docs/oss_changes.md#oss-changes) and [Angie PRO](https://en.angie.software//angie/docs/pro_changes.md#pro-changes)
that aren't in nginx?