Installation

Instalar num Servidor Público Ubuntu

Coloca o QuoteNode num servidor público Ubuntu com domínio, HTTPS, SMTP, backups e fundamentos de firewall.

Instalar num Servidor Público Ubuntu

Usa este caminho para um deployment em produção acessível por clientes através de um domínio público.

Quando usar

Clientes externos devem abrir links públicos de propostas.
As mensagens de email devem conter links funcionais.
Queres controlo direto sobre o servidor em vez de uma camada PaaS.

O que não vai funcionar sem configuração adequada

Links públicos falham se o DNS não apontar para o servidor.
Links públicos falham se o URL do browser diferir da configuração CORS.
A emissão do certificado HTTPS falha se os portos 80/443 estiverem bloqueados.
Links de email falham se o SMTP estiver em falta ou se as mensagens forem rejeitadas pelo provider de email do destinatário.
Deployments com IP doméstico dinâmico precisam de DDNS e port forwarding no router; um VPS é normalmente mais simples.

Pré-requisitos

Servidor Ubuntu LTS ou VPS.
Registo DNS público, por exemplo crm.example.com, a apontar para o servidor.
Portos 80 e 443 abertos a partir da internet.
Docker Engine 24.0+ e Docker Compose v2.
Conta SMTP para entrega de email.
Pelo menos 4 GB de RAM e 20 GB de espaço livre em disco (recomendados para produção).
Destino de backup e um procedimento de restore.
Um anfitrião x86 de 64 bits (linux/amd64). Dispositivos ARM, incluindo NAS com processador ARM, não são suportados.

Verifica o Docker:

docker --version        # Should show 24.0+
docker compose version  # Should show v2.x

Passo 1 — Criar uma diretoria de projeto

mkdir quotenode && cd quotenode
curl -fsSLO https://quotenode.dev/releases/v0.9.8-alpha/quotenode-deploy-v0.9.8-alpha.tar.gz
tar -xzf quotenode-deploy-v0.9.8-alpha.tar.gz --strip-components=1

Assim transferes o pacote de implementação da versão v0.9.8-alpha: docker-compose.yml com cada imagem fixada por digest, env.example, release.json (a identidade da versão) e operator/ (ferramentas de backup e restauração).

Problema conhecido na v0.9.5-alpha: o respetivo env.example contém uma linha de exemplo ativa, BACKUP_RCLONE_REMOTE=s3:mybucket/backups, que faz falhar todas as cópias de segurança. As definições deste guia não a contêm; se copiares definições do env.example, omite essa linha (detalhes).

Passo 2 — Criar o ficheiro de configuração

Cria um ficheiro chamado .env. Substitui crm.example.com pelo teu domínio real:

# Database
DB_URL=jdbc:postgresql://postgres:5432/quotenode
DB_USERNAME=quotenode
DB_PASSWORD=change-me-to-something-random-32-chars
DB_NAME=quotenode

# ============================================================
# SECURITY SECRETS — UNIQUE to this installation.
# SAVE THIS FILE and keep a secure backup.
# ============================================================
DB_ENCRYPTION_KEY=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
TIMING_TOKEN_SECRET=change-me-timing-secret-min-32-chars
PUBLIC_LINK_PASSWORD_SESSION_SECRET=change-me-session-secret-min-32

# Public domain — replace with your real domain
CORS_ALLOWED_ORIGINS=https://crm.example.com
DOMAIN=crm.example.com

# Email delivery
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USERNAME[email protected]
SMTP_PASSWORD=your-smtp-password
SMTP_AUTH=true
SMTP_STARTTLS=true

# Notification preference links (must match your public domain)
NOTIFICATIONS_PUBLIC_PREFERENCES_URL=https://crm.example.com/notifications/preferences

# Application
LOG_LEVEL=INFO
SPRING_PROFILES_ACTIVE=prod

# Client IP is auto-detected behind internal proxies and CDNs (Cloudflare included) — leave empty.
# Set only for an unusual proxy whose transport peer is a PUBLIC address to trust (IP/CIDR or hostname).
SECURITY_TRUSTED_PROXIES=

Faz backup do teu ficheiro .env antes do primeiro uso em produção. Guarda-o num gestor de passwords ou num cofre físico. O DB_ENCRYPTION_KEY é crítico — perdê-lo significa que os dados cifrados ficam perdidos para sempre.

