Exemplo: implantação com Docker Compose

Esta página ilustra, a título de exemplo, uma implantação on-premise do FoxPlan em um servidor único com Docker Compose e Traefik como reverse proxy (terminação TLS e certificados Let's Encrypt automáticos).

nota

Os arquivos exatos (docker-compose.yml, scripts, configuração do Traefik) são fornecidos com o pacote de implantação on-premise. Os trechos abaixo servem para entender o funcionamento geral.

Arquitetura

                 Internet (DNS : DOMAIN → ce serveur)
                          │  80 / 443
                          ▼
                      ┌────────┐   TLS Let's Encrypt (ACME)
                      │ Traefik│   redirection 80 → 443
                      └───┬────┘
        ┌─────────────────┼───────────────────────────┐
        ▼                 ▼                ▼            ▼
   / (app:5000)   /docs (docs:8080)  /_maintenance   (bascule)
   product-server     docs           maintenance-toggle  maintenance
        │
        ├──► mongo (réseau interne)
        └──► redis (réseau interne)

Duas variantes são fornecidas:

• docker-compose.yml — uma instância da aplicação;
• docker-compose-scale.yml — várias instâncias, entre as quais o Traefik distribui automaticamente a carga.

Pré-requisitos

• Um servidor Linux com Docker e Docker Compose v2;
• Um nome de domínio cujo registro DNS aponte para o servidor;
• As portas 80 e 443 abertas para a Internet (obrigatório para o challenge ACME);
• O acesso ao registro de imagens do FoxPlan e a sua licença.

Configuração

1. Preparação inicial

Um script prepara o ambiente (arquivo .env, armazenamento dos certificados, credenciais do painel de manutenção):

MAINT_USER=foxops MAINT_PASS='un_mot_de_passe_fort' ./setup-compose.sh

2. Variáveis de infraestrutura (.env)

Variável	Descrição
DOMAIN	Domínio público servido (ex.: app.mon-entreprise.com)
ACME_EMAIL	E-mail de contato do Let's Encrypt
APP_IMAGE	Imagem da aplicação a implantar (registro/tag)

3. Segredos da aplicação

Três arquivos de segredos são criados a partir dos seus modelos .example e, em seguida, preenchidos:

cp .env_application.example .env_application   # variables de l'app (BD, OAuth, S3, JWT…)
cp .env_mongo.example       .env_mongo         # identifiants MongoDB
cp .env_redis.example       .env_redis         # mot de passe Redis

Coerências a respeitar:

• URL_MONGO usa o usuário/senha de .env_mongo, com o host mongo;
• SPRING_REDIS_PASSWORD é idêntico a REDIS_PASSWORD;
• BASE_URL corresponde a https:// + DOMAIN.

Inicialização

# Variante simple (1 instance)
docker compose up -d --build

# Variante scalée (plusieurs instances)
docker compose -f docker-compose-scale.yml up -d --build
docker compose -f docker-compose-scale.yml up -d --scale product-server=4

Na primeira inicialização, o Traefik obtém automaticamente o certificado junto ao Let's Encrypt. Verificação:

docker compose logs -f traefik     # suivre l'obtention du certificat
curl -I https://VOTRE_DOMAINE/     # doit répondre 200 avec un certificat valide
curl -I https://VOTRE_DOMAINE/docs/

Modo de manutenção

O site pode alternar para uma página de manutenção (a documentação /docs permanece acessível).

• Pelo navegador: acesse https://VOTRE_DOMAINE/_maintenance (protegido por senha) e clique em Ativar / Restabelecer.
• Pela linha de comando:

./compose-maintenance.sh on        # active la maintenance
./compose-maintenance.sh off       # rétablit l'application
./compose-maintenance.sh status    # état courant

A alternância é instantânea e não reinicia nenhum contêiner (recarregamento a quente do Traefik).

Certificados TLS (Let's Encrypt)

• Obtidos e renovados automaticamente pelo Traefik (challenge HTTP-01);
• Nenhuma ação manual necessária para a renovação.

Caso o certificado não seja emitido, verifique nesta ordem:

1. O domínio resolve corretamente para o servidor (dig +short VOTRE_DOMAINE);
2. As portas 80 e 443 estão abertas para a Internet;
3. Os logs: docker compose logs traefik | grep -i acme.

Operação cotidiana

docker compose ps                              # état des services
docker compose logs -f product-server          # logs de l'application
docker compose pull product-server && docker compose up -d   # mise à jour
docker compose down                            # arrêt (conserve les données)

Os dados do MongoDB e do Redis são conservados em volumes nomeados, que sobrevivem a paradas e reinicializações.

Solução de problemas

Sintoma	Pista
404 em /	DOMAIN incorreto, ou aplicação não iniciada (veja os logs)
502 / 503	A aplicação ainda não está escutando, ou erro na inicialização
Certificado inválido	DNS, portas 80/443, logs ACME (veja acima)
/_maintenance em loop de autenticação	Credenciais a regenerar via setup-compose.sh
Erro de autenticação Redis	SPRING_REDIS_PASSWORD ≠ REDIS_PASSWORD
Falha de autenticação Mongo	URL_MONGO incoerente com .env_mongo

---

Para o alvo de produção com escalabilidade e alta disponibilidade, veja o formato Kubernetes.