lzocateli/certbot-dns-cloudflare repository overview

⁠Certbot DNS Cloudflare

Certbot com o plugin certbot-dns-cloudflare para emissão e renovação automatizada de certificados TLS Let's Encrypt via desafio DNS-01. Permite gerar certificados wildcard e para domínios sem expor a porta 80, ideal para serviços internos com DNS gerenciado na Cloudflare.

⁠Referência da imagem

⁠Conteúdo e finalidade

⁠Incluído

• Certbot 5.7.0 com CLI completa;
• Plugin certbot-dns-cloudflare para desafio DNS-01;
• Labels OCI adicionadas pelo wrapper lzocateli/certbot-dns-cloudflare.

⁠Não incluído

• Credenciais de API da Cloudflare (devem ser montadas em runtime);
• Servidor web ou listener de rede;
• Agendador de renovação automática (cron ou systemd devem ser configurados externamente);
• Configuração de domínio ou e-mail;
• Certificados gerados (armazenados em bind mount externo).

⁠Início rápido

docker pull lzocateli/certbot-dns-cloudflare:5.7.0
docker run --rm lzocateli/certbot-dns-cloudflare:5.7.0 --version

⁠Emissão de certificado

Crie o arquivo de credenciais da Cloudflare (não versione este arquivo):

# /caminho/local/.secrets/certbot/cloudflare.ini
dns_cloudflare_api_token = SEU_TOKEN_AQUI

Execute a emissão com desafio DNS-01:

docker run --rm \
  --name certbot \
  -v /userapps/certs:/etc/letsencrypt:z \
  -v /userapps/certs/_logs:/var/log/letsencrypt:z \
  -v /caminho/local/.secrets/certbot/cloudflare.ini:/root/.secrets/certbot/cloudflare.ini:ro,z \
  lzocateli/certbot-dns-cloudflare:5.7.0 \
    certonly \
    --noninteractive \
    --dns-cloudflare \
    --dns-cloudflare-credentials /root/.secrets/certbot/cloudflare.ini \
    --force-renewal \
    --max-log-backups 5 \
    -d exemplo.com.br \
    -d "*.exemplo.com.br" \
    --email [email protected] \
    --agree-tos

Após a execução, copie o certificado para o seu web server:

cp /userapps/certs/live/exemplo.com.br/fullchain.pem /userapps/ssl/exemplo.com.br.pem
cp /userapps/certs/live/exemplo.com.br/privkey.pem   /userapps/ssl/exemplo.com.br.key

⁠Docker Compose

Exemplo de execução pontual integrada a um stack Compose:

services:
  certbot:
    image: lzocateli/certbot-dns-cloudflare:5.7.0
    volumes:
      - /userapps/certs:/etc/letsencrypt:z
      - /userapps/certs/_logs:/var/log/letsencrypt:z
      - /caminho/local/.secrets/certbot/cloudflare.ini:/root/.secrets/certbot/cloudflare.ini:ro,z
    command: >
      certonly
      --noninteractive
      --dns-cloudflare
      --dns-cloudflare-credentials /root/.secrets/certbot/cloudflare.ini
      --force-renewal
      --max-log-backups 5
      -d exemplo.com.br
      --email [email protected]
      --agree-tos

⁠Configuração

⁠Variáveis de ambiente

Esta imagem não define variáveis de ambiente adicionais. Todas as configurações são passadas como argumentos CLI ao certbot.

⁠Mounts obrigatórios

⁠Secrets

O arquivo cloudflare.ini deve conter somente:

dns_cloudflare_api_token = SEU_TOKEN_AQUI

Permissões recomendadas no host: chmod 600 cloudflare.ini. Nunca versione este arquivo; use .gitignore para bloqueá-lo.

O token de API da Cloudflare precisa das seguintes permissões:

• Zone → DNS → Edit
• Zone → Zone → Read

⁠Inicialização e ciclo de vida

