Basics

Guia de instalacao

Como colocar o QuoteNode em producao na tua propria infraestrutura usando Docker Compose.

Instalacao

O QuoteNode corre como um conjunto de contentores Docker. Nao precisas de instalar Java, Node.js ou PostgreSQL na maquina: o Docker trata disso.

Pre-requisitos

Docker Engine 24.0 ou superior (instalar Docker)
Docker Compose v2
Uma maquina com pelo menos 2 GB de RAM e 10 GB de espaco livre

Verifica o ambiente com:

docker --version        # Deve mostrar 24.0+
docker compose version  # Deve mostrar v2.x

Arranque rapido

Isto coloca o QuoteNode a correr localmente para avaliacao. Nao e um setup de producao; para isso, ve a secao mais abaixo.

Passo 1 - Criar a diretoria de projeto

mkdir quotenode && cd quotenode

Passo 2 - Criar o ficheiro `.env`

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

# ============================================================
# SEGREDOS DE SEGURANCA - LER ANTES DE CONTINUAR
# Estes valores sao UNICOS para a tua instalacao.
# Se perderes este ficheiro, NAO consegues regenerar os mesmos segredos.
# GUARDA ESTE FICHEIRO e mantem um backup seguro.
# ============================================================
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

# Dominio
CORS_ALLOWED_ORIGINS=http://localhost
DOMAIN=localhost

# Logging
LOG_LEVEL=INFO
SPRING_PROFILES_ACTIVE=prod

Guarda o ficheiro .env imediatamente. Os segredos acima sao unicos para esta instalacao. Se perderes o ficheiro, nao consegues regenerar os mesmos valores. Sem o DB_ENCRYPTION_KEY original, os dados cifrados, como codigos MFA, password SMTP, chaves API e campos PII opcionais, tornam-se permanentemente ilegiveis.

Passo 3 - Criar o `docker-compose.yml`

Cria um ficheiro chamado docker-compose.yml:

services:
  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: ${DB_NAME}
      POSTGRES_USER: ${DB_USERNAME}
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${DB_USERNAME}"]
      interval: 10s
      timeout: 5s
      retries: 10
    restart: unless-stopped

  gotenberg:
    image: gotenberg/gotenberg:8
    environment:
      LOG_LEVEL: info
    healthcheck:
      test: ["CMD", "curl", "-fsS", "http://localhost:3000/health"]
      interval: 10s
      timeout: 5s
      retries: 5
    restart: unless-stopped

  backend:
    image: ghcr.io/lesisty7/quotenode/quotenode-api:latest
    depends_on:
      postgres: { condition: service_healthy }
      gotenberg: { condition: service_healthy }
    env_file: .env
    environment:
      SPRING_PROFILES_ACTIVE: prod
      JOBS_MODE: web
      PDF_ENABLED: "true"
      PDF_GOTENBERG_URL: http://gotenberg:3000
    volumes:
      - backend_uploads:/app/data/uploads
      - backend_pdfs:/app/data/pdfs
    healthcheck:
      test: ["CMD", "curl", "-fsS", "http://localhost:8080/health"]
      interval: 15s
      timeout: 10s
      retries: 5
      start_period: 45s
    restart: unless-stopped

  frontend:
    image: ghcr.io/lesisty7/quotenode/quotenode-frontend:latest
    depends_on:
      backend: { condition: service_healthy }
    ports:
      - "80:80"
      - "443:443"
    healthcheck:
      test: ["CMD", "curl", "-fsS", "http://localhost:80/"]
      interval: 15s
      timeout: 5s
      retries: 3
    restart: unless-stopped

volumes:
  postgres_data:
  backend_uploads:
  backend_pdfs:

Passo 4 - Arrancar o QuoteNode

docker compose up -d

Podes acompanhar o arranque com:

docker compose logs -f backend

Espera ate aparecer uma linha semelhante a Started QuoteNodeApplication. Isso significa que o backend esta pronto.

Passo 5 - Abrir a aplicacao

Abre http://localhost no browser.

Credenciais iniciais:

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

Altera a password imediatamente apos o primeiro login.

O que fica a correr

Depois do docker compose up, tens quatro contentores:

Contentor	Funcao	RAM tipica
`postgres`	Armazena todos os dados	~256 MB
`backend`	API Java, regras de negocio, jobs	~512 MB - 1.5 GB
`gotenberg`	Converte HTML em PDF	~200 MB
`frontend`	Serve o UI web e faz proxy	~20 MB

Total esperado: aproximadamente 1.5 - 2.5 GB de RAM.

Comandos comuns

# Verificar se todos os servicos estao a correr
docker compose ps

# Ver logs de todos os servicos
docker compose logs -f

# Ver apenas logs do backend
docker compose logs -f backend

# Parar QuoteNode
docker compose down

# Atualizar para a versao mais recente
docker compose pull && docker compose up -d

Proteger os teus segredos

O ficheiro .env contem segredos criptograficos unicos da tua instalacao. Convem perceber o que cada segredo protege:

