Primeiros passos#
Este guia passo a passo leva um Angie recém-instalado, partindo da página de boas-vindas do pacote, até um servidor que hospeda arquivos, encaminha requisições para uma aplicação, serve ambos por HTTPS com certificados que ele mesmo obtém, e relata suas próprias estatísticas. Se você já usa o nginx, migre a configuração existente em vez de reconstruí-la manualmente.
Cada etapa expande o arquivo que a anterior deixou pronto, então percorra-as em ordem. Apenas a etapa de HTTPS é opcional: é a única etapa que exige um nome de domínio público, e nada depois dela depende dela.
Você precisa do Angie instalado a partir de um pacote
em um Linux baseado em systemd e de uma conta que possa usar sudo.
No Alpine e no FreeBSD, a página de instalação traz os comandos
service a usar no lugar de systemctl. Confirme a versão instalada: Inicie o servidor e peça uma página a ele: A resposta vem do servidor de página de boas-vindas que o pacote traz; a próxima
etapa mostra onde ele é definido. As alterações de configuração são aplicadas com uma recarga, não uma
reinicialização: o processo mestre relê a configuração e inicia novos
processos trabalhadores, enquanto os processos antigos terminam as requisições
que estão atendendo antes de encerrar. O conjunto completo de comandos de
início, parada, recarga e rotação de logs, os sinais por trás deles e os
parâmetros de linha de comando estão descritos em Controle em tempo de execução. O arquivo de configuração principal é O arquivo é organizado em contextos — blocos que agrupam as diretivas
pertencentes a um tipo de tráfego: events — processamento geral de conexões http — tráfego HTTP mail — tráfego de e-mail stream — tráfego TCP e UDP Os arquivos em A página de boas-vindas vem de A herança entre contextos, as regras de sintaxe e as unidades de tamanho e tempo
usadas pelos parâmetros das diretivas estão em Arquivos de configuração. Comece com arquivos em disco. Crie dois diretórios com um arquivo cada; o
conteúdo indica o diretório de origem, para que a resposta mostre de onde o
arquivo veio: O segundo arquivo apenas simula uma imagem; um PNG real se comporta da mesma forma. Substitua o conteúdo de Teste a configuração e recarregue: Ambos os arquivos agora estão acessíveis, e um arquivo ausente resulta em um 404: Ambas as locations são de prefixo: elas correspondem às URIs de requisição
que começam com a string informada, e vence o prefixo mais longo que
corresponder. A diretiva root não indica o diretório de onde servir — ela indica o
diretório ao qual toda a URI de requisição é anexada, e é por isso que
Nota Quando uma requisição não faz o que você espera, a resposta está quase sempre
nos logs de acesso e de erro, gravados por padrão em Como uma requisição é comparada com servidores virtuais e locations, incluindo
as locations com expressões regulares e a ordem em que são testadas, está
descrito em Conexões, sessões, requisições, logs. As diretivas que mapeiam URIs para arquivos —
root, alias, index, try_files — estão na
referência dos módulos HTTP. A segunda função comum do Angie é atuar como proxy reverso de uma aplicação,
encaminhando as requisições para ela. Aqui o próprio Angie faz o papel da
aplicação: um segundo servidor, escutando apenas na porta 8080 do loopback,
serve um diretório próprio. Substitua-o pela aplicação real mais tarde. Coloque esse servidor em um arquivo próprio: Em Teste a configuração e recarregue: As requisições agora chegam à aplicação, exceto as de imagens: A segunda location começa com proxy_pass tem um extenso conjunto de diretivas complementares — para
cabeçalhos de requisição, tempos limite, buffering e cache — documentadas no
módulo Proxy. Para distribuir as requisições entre vários
servidores de aplicação em vez de um só, defina um bloco
upstream e faça proxy para ele pelo nome. Esta etapa precisa de um nome de domínio que resolva para o endereço público
deste host, e da porta 80 acessível pela internet: a autoridade certificadora
valida a propriedade buscando um arquivo por HTTP. Sem os dois, pule para a
próxima etapa; nada depois desta depende dela. O Angie obtém e renova certificados sozinho, via
ACME, sem cliente externo e
sem uma tarefa de cron para renovação. Adicione um acme_client acima do
bloco server (uma diretiva de nível http) e referencie o cliente a partir do
server, colocando seus próprios nomes no lugar de Por padrão, o Angie resolve o nome da autoridade certificadora por meio de
O certificado é emitido para os nomes de domínio listados em server_name
em todos os servidores que referenciam o mesmo cliente; entradas que não são
nomes de domínio, como expressões regulares e Teste a configuração e recarregue: O Angie vincula a porta 443 assim que a configuração é aplicada, mas não
consegue concluir um handshake TLS até que o certificado chegue, então as
requisições a essa porta falham durante o handshake nesse meio-tempo. A
emissão não é instantânea; depende da autoridade certificadora. Assim que o
certificado estiver disponível: Se ele nunca chegar, veja o estado do cliente em
Nota Enquanto você ainda está acertando a configuração, aponte o
acme_client para o diretório de staging da autoridade certificadora
— no caso do Let's Encrypt,
https://acme-staging-v02.api.letsencrypt.org/directory — para que as
tentativas malsucedidas não contem para os limites de taxa de produção. Mude
para a URL de produção assim que um certificado aparecer. Validação por DNS e TLS-ALPN, certificados curinga, vinculação de conta externa e
a mudança a partir do Certbot estão em Configuração ACME; as diretivas e
variáveis estão no módulo ACME. O Angie relata o próprio estado por meio de uma API REST integrada. Adicione
uma location para ela, restrita a requisições locais, e dê ao servidor uma
status_zone para que seus contadores sejam coletados: Se você pulou a etapa de HTTPS, adicione apenas as linhas destacadas. O
Teste a configuração e recarregue; a API então responde com JSON: O objeto A árvore completa de endpoints — upstreams, caches, resolvers, zonas de
memória compartilhada, clientes ACME e, no Angie PRO, a configuração
dinâmica — está documentada no módulo API. Se você prefere
visualizar esses dados a consultá-los com curl, o painel web
Console Light apresenta os mesmos números. Guias passo a passo para tarefas específicas: SSL, OIDC, clusters,
painéis de monitoramento e métricas personalizadas. A referência de todas as diretivas e variáveis, agrupadas por módulo. Links curtos que levam direto à documentação de uma diretiva. Se você também usa o nginx em outro lugar, migre essas configurações também.Verificando a instalação#
$ angie -v
Angie version: Angie/1.12.1
$ sudo systemctl start angie
$ curl -I localhost
HTTP/1.1 200 OK
Server: Angie/1.12.1
...
Estrutura da configuração#
angie.conf; sua localização é
compilada no binário:$ angie -V 2>&1 | tr ' ' '\n' | grep conf-path
--conf-path=/etc/angie/angie.conf
/etc/angie/http.d/ são incluídos dentro de http,
portanto contêm blocos server e diretivas de nível http. Ali, um bloco
server descreve um servidor virtual, e um bloco location
aninhado nele descreve como tratar um conjunto de URIs de requisição./etc/angie/http.d/default.conf, o único
servidor que o pacote define. Este guia passo a passo substitui esse arquivo e
deixa angie.conf como foi instalado.Servindo arquivos estáticos#
$ sudo mkdir -p /data/www /data/images
$ echo 'Hello from /data/www' | sudo tee /data/www/index.html
Hello from /data/www
$ echo 'Hello from /data/images' | sudo tee /data/images/example.png
Hello from /data/images
/etc/angie/http.d/default.conf por:server {
listen 80;
location / {
root /data/www;
}
location /images/ {
root /data;
}
}
$ sudo angie -t && sudo systemctl reload angie
$ curl localhost/index.html
Hello from /data/www
$ curl localhost/images/example.png
Hello from /data/images
$ curl -o /dev/null -w '%{http_code}\n' localhost/images/missing.png
404
/index.html correspondeu a location /, o
prefixo mais curto possível, que captura tudo o que as outras locations não
capturam.location /images/ precisa de root /data, não de
/data/images: a URI /images/example.png anexada a /data
resulta em /data/images/example.png./var/log/angie/.Fazendo proxy para uma aplicação#
$ sudo mkdir -p /data/app
$ echo 'Hello from the application' | sudo tee /data/app/index.html
Hello from the application
server {
listen 127.0.0.1:8080;
root /data/app;
}
default.conf, substitua root em location / por
proxy_pass, e faça a correspondência das imagens por extensão em vez de
por prefixo:server {
listen 80;
location / {
proxy_pass http://127.0.0.1:8080;
}
location ~ \.(gif|jpg|png)$ {
root /data;
}
}
$ sudo angie -t && sudo systemctl reload angie
$ curl localhost/
Hello from the application
$ curl localhost/images/example.png
Hello from /data/images
~, o que a torna uma location de
expressão regular em vez de uma de prefixo. O Angie verifica primeiro as
locations de prefixo e memoriza a correspondência mais longa; depois testa as
expressões regulares na ordem em que aparecem, e se uma delas corresponder, é
ela que vence. É isso que permite a um único padrão curto separar as
requisições de imagens da location que recolhe todo o resto, de modo que o
Angie as responde direto do disco, sem envolver a aplicação.HTTPS automático#
example.com e
www.example.com:acme_client example https://acme-v02.api.letsencrypt.org/directory;
server {
listen 80;
listen 443 ssl;
server_name example.com www.example.com;
acme example;
ssl_certificate $acme_cert_example;
ssl_certificate_key $acme_cert_key_example;
location / {
proxy_pass http://127.0.0.1:8080;
}
location ~ \.(gif|jpg|png)$ {
root /data;
}
}
/etc/resolv.conf, então nenhuma diretiva resolver é necessária.
Em um host sem conectividade IPv6, adicione resolver conf ipv6=off;
acima do bloco server para que ele pare de solicitar registros AAAA que não
pode usar._, são ignoradas com um
aviso no log de erros. O certificado chega até ssl_certificate por meio
de uma variável, e não de um caminho de arquivo, então não há nada para
instalar nem para trocar manualmente.$ sudo angie -t && sudo systemctl reload angie
$ curl -I https://www.example.com/
HTTP/1.1 200 OK
...
/status/http/acme_clients/example, na API apresentada na próxima
etapa, e as mensagens do ACME no log de erros; se isso
não for suficiente, ative o log de depuração.Estatísticas do servidor#
acme_client example https://acme-v02.api.letsencrypt.org/directory;
server {
listen 80;
listen 443 ssl;
server_name example.com www.example.com;
acme example;
ssl_certificate $acme_cert_example;
ssl_certificate_key $acme_cert_key_example;
status_zone site;
location / {
proxy_pass http://127.0.0.1:8080;
}
location ~ \.(gif|jpg|png)$ {
root /data;
}
location /status/ {
api /status/;
allow 127.0.0.1;
deny all;
}
}
default.conf do pacote já trazia essa mesma location /status/;
ela desapareceu quando você substituiu esse arquivo, então adicione-a de
volta.$ sudo angie -t && sudo systemctl reload angie
$ curl localhost/status/angie/
{
"version": "1.12.1",
"build_time": "2026-07-17T06:58:49Z",
"address": "192.0.2.10",
"generation": 1,
"load_time": "2026-07-17T10:23:06.011Z"
}
/status/connections relata as conexões aceitas, descartadas, ativas e
ociosas. Os contadores por servidor e por location são opcionais: um
server aparece em /status/http/server_zones/ e uma
location em /status/http/location_zones/, cada um somente
depois de receber sua própria status_zone. O servidor acima tem uma,
suas locations não têm:$ curl localhost/status/http/server_zones/site
{
"ssl": {
"handshaked": 3,
"reuses": 0,
"timedout": 0,
"failed": 0
},
"requests": {
"total": 5,
"processing": 1,
"discarded": 0
},
"responses": {
"200": 3,
"404": 1
},
"data": {
"received": 412,
"sent": 1418
}
}
ssl está presente porque o servidor escuta com ssl;
sem ele a zona começa em requests.Para onde ir a seguir#
Conteúdo