Migrando do nginx#

Este guia substitui um nginx empacotado por um Angie empacotado no mesmo host, preservando a configuração, os hosts virtuais, os módulos dinâmicos e os certificados. Ele pressupõe que o nginx foi instalado a partir de um pacote de distribuição, com sua configuração em /etc/nginx/, e que o Angie vem dos pacotes oficiais. A maioria das diretivas nginx funciona no Angie sem alterações; as exceções estão listadas em Diretivas nginx não suportadas e são tratadas abaixo. Contêineres e compilações com caminhos personalizados precisam de ajustes que este guia não cobre.

Instalando o Angie#

Instale o Angie a partir dos pacotes oficiais para sua distribuição, mas pule as etapas de iniciar e habilitar o serviço: o nginx ainda ocupa as portas 80 e 443. No Debian e no Ubuntu o pacote inicia o serviço por conta própria, e essa tentativa falha ao vincular a porta enquanto o nginx está em execução; a falha é esperada e não afeta a instalação.

Confirme o binário:

$ sudo angie -v
Angie version: Angie/1.12.4

Os pacotes colocam a configuração em /etc/angie/ — angie.conf ao lado dos diretórios http.d/ e stream.d/ e de um link modules/ para o diretório de módulos — e os logs em /var/log/angie/.

Copiando e adaptando a configuração#

As etapas abaixo usam rsync; instale o pacote correspondente se o comando não estiver disponível.

Copie toda a configuração nginx para /etc/angie/:
```
$ sudo rsync -a --no-links /etc/nginx/ /etc/angie/
```
A opção --no-links ignora os links simbólicos, relatando cada um que encontra; você recria os de sites-enabled/ e modules-enabled/ abaixo, e um link cujo destino esteja fora de /etc/nginx/ precisa ter esse destino copiado separadamente.
Renomeie o arquivo de configuração principal como o Angie espera:
```
$ sudo mv /etc/angie/nginx.conf /etc/angie/angie.conf
```

Atualize os caminhos em toda a configuração do Angie, começando pelo arquivo principal. No mínimo:

Quaisquer caminhos include que ainda apontem para /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;

O caminho pid, que a unidade de serviço do pacote espera em /run/angie.pid:

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

Por fim, os caminhos do log de acesso e do log de erros:

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

Hosts virtuais#

Se os hosts virtuais forem incluídos a partir de sites-enabled/, o include já aponta para /etc/angie/ e os próprios arquivos já foram copiados, mas não os links simbólicos, que --no-links ignorou. Recrie-os.

Liste os originais e anote para onde apontam:

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

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

Neste caso é /etc/nginx/sites-available/, dentro de /etc/nginx/, então a cópia do Angie já está no lugar. Se um destino estiver fora desse diretório, copie-o também para /etc/angie/.

Em seguida, recrie cada link simbólico apontando para a cópia do Angie:

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

Módulos dinâmicos#

Encontre os módulos dinâmicos que a configuração do nginx carrega:

$ sudo nginx -T | grep load_module

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

Para módulos de terceiros populares, publicamos pacotes: angie-module-name para o Angie e angie-pro-module-name para o Angie PRO. Os dois arquivos .so da saída acima vêm do pacote angie-module-geoip2. Consulte a lista de pacotes e instale um pacote para cada módulo listado pelo comando; um módulo que não está na lista precisa ser compilado para o Angie ou o Angie PRO instalado.

Um caminho load_module relativo, como modules/ngx_http_geoip2_module.so, é resolvido em relação ao prefixo /etc/angie, onde modules aponta para o diretório de módulos do pacote, então não precisa de alteração. Já um caminho absoluto do nginx precisa de ajuste: reescreva-o para /usr/lib/angie/modules/ no Debian e no Ubuntu, ou /usr/lib64/angie/modules/ na família RHEL. Qualquer que seja o layout que você tenha, reescreva os caminhos absolutos nos arquivos de configuração de módulo que você copiar abaixo.

As distribuições incluem a configuração dos módulos de uma destas duas maneiras:

Se os módulos dinâmicos forem incluídos via /usr/share/nginx/modules/, atualize o caminho:

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

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

Então copie os arquivos de configuração do módulo:

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

