lzocateli/nginx repository overview

⁠NGINX com headers-more e GeoIP2 dinâmicos

Imagem NGINX estável baseada em nginx:1.28.0-bookworm, com módulos dinâmicos headers-more e geoip2 compilados em build multi-stage. O contrato da imagem prioriza configuração por bind mount em /etc/nginx/conf.d.

⁠Referência da imagem

⁠Conteúdo e finalidade

⁠Incluído

• NGINX Open Source 1.28.0 sobre Debian Bookworm.
• Módulo headers-more carregado automaticamente em /etc/nginx/modules-enabled/50-mod-http-headers-more-filter.conf.
• Módulo geoip2 carregado automaticamente em /etc/nginx/modules-enabled/51-mod-http-geoip2.conf.
• Conteúdo estático de erro customizado em /usr/share/nginx/html/custom-error-page/.
• Configuração base enxuta em /etc/nginx/nginx.conf, delegando server blocks para /etc/nginx/conf.d/*.conf.

⁠Não incluído

• Certificados TLS e chaves privadas.
• Base de dados GeoIP (.mmdb).
• server blocks de aplicação específicos do ambiente.
• Health check no Dockerfile (o compose.yaml inclui healthcheck leve por HTTP local).

⁠Início rápido

Baixe a imagem:

docker pull lzocateli/nginx:1.28.0-bookworm

Exemplo mínimo com configuração e dados GeoIP por bind mount:

mkdir -p ./conf.d ./geoip-data

docker run --name nginx \
  --detach \
  --publish 127.0.0.1:8080:80 \
  --mount type=bind,src="$(pwd)/conf.d",dst=/etc/nginx/conf.d,readonly \
  --mount type=bind,src="$(pwd)/geoip-data",dst=/usr/share/GeoIP,readonly \
  lzocateli/nginx:1.28.0-bookworm

Antes de subir, valide a configuração montada:

docker run --rm \
  --mount type=bind,src="$(pwd)/nginx.conf",dst=/etc/nginx/nginx.conf,readonly \
  --mount type=bind,src="$(pwd)/conf.d",dst=/etc/nginx/conf.d,readonly \
  --mount type=bind,src="$(pwd)/geoip-data",dst=/usr/share/GeoIP,readonly \
  lzocateli/nginx:1.28.0-bookworm nginx -t

⁠Execução com Podman

Modo serviço (exemplo com rede dedicada e TLS):

podman rm nginx -f 2>/dev/null || true

podman run -d \
  --name nginx \
  --network lzo \
  --network-alias nginx \
  -p 443:443 \
  -v /userapps/ssl:/etc/nginx/ssl:ro \
  -v /userapps/configs/geoip2/data:/usr/share/GeoIP:ro \
  -v /userapps/configs/nginx:/etc/nginx/conf.d:ro \
  -v /var/log/nginx:/var/log/nginx \
  lzocateli/nginx:1.28.0-bookworm

Validação de sintaxe com Podman:

podman run --rm \
  -v /userapps/configs/nginx/nginx.conf:/etc/nginx/nginx.conf:ro \
  -v /userapps/configs/nginx:/etc/nginx/conf.d:ro \
  -v /userapps/configs/geoip2/data:/usr/share/GeoIP:ro \
  lzocateli/nginx:1.28.0-bookworm nginx -t

Em ambiente Windows/PowerShell, ajuste os caminhos para o formato absoluto local, como c:/Users/....

⁠Docker Compose

O diretório já inclui um arquivo pronto: compose.yaml.

Passos recomendados:

cp .env.example .env
podman network exists lzo || podman network create lzo
podman compose up -d

Se estiver usando Docker Compose, substitua o último comando por docker compose up -d.

As configurações de paths, portas e rede ficam no arquivo .env.

⁠Configuração

⁠Variáveis de ambiente

A imagem não adiciona variáveis de ambiente de configuração próprias. A configuração é feita por arquivos montados em bind mounts.

Para execução via Compose, use as variáveis abaixo no arquivo .env:

⁠Portas

O endpoint interno de healthcheck usa 127.0.0.1:8081/nginx-healthz apenas dentro do contêiner e não precisa ser publicado no host.

⁠Persistência e mounts

⁠Uso da página de erro customizada

O arquivo custom-error.locations é distribuído em /etc/nginx/conf.d/custom-error.locations, mas não é carregado automaticamente por nginx.conf porque a diretiva padrão usa *.conf.

Inclua o arquivo dentro de um server block, por exemplo:

server {
    listen 80;
    server_name _;

    include /etc/nginx/conf.d/custom-error.locations;

    location / {
        proxy_pass http://app:8080;
    }
}

⁠Inicialização e ciclo de vida

O entrypoint oficial do NGINX é preservado. Na inicialização, os módulos dinâmicos são carregados via /etc/nginx/modules-enabled/*.conf, o arquivo base /etc/nginx/nginx.conf é lido e os server blocks montados em /etc/nginx/conf.d passam a compor o runtime.

O compose.yaml define um healthcheck leve com curl contra http://127.0.0.1:8081/nginx-healthz, que retorna 204 por um server interno dedicado no nginx.conf.

SIGTERM encerra o processo principal de forma graciosa conforme comportamento padrão do NGINX.

⁠Segurança

• Não armazene certificados, chaves ou segredos na imagem.
• Monte /etc/nginx/ssl e arquivos sensíveis como somente leitura.
• Prefira publicar portas apenas em localhost quando não houver necessidade de exposição externa.
• Restrinja permissões de leitura aos arquivos GeoIP e TLS no host.
• Valide configuração com nginx -t antes de atualizar o serviço.

⁠Build local

A partir da raiz do repositório:

docker build --pull --tag lzocateli/nginx:1.28.0-bookworm nginx

Validação de sintaxe do Dockerfile com BuildKit:

docker buildx build --check --file nginx/Dockerfile nginx

⁠Tags e compatibilidade

Não há política de publicação para latest. Toda mudança de contrato (base, módulos, entrypoint, portas, mounts ou configuração esperada) deve receber nova tag imutável.

⁠Validação

Antes da publicação, confirme:

• .gitignore e .dockerignore presentes e atualizados;
• exclusão de .env, secrets e .git do contexto de build;
• docker buildx build --check sem erros;
• build da imagem para linux/amd64;
• nginx -t com os mounts reais de runtime;
• docker inspect --format '{{.State.Health.Status}}' nginx retornando healthy;
• smoke test com resposta HTTP/HTTPS do serviço alvo;
• inspeção de labels OCI, entrypoint e módulos carregados;
• scan de vulnerabilidades, SBOM e proveniência no workflow oficial.

⁠Publicação

Use Actions > Publicar imagem de container > Run workflow com:

• context_path: nginx;
• image_name: nginx;
• image_tag: 1.28.0-bookworm;
• dockerfile: Dockerfile;
• platforms: linux/amd64.

⁠Operação

• Faça backup dos arquivos de configuração montados no host (nginx.conf, conf.d, certificados e dados GeoIP) antes de qualquer atualização.
• Atualize sempre por nova tag imutável e valide com nginx -t antes do restart.
• Para rollback, volte para a tag anterior e restaure a mesma configuração validada no host.
• Use docker logs -f nginx ou podman logs -f nginx para troubleshooting operacional.

⁠Troubleshooting

⁠Limitações conhecidas

• Plataforma publicada e validada: somente linux/amd64.
• A imagem não distribui banco GeoIP nem certificados TLS.
• Não há HEALTHCHECK definido no Dockerfile; configure no runtime quando necessário.

⁠Licenças e fontes

O badge MIT descreve somente o conteúdo original deste repositório. Componentes de terceiros permanecem sujeitos às suas próprias licenças e avisos upstream. Consulte a política de licenciamento: https://github.com/lzocateli/containers/blob/main/LICENSING.md⁠.

⁠Histórico de alterações

• 1.28.0-bookworm: atualiza a base para NGINX 1.28.0 (Bookworm), adiciona build multi-stage e padroniza carregamento dos módulos dinâmicos headers-more e geoip2.