O contêiner executa certbot como processo único, grava os certificados no mount /etc/letsencrypt e encerra. Não é um serviço de longa duração.

Para renovação automática, configure um cron job ou systemd timer no host que execute o contêiner periodicamente (ex.: duas vezes por semana). Certbot renova apenas certificados que expiram em menos de 30 dias quando usado com renew.

Exemplo de cron para renovação:

0 3 * * 1,4 docker run --rm -v /userapps/certs:/etc/letsencrypt:z -v /userapps/certs/_logs:/var/log/letsencrypt:z -v /caminho/.secrets/certbot/cloudflare.ini:/root/.secrets/certbot/cloudflare.ini:ro,z lzocateli/certbot-dns-cloudflare:5.7.0 renew --quiet

⁠Segurança

• O processo executa como root — necessário para gravação dos certificados nas pastas gerenciadas pelo certbot;
• O arquivo cloudflare.ini deve ser montado como somente leitura (:ro);
• Nunca incorpore o token de API na imagem, em variáveis de ambiente ou em argumentos de linha de comando visíveis em docker inspect;
• Use permissões 600 no arquivo de credenciais no host;
• Não exponha o bind mount /etc/letsencrypt com permissão de escrita para outros contêineres além do certbot e do web server que lê os certificados;
• Atualize a tag da imagem para receber correções de segurança do certbot e do plugin Cloudflare.

⁠Certificados de teste (staging)

Para validar o fluxo sem consumir os limites de rate da Let's Encrypt, acrescente os argumentos abaixo. Os certificados gerados serão inválidos para produção:

--test-cert \
--server https://acme-staging-v02.api.letsencrypt.org/directory

⁠Build local

docker build --pull --tag lzocateli/certbot-dns-cloudflare:5.7.0 certbot

⁠Tags e compatibilidade

Não há política para latest. Atualize a tag na composição e valide a renovação antes do rollout.

⁠Validação

Antes da publicação, confirme:

• .gitignore e .dockerignore presentes e bloqueando .secrets/ e *.ini;
• build sem erros com BuildKit;
• smoke test: docker run --rm lzocateli/certbot-dns-cloudflare:5.7.0 --version;
• inspeção dos labels OCI: docker inspect lzocateli/certbot-dns-cloudflare:5.7.0 --format '{{json .Config.Labels}}';
• emissão de certificado de staging (--test-cert) com domínio de teste antes da publicação.

docker buildx build --check --file certbot/Dockerfile certbot
docker build --pull --tag lzocateli/certbot-dns-cloudflare:5.7.0 certbot
docker run --rm lzocateli/certbot-dns-cloudflare:5.7.0 --version
docker inspect lzocateli/certbot-dns-cloudflare:5.7.0 --format '{{json .Config.Labels}}'

⁠Publicação

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

• context_path: certbot;
• image_name: certbot-dns-cloudflare;
• image_tag: 5.7.0;
• dockerfile: Dockerfile;
• platforms: linux/amd64.

O workflow publica no Docker Hub com SBOM e proveniência e pode sincronizar este README. A publicação não ocorre durante o build local.

⁠Operação

Mantenha backup do diretório /etc/letsencrypt do host — ele contém as chaves privadas e metadados de renovação. Para atualizar a imagem, reconstrua com a nova tag, valide com staging e ajuste o cron/systemd timer.

⁠Troubleshooting

⁠Limitações conhecidas

• Suporta apenas o plugin dns-cloudflare; outros provedores DNS exigem imagens diferentes.
• Plataforma linux/amd64 apenas.

⁠Licenças e fontes

O badge MIT descreve somente o conteúdo original deste repositório. A imagem inclui componentes de terceiros que permanecem sujeitos aos termos e avisos de suas fontes. Consulte a política de licenciamento⁠, preserve as atribuições upstream e verifique também os avisos distribuídos dentro da imagem.

⁠Histórico de alterações