Alternativa SMTP: Podes omitir as variáveis SMTP_* do .env e configurar o email mais tarde em Definições > SMTP de email no QuoteNode. O painel de administração armazena a password SMTP cifrada com DB_ENCRYPTION_KEY, mantendo-a fora do teu ficheiro .env.

Passo 3 — Rever o ficheiro Docker Compose

O docker-compose.yml do pacote executa a versão v0.9.8-alpha com cada imagem fixada por digest. Não o edites: todas as definições vão para o .env, e uma atualização substitui este ficheiro pelo da versão seguinte. Para referência:

x-json-file-logging: &json-file-logging
  driver: json-file
  options:
    max-size: "${DOCKER_LOG_MAX_SIZE:-10m}"
    max-file: "${DOCKER_LOG_MAX_FILE:-5}"

# ==========================================================================
# QuoteNode — standalone deployment (docker compose)
# GENERATED by scripts/render-deployment.mjs — do not edit by hand.
# Release v0.9.8-alpha (commit ff74453ca68f3c40bd86a32f0b0b813aaffc7aea, build 28); platforms: linux/amd64.
# API image:      ghcr.io/lesisty7/quotenode/quotenode-api@sha256:0ed701f952c27ea0e1db168a00de75facb231f7c6d5f6b4f0f3b77ef98d4f140
# Frontend image: ghcr.io/lesisty7/quotenode/quotenode-frontend@sha256:40a1cdc4fca5cebd9f43d34daef4ba059a88000ff08af821e199566f07260606
#
# Settings: the .env file in this directory (start from env.example, the commented catalogue of every
# setting; postgres, backend and backup-worker read it). Start: docker compose up -d
# DOMAIN: public host name for automatic HTTPS, or :80 / http://<address> for plain HTTP on a trusted LAN.
# Only the caddy entry point publishes ports (HTTP_PORT/HTTPS_PORT, default 80/443).
# Upgrades: replace this file with the next release package version; volumes keep the data.
# ==========================================================================

