Como configurar o Nginx Unit

Nos últimos dias, mergulhei no NGINX Unit, um servidor da própria equipe do NGINX projetado para substituir o combo tradicional “NGINX + Gunicorn + uWSGI”.
A promessa é boa: configuração dinâmica via API, múltiplos apps (Python, PHP, Go, etc.) no mesmo processo, e até proxy reverso para outros containers.

Mas ,na prática, o Unit pode ser cheio de pegadinhas.

Segue um resumo do que aprendi — com erros, acertos e código real.

O que é o Nginx UNIT

O NGINX Unit é um servidor de aplicações modular, criado pela equipe do NGINX, mas com uma filosofia diferente:

• Ele não usa arquivos de configuração no formato nginx.conf.
• Toda a configuração é feita via API HTTP (ou socket Unix).
• E ela é atualizável em tempo real, sem reiniciar o serviço.

Você pode, por exemplo, adicionar um novo site, trocar a linguagem de execução ou criar um proxy reverso apenas enviando um POST JSON.

Subindo o Unit com Docker

O compose para o container do Unit segue o seguinte yaml:

services:

unit:
image: nginx/unit:1.32.1
ports:
- "8080:80"
volumes:
- ./config:/docker-entrypoint.d
- ./sites:/var/www/sites

Para aplicar uma configuração use o comando:

curl -X PUT --data-binary @config.json http://localhost:8080/config
# Substituta o localhost:8080 pelo endereço do seu ambiente

Configurando sites estáticos

Para configurar um site que server apenas conteúdo estático o JSON pode ser usado:

{
    "listeners": {
    "*:80": {
       "pass": "routes/main"
    }
},
    "routes": {
        "main": [
            {
                 "match": {
                 "host": "site1.example.com"
            },
        "action": {
            "share": "/var/www/sites/site1"
        }
      }
     ]
    }
}

Dica: o caminho (share) precisa existir dentro do container, então monte seu volume corretamente no docker-compose.yml.

Configurando um proxy

O Unit não entende o nome dos containers (ex: app:8000), porque ele não usa o DNS interno do Docker.

Você precisa usar um IP fixo (i.e. o IP da aplicação configurado no compose) ou um alias adicionado via extra_hosts.

O JSON que deve ser aplicado ao Unit tem estrutura semelhante, exceto pela parte a seguir:

"routes": {
    "main": [
        {
            "match": { "host":    "deployer.linkei.app.br" 
        },
     "action": {
          "proxy": "http://172.28.0.11:8000",
           "rewrite": "$uri"
      }
    }
  ]
}

💡 Importante: o campo “rewrite” deve ser uma string, não um objeto. Muita gente erra isso (inclusive eu, no começo).

Debugando erros comuns

Segue uma tabela com erros comuns e algumas soluções que apliquei.

ERRO	CAUSA	SOLUÇÃO
403 Forbidden	O Unit não tem permissão para ler o diretório share	Ajuste permissões (chmod -R a+rX /var/www/sites)
Request "pass" points to invalid location	Erro de referência no campo "pass"	Use "pass": "routes/main", não "routes/main/"
“connection reset“	Unit não consegue alcançar o container backend	Use IP fixo ou extra_hosts
“types value must be string or array“	JSON incorreto ao definir MIME types	Use "types": ["text/html", "text/css", ...]

Conclusão

O NGINX Unit é uma ferramenta poderosa — mas diferente.
Ele exige um pouco de experimentação e leitura da documentação oficial, especialmente porque pequenos detalhes de JSON podem causar grandes dores de cabeça.

Mas, uma vez entendido, ele te dá uma flexibilidade incrível:
você pode subir e atualizar sites estáticos, APIs e apps em tempo real, via API, sem reiniciar nada.

Ideal para quem está construindo plataformas de deploy automatizado.