Instalar com Coolify

A Coolify é o caminho de deployment público beta recomendado quando queres HTTPS gerido, deploys baseados em Git, health checks de contentores e uma UI web para variáveis de ambiente.

Definições do repositório

Cria uma aplicação a partir do repositório QuoteNode e usa estas definições:

Definição	Valor
Build Pack	Docker Compose
Base Directory	/
Docker Compose Location	/infra/docker-compose.coolify.yml
Public domain	configura apenas no frontend, por exemplo https://crm2.prodata.cc
Backend domain	deixa vazio a menos que saibas porque deve ser público
Backup worker domain	deixa vazio
Gotenberg domain	deixa vazio

O proxy da Coolify deve encaminhar o domínio para o serviço frontend. O backend, backup worker, PostgreSQL e Gotenberg ficam internos. Não atribuas domínios públicos a backend, backup-worker, postgres ou gotenberg; expor esses serviços diretamente aumenta a superfície de ataque e pode contornar a fronteira pretendida entre frontend/proxy.

Comandos de build e arranque

Para deployments normais da Coolify, deixa os comandos personalizados vazios a menos que a tua setup da Coolify os exija. Se a Coolify mostrar comandos gerados, podem parecer-se com:

docker compose build
docker compose up -d

Não contes com as definições Nixpacks Node para o runtime do QuoteNode neste modo. Os Dockerfiles e o ficheiro Compose definem o runtime.

Opções avançadas

Defaults recomendados:

Opção Coolify	Recomendação
Inject Build Args to Dockerfile	ativado
Auto Deploy	ativado para staging, opcional para produção
Git Submodules	apenas se o teu checkout precisar
LFS	apenas se o repo usar assets Git LFS
Shallow Clone	aceitável
Proxy Force HTTPS	ativado
Enable Gzip Compression	ativado
Strip Prefixes	deixa o default a menos que faças deploy sob um prefixo de path

Reve os Watch Paths antes de os usares. Um path como services/api/** é obsoleto para esta estrutura de repositório; o código do backend vive sob backend/** e o código do frontend sob frontend/**.

Variáveis de ambiente obrigatórias

Define estas na UI de ambiente da Coolify:

DB_NAME=quotenode
DB_USERNAME=quotenode
DB_PASSWORD=<random-32+-characters>
DB_URL=jdbc:postgresql://postgres:5432/quotenode
DB_ENCRYPTION_KEY=<64-hex-characters>
TIMING_TOKEN_SECRET=<random-32+-characters>
PUBLIC_LINK_PASSWORD_SESSION_SECRET=<random-32+-characters>
CORS_ALLOWED_ORIGINS=https://<frontend-domain>
NOTIFICATIONS_PUBLIC_PREFERENCES_URL=https://<frontend-domain>/notifications/preferences
PDF_ENABLED=true
NOTIFICATIONS_ENABLED=true
NOTIFICATIONS_EMAIL_ENABLED=false
FEATURE_2FA_ENABLED=true
BACKUP_ENABLED=false
BACKUP_CRON=0 0 2 * * *
SECURITY_BOT_DETECTION_ENABLED=true
# O IP do cliente é detetado automaticamente atrás de proxies internos e CDNs (incluindo Cloudflare) — deixe vazio.
# Defina apenas para um proxy invulgar cujo par de transporte seja um endereço PÚBLICO a confiar (IP/CIDR ou nome de host).
SECURITY_TRUSTED_PROXIES=
GEOIP_ENABLED=false
LOG_LEVEL=INFO
VITE_RELEASE_CHECK_ENABLED=true
VITE_RELEASE_MANIFEST_URL=https://quotenode.dev/releases/latest.json

Se a entrega de email estiver ativada, define também:

NOTIFICATIONS_EMAIL_ENABLED=true
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USERNAME[email protected]
SMTP_PASSWORD=<smtp-password>
SMTP_AUTH=true
SMTP_STARTTLS=true

O BACKUP_CRON usa o formato cron de seis campos do Spring, logo 0 0 2 * * * significa às 02:00 todos os dias.

Alguns templates de operador também incluem SERVICE_URL_FRONTEND=https://<frontend-domain>. Mantém-no alinhado com o domínio do frontend se o teu processo de deployment o usar. O ficheiro compose atual da Coolify não consome esta variável diretamente; o acesso do browser é controlado por CORS_ALLOWED_ORIGINS, e os links de preferências de notificação usam NOTIFICATIONS_PUBLIC_PREFERENCES_URL.

Metadados de release

Deployments de source da Coolify podem deixar APP_VERSION vazio a menos que esteja a ser construída uma tag de release. Define os metadados quando o teu CI ou pipeline da Coolify os puder fornecer:

# APP_VERSION pode ser omitido para deployments de source ate uma tag de release ser construida.
APP_CHANNEL=beta
APP_COMMIT_SHA=<commit-sha>
APP_BUILD_TIME=<iso-time>
APP_BUILD_NUMBER=<build-number>
APP_SOURCE_REF=<branch-or-tag>
APP_IMAGE_TAG=<image-tag>

Usa APP_CHANNEL=alpha, beta, rc, dev ou stable de acordo com o release que fazes deploy.

Segurança da licença

Para deployments beta e públicos reais:

LICENSE_SKIP_SIGNATURE_CHECK=false

Define-o explicitamente como false para deployments beta reais. O ficheiro compose também faz default a false quando a variável é omitida, mas operadores de produção não devem confiar na ambiguidade. Defini-lo como true desativa a verificação de autenticidade da licença e pode violar os termos de licença; usa-o apenas em ambientes de desenvolvimento descartáveis.

Verificações pós-deploy

Depois de o deployment estar saudável na Coolify:

1. Abre https://<frontend-domain>/health.
2. Abre o domínio do frontend num browser.
3. Faz login com o administrador seed apenas para o primeiro bootstrap, depois altera a password.
4. Cria uma proposta.
5. Gera um PDF.
6. Cria e abre um link público.
7. Se o email estiver ativado, verifica SMTP e links de preferências de notificação.
8. Verifica a área de administração de licença/versão para a versão atual e o estado do aviso de release.

Problemas comuns da Coolify

• Os links públicos falham quando CORS_ALLOWED_ORIGINS não corresponde exatamente à origem do browser.
• Os links de preferências de email falham quando NOTIFICATIONS_PUBLIC_PREFERENCES_URL ainda aponta para localhost ou um domínio antigo.
• O Gotenberg não deve receber um domínio público; é um serviço PDF interno.
• O HTTPS gerido pela Coolify exige que o domínio do frontend resolva para o servidor da Coolify.
• Se os metadados de build estiverem vazios, a aplicação ainda pode correr, mas o ecrã de versão da administração pode mostrar menos detalhes de release.