services:
  postgres:
    # Database (PostgreSQL 18); internal network only, data in the database volume.
    image: postgres:18-alpine@sha256:77f585114c32fbca283dc835b0596f4e52b51b4c6662d7810b2f4084f60a1873
    # JIT is off by default: for this OLTP workload most queries fall below jit_above_cost,
    # so JIT compilation rarely helps and can add latency. Set PG_JIT=on to re-enable.
    command: ["postgres", "-c", "jit=${PG_JIT:-off}"]
    env_file: .env
    environment:
      POSTGRES_DB: ${DB_NAME}
      POSTGRES_USER: ${DB_USERNAME}
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_INITDB_ARGS: "--data-checksums"
      # postgres:18 refuses to start on a bare /var/lib/postgresql/data mount (new default layout).
      # Pin PGDATA to the legacy path so the existing volume mount keeps working; major upgrades go
      # through a logical dump/restore, never an in-place upgrade of the data directory.
      PGDATA: /var/lib/postgresql/data
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${DB_USERNAME} -d ${DB_NAME}"]
      interval: 10s
      timeout: 5s
      retries: 10
    # CPU ceilings are opt-in (*_CPUS): 0 = no ceiling, all host cores. Docker refuses a ceiling above the
    # host's core count, so a fixed default would stop the stack on smaller hosts (minimum: 2 cores).
    cpus: ${POSTGRES_CPUS:-0}
    # Ceiling, not a reservation: PG sits at tens of MB until working set/connections grow.
    # Default 512m fits the 4 GB-VM profile; raise POSTGRES_MEM_LIMIT for larger tiers.
    mem_limit: ${POSTGRES_MEM_LIMIT:-512m}
    restart: unless-stopped
    logging: *json-file-logging
    # No published host port: the database is reachable only on the internal network.

  gotenberg:
    # PDF rendering (Chromium) for the backend; internal network only, keeps no data.
    image: gotenberg/gotenberg:8@sha256:aa552cc115db488e0f0bcb07446aac13071ad51505b642c84bb894500907b42b
    healthcheck:
      test: ["CMD", "curl", "-fsS", "http://localhost:3000/health"]
      interval: 10s
      timeout: 5s
      retries: 5
    cpus: ${GOTENBERG_CPUS:-0}
    # Chromium PDF rendering: measured ~188 MiB peak rendering a real offer template, so
    # 448m keeps ~2.4x headroom. Freed budget goes to backup-worker (closer to its limit).
    mem_limit: ${GOTENBERG_MEM_LIMIT:-448m}
    restart: unless-stopped
    logging: *json-file-logging

  backend:
    # API server (Java): business logic and web jobs; uploads, PDFs and the GeoIP database live in volumes.
    image: ghcr.io/lesisty7/quotenode/quotenode-api@sha256:0ed701f952c27ea0e1db168a00de75facb231f7c6d5f6b4f0f3b77ef98d4f140
    # Time Docker gives the backend between SIGTERM and SIGKILL. 60 s = the SMTP handoff hard limit
    # (mail.handoff.deadline-ms + end-of-data-allowance-ms = 25 s) + 5 s to record its outcome + the HTTP
    # graceful drain phase (30 s). A ceiling, not a delay: an idle backend exits in seconds.
    stop_grace_period: 60s
    depends_on:
      postgres:
        condition: service_healthy
      gotenberg:
        condition: service_healthy
    env_file: .env
    environment:
      SPRING_PROFILES_ACTIVE: prod
      JOBS_MODE: web
      # The caddy edge below is the backend's only HTTP peer, so it is the trusted proxy by default (security
      # finding #80); without it every request would appear to come from the edge container. Override only
      # for a custom proxy chain.
      SECURITY_TRUSTED_PROXIES: ${SECURITY_TRUSTED_PROXIES:-caddy}
      BACKUP_LOCAL_DIR: /app/data/backups
    volumes:
      - backend_uploads:/app/data/uploads
      - backend_pdfs:/app/data/pdfs
      - backend_backups:/app/data/backups
      - backend_geoip:/app/data/geoip
    healthcheck:
      test: ["CMD", "curl", "-fsS", "http://localhost:8080/health"]
      interval: 15s
      timeout: 10s
      retries: 5
      start_period: 45s
    cpus: ${BACKEND_CPUS:-0}
    # Heap auto-scales to 70% of this limit (MaxRAMPercentage); default 1536m → ~1 GB heap,
    # fits the 4 GB-VM profile. Raise BACKEND_MEM_LIMIT for heavier load (see resource docs).
    mem_limit: ${BACKEND_MEM_LIMIT:-1536m}
    restart: unless-stopped
    logging: *json-file-logging

  backup-worker:
    # Scheduled backups: same image as the backend, JOBS_MODE=backup-only; archives go to the backups volume.
    image: ghcr.io/lesisty7/quotenode/quotenode-api@sha256:0ed701f952c27ea0e1db168a00de75facb231f7c6d5f6b4f0f3b77ef98d4f140
    depends_on:
      postgres:
        condition: service_healthy
      backend:
        condition: service_healthy
    env_file: .env
    environment:
      SPRING_PROFILES_ACTIVE: prod
      JOBS_MODE: backup-only
      BACKUP_LOCAL_DIR: /app/data/backups
      # Worker runs pg_dump in a shell (out-of-JVM) and never does web/import heap work,
      # so it needs little heap. On this small 768m container the ~350 MB fixed non-heap
      # cost makes the global MaxRAMPercentage=70 (538 MB heap → 888 MB total) unsafe.
      # Cap heap lower so heap_max + non-heap stays well under the limit.
      JAVA_OPTS: "-XX:MaxRAMPercentage=45.0 -XX:+UseG1GC -XX:G1PeriodicGCInterval=300000"
    volumes:
      - backend_uploads:/app/data/uploads
      - backend_pdfs:/app/data/pdfs
      - backend_backups:/app/data/backups
      - backend_geoip:/app/data/geoip
    healthcheck:
      test: ["CMD", "curl", "-fsS", "http://localhost:8080/health"]
      interval: 15s
      timeout: 10s
      retries: 5
      # JVM boots a large Spring context (CPU-bound); the grace window must outlast
      # cold start to avoid a false-unhealthy restart loop under load.
      start_period: 300s
    # CPU is a ceiling (idle cost ~0); give the worker enough to boot fast and to run
    # pg_dump + age-encryption/compression bursts without throttling. Idles near zero CPU.
    cpus: ${WORKER_CPUS:-0}
    # Default 832m: measured backup peak (JVM idle + pg_dump + tar + gzip) is ~607 MiB, so
    # this keeps a ~27% margin. Do NOT set WORKER_MEM_LIMIT below ~768m or backups risk OOM.
    mem_limit: ${WORKER_MEM_LIMIT:-832m}
    restart: unless-stopped
    logging: *json-file-logging

  frontend:
    # Web UI: the static build served by Caddy, reached through the caddy entry point.
    image: ghcr.io/lesisty7/quotenode/quotenode-frontend@sha256:40a1cdc4fca5cebd9f43d34daef4ba059a88000ff08af821e199566f07260606
    depends_on:
      backend:
        condition: service_healthy
    healthcheck:
      test: ["CMD", "curl", "-fsS", "http://localhost:80/"]
      interval: 15s
      timeout: 5s
      retries: 3
    cpus: ${FRONTEND_CPUS:-0}
    # Prod frontend is Caddy serving the static build (measured ~46 MiB peak under load); 96m is ample.
    # CPU is a free ceiling, so headroom for concurrent connections costs nothing at idle.
    mem_limit: ${FRONTEND_MEM_LIMIT:-96m}
    restart: unless-stopped
    logging: *json-file-logging

  caddy:
    # Entry point: the only published ports (HTTP_PORT/HTTPS_PORT, default 80/443), TLS for DOMAIN, routing, security headers.
    image: ghcr.io/lesisty7/quotenode/quotenode-frontend@sha256:40a1cdc4fca5cebd9f43d34daef4ba059a88000ff08af821e199566f07260606
    # The released frontend image carries the edge config (frontend/caddy/Caddyfile.edge) and the Cloudflare
    # ranges, so the edge needs no host files. Same image digest as the frontend service.
    command: ["caddy", "run", "--config", "/etc/caddy/Caddyfile.edge", "--adapter", "caddyfile"]
    depends_on:
      backend:
        condition: service_healthy
      frontend:
        condition: service_healthy
    environment:
      # Site address for frontend/caddy/Caddyfile.edge: a public host name enables automatic HTTPS; ":80" or
      # "http://host" serves plain HTTP on a trusted LAN. Required: an empty site address is not a valid config.
      DOMAIN: ${DOMAIN:?set DOMAIN to the public host name, or :80 for plain HTTP on a LAN}
      # Optional: address(es) of an operator reverse proxy in front of this edge (default: trust none).
      EDGE_TRUSTED_PROXIES: ${EDGE_TRUSTED_PROXIES:-}
    ports:
      - "${HTTP_PORT:-80}:80"
      - "${HTTPS_PORT:-443}:443"
      - "${HTTPS_PORT:-443}:443/udp"      # HTTP/3 (QUIC)
    volumes:
      - caddy_data:/data
      - caddy_config:/config
    # caddy is the single ingress (TLS, HTTP/3/QUIC, proxying all traffic); give it
    # cores for handshake/encryption bursts under load. CPU idle cost ~0.
    cpus: ${CADDY_CPUS:-0}
    # 96m fits the 4 GB / light-traffic profile. Under heavy TLS load (many concurrent
    # handshakes, large QUIC buffers) raise CADDY_MEM_LIMIT — this ingress is untested at scale.
    mem_limit: ${CADDY_MEM_LIMIT:-96m}
    restart: unless-stopped
    logging: *json-file-logging

