Deployment

O QuoteNode privilegia um modelo de deployment simples, legivel e facil de auditar.

Docker Compose (modelo standard)

O deployment standard usa um unico docker-compose.yml para arrancar todos os servicos:

docker compose up -d

Topologia de producao

Internet
  |
  v
Caddy (porta 80/443, HTTPS automatico)
  |-- /api/*    -> Backend (Java 25, porta 8080)
  |-- /offer/*  -> Backend (paginas publicas de propostas)
  `-- /*        -> Frontend (Vue 3, ativos estaticos)

Backend -> PostgreSQL (porta 5432)
Backend -> Gotenberg (porta 3000, geracao PDF)

backup-worker -> PostgreSQL (backups agendados)

Servicos

Contentor	Imagem	Objetivo
frontend	Vue 3 + Caddy	Serve a SPA e faz proxy dos pedidos API
backend	Java 25 / Spring Boot	API REST, regras de negocio, geracao PDF
postgres	PostgreSQL 16 Alpine	Base de dados
gotenberg	Gotenberg 8	Conversao HTML para PDF
backup-worker	Igual ao backend	Backups agendados de base de dados e ficheiros

Volumes persistentes

Volume	Conteudo
postgres_prod_data	Ficheiros da base de dados
backend_prod_uploads	Imagens de produtos e logotipos
backend_prod_pdfs	Documentos PDF gerados
backend_prod_backups	Arquivos de backup
backend_prod_geoip	Base GeoIP MaxMind, quando usada

Coolify

Coolify e uma plataforma PaaS self-hosted de codigo aberto que pode simplificar o rollout do QuoteNode.

O projeto suporta uma configuracao otimizada para Coolify, mantendo a mesma base de contentores.

Diferencas em relacao ao Docker Compose standard

• O TLS e gerido pelo Coolify - o proxy do proprio Coolify trata certificados e dominios
• Variaveis via UI - a configuracao e feita na interface web em vez de depender apenas de .env
• Health checks integrados - o Coolify monitoriza e reinicia contentores com falha
• Dois modos possiveis:
  • build a partir do codigo fonte
  • uso de imagens pre-buildadas publicadas no registry

Modo A - Build a partir do codigo

Neste modo, o Coolify faz clone do repositorio e constroi as imagens durante o deploy. E mais lento, mas simples para arrancar.

Modo B - Imagens pre-buildadas

Neste modo, a pipeline CI publica imagens num registry e o Coolify apenas faz pull e restart. E o modo mais indicado para producao.

Configuracao recomendada no Coolify

• Tipo de recurso: Dockerfile ou Docker Image
• Porta interna: 8080
• Health check path: /health
• Dominio: configurado ao nivel do Coolify
• HTTPS: imposto automaticamente pela plataforma

Observacoes sobre health checks

Vale a pena confirmar que os checks do backend, do frontend e do Gotenberg estao coerentes com o modelo de deploy, para que a plataforma nao marque o servico como unhealthy por uma rota errada.

Variaveis criticas

Em producao, convem validar sempre:

• credenciais de base de dados
• segredos de cifragem
• segredos de sessao
• CORS e dominio
• configuracao SMTP
• configuracao de backup

Para a referencia completa, incluindo portas locais de desenvolvimento e variaveis de frontend, consulta Referencia de variaveis de ambiente.

Email

As variaveis SMTP sao opcionais, mas muito recomendadas em producao quando a equipa quer enviar propostas diretamente pela aplicacao.

Backup

As variaveis de backup tornam-se fundamentais em ambientes com dados reais. O deployment nao deve ser considerado maduro sem uma politica de backup coerente.

Seguranca

Flags como 2FA, GeoIP e bot detection devem ser revistas explicitamente antes do go-live, em vez de ficarem nos defaults por acidente.

Obrigatorias

Variavel	Descricao
DB_USERNAME	Utilizador PostgreSQL
DB_PASSWORD	Password PostgreSQL
DB_ENCRYPTION_KEY	Chave AES-256 para cifragem de dados sensiveis
TIMING_TOKEN_SECRET	Segredo para tokens de protecao anti-bot
PUBLIC_LINK_PASSWORD_SESSION_SECRET	Segredo de sessao dos links publicos protegidos
CORS_ALLOWED_ORIGINS	Origins permitidas para o browser

Opcionais mas recomendadas

Variavel	Descricao
SMTP_HOST	Hostname SMTP
SMTP_PORT	Porta SMTP
BACKUP_ENABLED	Ativa backups agendados
BACKUP_RCLONE_REMOTE	Destino remoto dos backups
FEATURE_2FA_ENABLED	Ativa 2FA
GEOIP_ENABLED	Ativa controlo GeoIP
PDF_ENABLED	Ativa geracao PDF

Requisitos minimos

Cenario	RAM	CPU	Disco
Avaliacao / utilizador unico	2 GB	1 core	10 GB SSD
Equipa pequena (5-10 utilizadores)	4 GB	2 cores	20 GB SSD
Equipa media (10-50 utilizadores)	8 GB	4 cores	50 GB SSD

Sao estimativas conservadoras. O uso real depende do tamanho do catalogo, do volume de propostas e da frequencia de geracao de PDFs.