lzocateli/geoipupdate repository overview

⁠GeoIP2 Update Agent

Container agendado que atualiza automaticamente bases de dados GeoIP2 da MaxMind. Executa em modo daemon com frequência configurável, ideal para servir dados geográficos em aplicações que usam módulos como ngx_http_geoip2_module do NGINX.

⁠Referência da imagem

⁠Conteúdo e finalidade

⁠Incluído

• MaxMind geoipupdate v8.0.0.
• Suporte a múltiplas bases de dados GeoIP2 (GeoLite2 gratuitas ou premium).
• Agendamento automático via variável GEOIPUPDATE_FREQUENCY.
• Logging detalhado via GEOIPUPDATE_VERBOSE.

⁠Não incluído

• Conta e chave de licença MaxMind (consumidor deve fornecer).
• Bases de dados pré-carregadas (baixadas no primeiro start).
• TLS/certificados (o container não expõe porta HTTP).

⁠Início rápido

Baixe a imagem:

docker pull lzocateli/geoipupdate:8.0.0

Exemplo mínimo com arquivo .env:

cat > geoip2.env << 'EOF'
GEOIPUPDATE_ACCOUNT_ID=999999
GEOIPUPDATE_LICENSE_KEY=your_license_key_here
GEOIPUPDATE_EDITION_IDS=GeoLite2-City GeoLite2-Country GeoLite2-ASN
GEOIPUPDATE_FREQUENCY=48
GEOIPUPDATE_VERBOSE=1
EOF

docker run --name geoipupdate \
  --detach \
  --env-file geoip2.env \
  --mount type=bind,src="$(pwd)/geoip-data",dst=/usr/share/GeoIP \
  lzocateli/geoipupdate:8.0.0

Verificar logs:

docker logs geoipupdate

⁠Docker Compose

services:
  geoipupdate:
    image: lzocateli/geoipupdate:8.0.0
    container_name: geoipupdate
    restart: unless-stopped
    env_file: geoip2.env
    volumes:
      - ./geoip-data:/usr/share/GeoIP
    healthcheck:
      test: [ "CMD", "test", "-f", "/usr/share/GeoIP/GeoLite2-City.mmdb" ]
      interval: 3600s
      timeout: 10s
      retries: 3
      start_period: 60s

⁠Configuração

⁠Variáveis de ambiente

Todas as variáveis são herdadas da imagem MaxMind oficial. As principais:

⁠Portas

A imagem não expõe portas HTTP/TCP. Comunica apenas com servers da MaxMind via HTTPS para download.

⁠Persistência e mounts

As bases são baixadas no primeiro start e reutilizadas em atualizações subsequentes. Persistência é essencial para evitar redownloads desnecessários.

Propriedade esperada:

• Usuário: geoipupdate:geoipupdate (uid:gid 1000:1000)
• Permissões: rwx (diretório), rw- (arquivos .mmdb)

Bind mount recomendado no host:

mkdir -p /userapps/configs/geoip2/data
chmod 755 /userapps/configs/geoip2/data

⁠Secrets

A licença MaxMind NUNCA deve ser armazenada em variáveis de ambiente gravadas em logs. Use:

• Docker Secrets (Swarm): passadas via --secret e montadas em /run/secrets/.
• Docker Compose (Dev): arquivo .env com permissões 600, não versionado.
• Kubernetes: Secret object lido como envFrom.
• Variáveis de ambiente do host (CI/CD): carregadas via env_file ou direto da ferramenta de deploy.

Exemplo seguro com .env.example:

# .env.example (versionado, sem segredo)
GEOIPUPDATE_ACCOUNT_ID=MUDE_PARA_SEU_ID
GEOIPUPDATE_LICENSE_KEY=MUDE_PARA_SUA_CHAVE
GEOIPUPDATE_EDITION_IDS=GeoLite2-City GeoLite2-Country
GEOIPUPDATE_FREQUENCY=48
GEOIPUPDATE_VERBOSE=1

# .env (ignore file, local apenas, com segredos)
GEOIPUPDATE_ACCOUNT_ID=999999
GEOIPUPDATE_LICENSE_KEY=abc123def456...

⁠Inicialização e ciclo de vida

1. Primeiro start: Downloads todas as bases especificadas em GEOIPUPDATE_EDITION_IDS.
2. Agendamento: Se GEOIPUPDATE_FREQUENCY > 0, aguarda N horas e repete.
3. Modo única vez: Se GEOIPUPDATE_FREQUENCY = 0, executa e encerra após primeiro download.
4. Logging: Cada atualização registra resultado, versão das bases e timestamp.