# Persistent data: database, uploads, generated PDFs, local backup archives, GeoIP database and the entry
# point's certificates/config. Docker prefixes each name with the Compose project name (by default the
# directory name), so keep the project name across upgrades.
volumes:
  postgres_data:
  backend_uploads:
  backend_pdfs:
  backend_backups:
  backend_geoip:
  caddy_data:
  caddy_config:

DOMAIN define como o ponto de entrada caddy serve o QuoteNode: um nome de anfitrião público (crm.example.com) recebe automaticamente um certificado HTTPS; http://<endereço> ou :80 serve HTTP simples numa rede de confiança. Se as portas 80/443 já estiverem ocupadas, define HTTP_PORT / HTTPS_PORT no .env. Atrás do teu próprio proxy inverso, define DOMAIN=:80 e indica o endereço do proxy em EDGE_TRUSTED_PROXIES.

Passo 4 — Configurar o firewall

Abre apenas o necessário:

ufw allow OpenSSH
ufw allow 80/tcp
ufw allow 443/tcp
ufw enable

Não expões o PostgreSQL publicamente. Fica na rede Docker.

Passo 5 — Iniciar o QuoteNode

docker compose up -d

Acompanha o arranque:

docker compose logs -f backend

Aguarda a mensagem Started QuoteNodeApplication. O contentor do ponto de entrada (caddy) obtém automaticamente um certificado Let’s Encrypt para o nome de anfitrião em DOMAIN.