Segredo	O que protege	Se for perdido
`DB_PASSWORD`	Acesso a base de dados	Recuperavel com ferramentas de admin PostgreSQL
`DB_ENCRYPTION_KEY`	MFA, password SMTP, chave FX e PII quando `ENCRYPT_PII=true`	Irrecuperavel sem a chave original
`TIMING_TOKEN_SECRET`	Tokens anti timing attack	Regeneravel, invalidando tokens antigos
`PUBLIC_LINK_PASSWORD_SESSION_SECRET`	Sessoes de links publicos protegidos por password	Regeneravel, expirando sessoes ativas

O segredo critico e o DB_ENCRYPTION_KEY. Os restantes podem ser regenerados com algum impacto operacional. A chave de cifragem da base de dados nao pode ser reconstituida.

Para producao, recomendamos:

guardar uma copia do .env num password manager
manter uma copia offline segura, ou mesmo uma impressao em cofre
nunca fazer commit do .env para controlo de versoes

Recuperacao se perderes `.env`

Se perderes o .env mas tiveres um backup da base de dados nao cifrado, ainda podes restaurar a maior parte dos dados:

cria um novo .env com segredos novos
restaura a base de dados a partir do teu backup
volta a arrancar a stack
reconfigura os poucos campos cifrados que dependiam da chave antiga

Sem a chave original, deixam de ser legiveis os codigos MFA, a password SMTP, algumas chaves API e, se ENCRYPT_PII=true estiver ativo, tambem os campos PII cifrados.

Deployment de producao

Para producao, precisas de:

gerar segredos reais
configurar dominio e HTTPS
configurar email
fazer backup do .env
ativar backups de base de dados
rever as variaveis de ambiente

Gerar segredos adequados

Em producao, nunca uses valores de exemplo:

# Gerar chave hex de 64 caracteres para cifragem da base de dados
openssl rand -hex 32

# Gerar segredos aleatorios para tokens
openssl rand -base64 32

Configurar dominio e HTTPS

O dominio publico e o CORS devem ficar alinhados com o hostname real. Quando o deployment usa Caddy integrado, a emissao de certificados HTTPS pode ser automatizada.

Preparar email

O email pode ser configurado por variaveis de ambiente ou mais tarde no painel administrativo.

Preferivel: configurar SMTP em Settings > Email SMTP na propria app
Fallback: definir SMTP no .env se precisares que o email esteja pronto antes do primeiro login admin

SMTP_HOST=smtp.yourprovider.com
SMTP_PORT=587
SMTP_USERNAME=[email protected]
SMTP_PASSWORD=your-smtp-password
SMTP_AUTH=true
SMTP_STARTTLS=true

Rever backups e disaster recovery

Antes de considerar a instalacao pronta, convem validar onde os backups vao ficar, como serao testados e onde sera guardada a copia segura do .env.

Rever defaults operacionais

Depois do deploy, faz sentido verificar branding, moeda base, IVA, notificacoes e templates base antes de a equipa comecar a usar propostas reais.

Atualizar QuoteNode

Para atualizar:

docker compose pull && docker compose up -d

O .env nao deve ser recriado ou apagado durante updates.

Resolução de problemas

O backend nao arranca

Confirma:

logs do backend
disponibilidade da base de dados
validade dos segredos
conflitos de portas
estado do Gotenberg

Nao consigo aceder ao QuoteNode

Confirma o estado dos contentores, o health check do frontend, o URL correto e o reverse proxy usado no ambiente.

Esqueci-me da password admin

Usa antes um caminho de recuperacao nao destrutivo:

Se o SMTP estiver configurado, comeca pelo fluxo no ecran de login: Esqueceu-se da sua palavra-passe?
Se outro administrador ainda conseguir entrar, abre Users no painel administrativo e redefine a password a partir dessa vista. Os administradores podem definir uma nova password e forcar a alteracao no proximo login.
Se nenhum administrador conseguir entrar e o reset por email nao estiver disponivel, trata o caso como um incidente de recuperacao operacional. Recupera o acesso a partir de um backup valido ou usa o procedimento interno de manutencao adequado a esse ambiente.

docker compose down -v nao e um procedimento de reset de password. Esse comando recria toda a instancia e apaga todos os dados persistidos, incluindo utilizadores, propostas, clientes, configuracoes e backups locais. Usa-o apenas em ambientes locais descartaveis quando quiseres reiniciar deliberadamente toda a instancia.

Ver tambem: Redefinir uma password e Backup e recuperacao.

Proximos passos

O que validar apos a instalacao

Depois do primeiro arranque, convem confirmar:

login administrativo
acesso ao frontend e a API
criacao de uma proposta de teste
geracao de PDF
funcionamento do armazenamento de uploads
coerencia do locale e dos defaults comerciais

Boas praticas para producao

Em producao, faz sentido:

usar segredos fortes e guardados offline
definir uma estrategia de backup antes do go-live
validar branding e templates base
rever limites de sessao e politicas de seguranca
confirmar que o dominio e o CORS estao alinhados com o ambiente real
testar pelo menos um restore antes de considerares o sistema pronto