Recomenda-se usar GEOIPUPDATE_FREQUENCY=24 ou 48 para manter bases atualizadas em produção.

⁠Segurança

• Usuário não root: Executa como geoipupdate:geoipupdate (uid:gid 1000:1000).
• Sem rede de entrada: Não expõe portas; apenas conecta a servers MaxMind.
• Secrets: Licença deve ser injetada via environment, Docker Secrets ou Kubernetes Secret, nunca hardcoded no Dockerfile.
• Imagem base: Mantida a partir do registry MaxMind oficial (ghcr.io/maxmind/geoipupdate); audite verificações de vulnerabilidade regularmente.

Recomendação: Configure o host ou orquestrador para rotar secrets periodicamente (ex: a cada 90 dias).

⁠Build local

docker build \
  --pull \
  --tag lzocateli/geoipupdate:8.0.0 \
  geoipupdate

Para múltiplas plataformas:

docker buildx build \
  --platform linux/amd64,linux/arm64 \
  --tag lzocateli/geoipupdate:8.0.0 \
  geoipupdate

⁠Tags e compatibilidade

Política de atualização: A cada nova versão estável do geoipupdate, cria-se uma tag imutável. A tag latest segue o upstream.

⁠Validação

Antes da publicação:

# Inspecionar Dockerfile
docker buildx build --dry-run geoipupdate

# Build local sem cache
docker build --no-cache -t test-geoip geoipupdate

# Smoke test: verificar se bases foram baixadas
docker run --rm \
  --env-file geoip2.env \
  --mount type=bind,src="$(pwd)/test-data",dst=/usr/share/GeoIP \
  test-geoip

ls test-data/  # Deve conter *.mmdb

# Inspecionar imagem
docker inspect test-geoip

# Scan de vulnerabilidades
trivy image test-geoip

⁠Publicação

Use GitHub Actions > Publicar imagem de container > Run workflow e informe:

• context_path: geoipupdate
• image_name: geoipupdate
• image_tag: 8.0.0
• dockerfile: Dockerfile
• platforms: linux/amd64,linux/arm64 (ou apenas linux/amd64 se ARM não testada)

O workflow:

1. Valida Dockerfile com BuildKit.
2. Faz scan de vulnerabilidades (Trivy).
3. Gera SBOM.
4. Faz push ao Docker Hub como lzocateli/geoipupdate:8.0.0.
5. Sincroniza este README como descrição Docker Hub.

⁠Operação

⁠Backup

# Backup de bases (recomendado antes de deletar container)
tar -czf geoip-backup-$(date +%Y%m%d).tar.gz -C /userapps/configs/geoip2 data/

⁠Restore

# Restore de backup
tar -xzf geoip-backup-20250814.tar.gz -C /userapps/configs/geoip2
docker restart geoipupdate

⁠Atualizar para nova versão

# Parar e remover container antigo
docker stop geoipupdate && docker rm geoipupdate

# Pull nova versão (ex: 8.1.0)
docker pull lzocateli/geoipupdate:8.1.0

# Restart com mesma config e volume
docker run -d \
  --name geoipupdate \
  --env-file geoip2.env \
  --mount type=bind,src=/userapps/configs/geoip2/data,dst=/usr/share/GeoIP \
  lzocateli/geoipupdate:8.1.0

⁠Logs e monitoramento

# Logs em tempo real
docker logs -f geoipupdate

# Últimas N linhas
docker logs --tail 50 geoipupdate

# Com timestamp
docker logs -t geoipupdate

⁠Limites de recursos

Recomendação para Kubernetes:

resources:
  requests:
    cpu: 100m
    memory: 128Mi
  limits:
    cpu: 500m
    memory: 512Mi

⁠Troubleshooting

⁠Limitações conhecidas

• Apenas Linux amd64: Imagem de origem MaxMind não oferece arm64 no momento da versão 8.0.0; aguardando atualização upstream.
• Atualização manual: Para forçar atualização imediata fora da agenda, reiniciar container com frequência maior ou usar sinal SIGHUP se suportado.
• GeoLite2 gratuitas: Requerem cadastro em maxmind.com; edições premium exigem licença paga.

⁠Licenças e fontes

O badge MIT descreve somente o conteúdo original deste repositório. A imagem inclui componentes de terceiros sob licenças MaxMind que permanecem sujeitos aos termos e avisos de suas fontes. Consulte a política de licenciamento⁠, preserve as atribuições upstream e respeite os termos de uso das bases de dados MaxMind.

⁠Histórico de alterações

• 8.0.0 (2024): Atualização para geoipupdate v8.0.0; alinhamento com diretrizes de container do projeto; adição de labels OCI; documentação completa.