Passo 6 — Abrir o QuoteNode

Navega para https://crm.example.com no teu browser.

Credenciais de acesso predefinidas:

Campo	Valor
Email	`[email protected]`
Password	`Admin123!`

Altera a password predefinida imediatamente após iniciar sessão.

Verificações pós-deployment

Iniciar sessão e alterar a password admin.
Criar uma proposta de teste.
Gerar um PDF.
Criar e abrir um link público a partir de outro dispositivo.
Se o SMTP estiver configurado, enviar uma notificação de teste e verificar que os links do email funcionam.

O que está a correr?

Container	O que faz	Uso de RAM
`postgres`	Armazena todos os teus dados	~256 MB
`backend`	Servidor API Java, lógica de negócio	~512 MB – 1,5 GB
`gotenberg`	Converte HTML para PDF (baseado em Chromium)	~200 MB
`frontend`	Serve a interface web	~20 MB
`backup-worker`	Executa as cópias de segurança agendadas (mesma imagem do backend)	~300 MB
`caddy`	Ponto de entrada: certificados HTTPS, roteamento, cabeçalhos de segurança	~20 MB

Total: aproximadamente 1,5 – 2,5 GB de RAM.

Comandos habituais

# Check service status
docker compose ps

# View logs
docker compose logs -f backend

# Stop QuoteNode
docker compose down

# Atualização: substitui o docker-compose.yml pelo do pacote da versão seguinte (consulta o guia de atualização)

Checklist de upgrade

Antes de cada upgrade:

Confirma a versão atual da app na área de administração.
Faz backup do .env.
Corre ou verifica um backup fresco da base de dados.
Faz pull das novas imagens e reinicia.
Verifica health do backend, login, geração de PDF e um link público de proposta.

Manter os teus segredos seguros

Segredo	O que protege	Se perdido
`DB_PASSWORD`	Acesso à base de dados	Recuperável — reiniciar via ferramentas de administração PostgreSQL
`DB_ENCRYPTION_KEY`	Códigos MFA, password SMTP, chave API FX, campos PII	Permanentemente ilegível
`TIMING_TOKEN_SECRET`	Tokens anti-timing-attack	Regenerar — utilizadores re-autenticam-se
`PUBLIC_LINK_PASSWORD_SESSION_SECRET`	Sessões de links públicos	Regenerar — as sessões ativas expiram

Guarda o .env num gestor de passwords (1Password, Bitwarden). Para máxima segurança, imprime os segredos e guarda a impressão numa caixa-forte física. Nunca faças commit do .env no controlo de versão.

Recuperação se `.env` for perdido

Se perderes o teu ficheiro .env mas tiveres uma cópia de segurança da base de dados não cifrada (o modo padrão):

Cria um novo .env com novos segredos.
Restaura a base de dados a partir da tua cópia de segurança.
Todos os dados de negócio serão acessíveis.
Perdidos: códigos MFA (utilizadores re-inscrevem-se), password SMTP (reinserir), chave API FX (reinserir). Se ENCRYPT_PII=true estava ativo, os dados de clientes cifrados também são perdidos.

Instalar num Servidor Público Ubuntu

Quando usar

O que não vai funcionar sem configuração adequada

Pré-requisitos

Passo 1 — Criar uma diretoria de projeto

Passo 2 — Criar o ficheiro de configuração

Passo 3 — Rever o ficheiro Docker Compose

Passo 4 — Configurar o firewall

Passo 5 — Iniciar o QuoteNode

Passo 6 — Abrir o QuoteNode

Verificações pós-deployment

O que está a correr?

Comandos habituais

Checklist de upgrade

Manter os teus segredos seguros

Recuperação se .env for perdido

Recuperação se `.env` for perdido