Se os módulos dinâmicos forem incluídos via /etc/nginx/modules-enabled/, o include já aponta para /etc/angie/. Recrie os links simbólicos que --no-links ignorou.

Liste os originais e anote para onde apontam:

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

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

Neste caso é /usr/share/nginx/modules-available/, fora de /etc/nginx/, então copie esse diretório também:

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

Por fim, recrie cada link simbólico:

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

Diretivas divergentes#

O Angie descontinua algumas diretivas nginx e omite outras poucas. Se sua configuração depender de alguma delas, veja Diretivas nginx não suportadas. Uma diretiva omitida faz angie -t falhar com um erro de diretiva desconhecida; uma descontinuada é aceita e registra um aviso indicando a diretiva a usar em seu lugar.

A mais provável de aparecer em uma configuração existente é a keepalive_min_timeout do nginx: o Angie a omite, então remova-a.

Diretório root (opcional)#

Esta etapa se aplica apenas se root apontar para /usr/share/nginx/html/. Copie o conteúdo para o diretório do Angie:

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

Em seguida, atualize a diretiva:

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

Usuário e grupo (opcional)#

A diretiva user indica a conta com a qual os processos trabalhadores são executados. Os pacotes do Angie criam uma conta angie. A conta do nginx continua funcionando, então esta etapa é opcional; para alternar os processos trabalhadores para a conta do Angie:

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

O processo mestre analisa a configuração e lê certificados e chaves como root, então a propriedade de /etc/angie/ não muda. O que os processos trabalhadores precisam é de acesso ao conteúdo que servem:

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

Se a configuração do Angie tiver diretivas root apontando para outros diretórios, altere também o proprietário deles, por exemplo:

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

Verificação final#

Procure por qualquer coisa que ainda aponte para o nginx:

$ grep -rn nginx /etc/angie/

Revise cada ocorrência. Comentários e os arquivos de parâmetros padrão (fastcgi_params, scgi_params, uwsgi_params) citam o nginx sem problema; o que importa são caminhos que ainda resolvem para /etc/nginx/ ou /var/log/nginx/.

Testando e fazendo a transição#

Verifique se o Angie aceita a nova configuração:

$ sudo angie -t

O comando carrega os módulos dinâmicos e analisa cada arquivo incluído; corrija cada erro relatado e execute novamente até o teste passar.

Parando o nginx, iniciando o Angie#

Para minimizar o tempo de inatividade, inicie o Angie imediatamente após parar o nginx:

$ sudo systemctl stop nginx && sudo systemctl start angie

Habilite o serviço para que ele inicie após uma reinicialização:

$ sudo systemctl enable angie

Confirme que a resposta agora vem do Angie:

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

Desabilitando o nginx#

Depois que o Angie funcionar sem problemas, desabilite o nginx para que ele não retome as portas 80 e 443 após uma reinicialização:

$ sudo systemctl disable nginx

Certificados#

Se o Certbot gerenciava os certificados do nginx, ele continua funcionando com o Angie assim que for apontado para o novo layout.

Certbot#

O plugin nginx do certbot procura nginx.conf na raiz do servidor e recarrega o servidor por meio do binário nginx. Aponte-o para o Angie antes da próxima renovação.

Crie o nome de arquivo que o plugin espera:

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

Execute o plugin novamente para os domínios existentes, indicando a raiz do servidor e o binário do Angie; o certbot armazena esses parâmetros junto com o certificado e os reutiliza na renovação:

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

Verifique se uma renovação teria sucesso:

$ sudo certbot renew --dry-run

As renovações continuam pelo próprio timer do Certbot.

Cliente ACME integrado#

O Angie obtém e renova certificados sozinho, sem um cliente externo: HTTPS automático mostra a configuração, e Migrando do certbot cobre a substituição de uma configuração existente do Certbot.

Para onde ir a seguir#

O que o Angie adiciona e o Angie PRO	Recursos que o nginx não tem, na versão de código aberto e na comercial.
Primeiros passos	HTTPS automático e a API de estatísticas em um pequeno exemplo.
Módulos	A referência de todas as diretivas e variáveis, agrupadas por módulo.
Instruções	Guias passo a passo para tarefas específicas: SSL, OIDC, clusters, painéis de monitoramento e métricas personalizadas.