Operations
Referencia de variaveis de ambiente
Referencia completa das variaveis de ambiente do QuoteNode para producao, desenvolvimento, Docker Compose e operacao.
Variaveis de ambiente
As variaveis de ambiente controlam comportamentos criticos do QuoteNode. Devem ser geridas como parametros sensiveis de infraestrutura.
Como ler esta referencia
- Prod significa que a variavel pertence ao
.envde producao - Dev significa desenvolvimento local ou stacks de demo
- Compose significa wiring do Docker Compose no host, nao da aplicacao em si
- defaults vazios significam normalmente “define explicitamente quando precisares desta feature”
Variaveis de Compose e stack local
Estas variaveis moldam o ambiente local em Docker Compose e o proxy dev do frontend.
| Variavel | Ambito | Objetivo | Valor tipico |
|---|---|---|---|
COMPOSE_PROJECT_NAME |
Dev / Compose | Evita colisoes de nomes de contentores | quotenode-dev |
POSTGRES_PORT |
Dev / Compose | Porta host mapeada para PostgreSQL | 5433, 5434 |
PG_JIT |
Dev / Compose | Compilacao JIT do PostgreSQL. Desativada por padrao — raramente ajuda nesta carga OLTP. Defina on para ativar. |
off |
MAILPIT_PORT |
Dev / Compose | Porta da UI do Mailpit | 8025, 8026 |
BACKEND_PORT |
Dev / Compose | Porta host da API backend | 8091, 8092 |
FRONTEND_PORT |
Dev / Compose | Porta host do frontend | 5174, 5175 |
VITE_PUBLIC_API_BASE |
Dev / Frontend | URL base da API visivel no browser | http://localhost:8091 |
APP_VERSION |
Prod / Dev / Compose | Tag de imagem Docker selecionada | latest |
APP_CHANNEL |
Prod / Dev / Compose | Canal de release embebido nos metadados de build e labels da UI | alpha, stable |
VITE_RELEASE_CHECK_ENABLED |
Prod / Dev / Frontend | Ativa a verificacao de releases upstream (apenas admin) | true, false |
VITE_RELEASE_MANIFEST_URL |
Prod / Dev / Frontend | URL do manifesto JSON publico para verificacao de releases | https://quotenode.dev/releases/latest.json |
PROXY_MODE |
Prod / Dev / Compose | Define se o Caddy corre interno ou externo | internal, external |
DOMAIN |
Prod / Compose | Dominio publico usado por Caddy e URLs publicos | quotenode.example.com |
SECURITY_TRUSTED_PROXIES |
Prod / Dev / Compose | Normalmente vazio — o IP do cliente é detetado automaticamente atrás de proxies internos (gamas privadas/loopback) e CDNs como a Cloudflare (via CF-Connecting-IP). Os cabeçalhos de reencaminhamento de um par direto (não interno) são ignorados. Defina apenas para um proxy invulgar cujo par de transporte seja um endereço público. |
vazio, 203.0.113.5/32 |
Base de dados e runtime
| Variavel | Ambito | Objetivo | Valor tipico |
|---|---|---|---|
DB_URL |
Prod / Dev | String JDBC para PostgreSQL | jdbc:postgresql://postgres:5432/quotenode |
DB_USERNAME |
Prod / Dev | Utilizador da base de dados | quotenode |
DB_PASSWORD |
Prod / Dev | Password da base de dados | 32+ chars em prod |
DB_NAME |
Prod / Dev / Compose | Nome da base de dados | quotenode |
DB_AUTO_MIGRATE |
Prod / Dev | Migracao automatica de versao principal do PostgreSQL no arranque (usada pelo stack-up.sh). Desativada por padrao; quando true, um volume de dados mais antigo e copiado e migrado antes do stack iniciar. |
false |
SPRING_PROFILES_ACTIVE |
Prod / Dev | Perfil Spring ativo | prod, dev |
CORS_ALLOWED_ORIGINS |
Prod / Dev | Origins permitidas para o browser | https://yourdomain.com |
LOG_LEVEL |
Prod / Dev | Verbosidade base dos logs | ERROR, INFO, DEBUG |
Rotacao de logs Docker e diagnostico
| Variavel | Ambito | Objetivo | Valor tipico |
|---|---|---|---|
DOCKER_LOG_MAX_SIZE |
Prod / Compose | Tamanho maximo de um ficheiro de log antes de rotacao | 10m |
DOCKER_LOG_MAX_FILE |
Prod / Compose | Numero de ficheiros de log retidos | 5 |
SUPPORT_LOGS_BUFFER_SIZE |
Prod | Tamanho do buffer de preview de logs | 4000 |
SUPPORT_LOGS_PREVIEW_RATE_LIMIT_PER_MINUTE |
Prod | Rate limit para preview de logs | 30 |
SUPPORT_LOGS_LOG_LEVEL_DEFAULT_TTL_MINUTES |
Prod | Tempo de expiracao do override temporario de log level | 15 |
SUPPORT_LOGS_LOG_LEVEL_MAX_TTL_MINUTES |
Prod | Janela maxima para elevar log level | 30 |
SUPPORT_LOGS_LOG_LEVEL_ALLOWED_SCOPES |
Prod | Scopes de pacote que podem ser elevados temporariamente para diagnostico | dev.quotenode,... |
Seguranca, autenticacao e sessao
| Variavel | Ambito | Objetivo | Valor tipico |
|---|---|---|---|
DB_ENCRYPTION_KEY |
Prod / Dev | Chave principal de cifragem aplicacional | 64 chars hex |
TIMING_TOKEN_SECRET |
Prod / Dev | Segredo HMAC para protecao anti-bot | 32+ chars |
PUBLIC_LINK_PASSWORD_SESSION_SECRET |
Prod / Dev | Segredo de sessao para links publicos protegidos | 32+ chars |
AUTH_PASSWORD_MIN_LENGTH |
Prod / Dev | Comprimento minimo de password | 12, 8 |
AUTH_PASSWORD_COMPLEXITY_LEVEL |
Prod / Dev | Nivel de complexidade exigido | 2, 1 |
AUTH_SESSION_IDLE_TIMEOUT_MIN |
Prod / Dev | Timeout por inatividade | 30, 480 |
SECURITY_SESSION_ABSOLUTE_TIMEOUT_H |
Prod / Dev | Duracao maxima absoluta da sessao | 12, 24 |
SECURITY_MAX_FAILED_LOGINS_SOFT |
Prod / Dev | Limite de falhas para aviso | 5, 10 |
SECURITY_MAX_FAILED_LOGINS_TEMP_LOCK |
Prod / Dev | Limite para bloqueio temporario | 10, 20 |
SECURITY_MAX_FAILED_LOGINS_HARD_LOCK |
Prod / Dev | Limite para bloqueio forte | 20, 50 |
SECURITY_TEMP_LOCK_MINUTES |
Prod / Dev | Duracao do bloqueio temporario | 30, 5 |
FEATURE_2FA_ENABLED |
Prod / Dev | Ativa fluxos de 2FA | true, false |
SECURITY_REQUIRE_2FA_ROLES |
Prod / Dev | Perfis obrigados a ativar 2FA | ADMIN |
SECURITY_BOT_DETECTION_ENABLED |
Prod / Dev | Ativa camada de bot detection | true, false |
SECURITY_BOT_SCORE_WARN_THRESHOLD |
Prod / Dev | Threshold de bot score para apenas avisar | 30 |
SECURITY_BOT_SCORE_BLOCK_THRESHOLD |
Prod / Dev | Threshold de bot score para bloquear | 70 |
SECURITY_IP_WHITELIST |
Prod / Dev | Lista de permissões de IP imposta pelo operador (IP/CIDR literais separados por vírgulas). Quando ativa, a lista protege toda a superfície de administração — início de sessão, o desafio 2FA e cada rota de administração autenticada — deixando acessíveis apenas os endpoints de saúde/infraestrutura e os públicos para clientes. Quando definida, prevalece sobre a lista do tenant na aplicação e é só de leitura na interface; uma lista do operador é aplicada no arranque sem reversão automática, por isso confirme que o seu próprio endereço está abrangido. Vazio = aplica-se a definição do tenant (se existir). Resolve clientes através de SECURITY_TRUSTED_PROXIES. |
vazio, 203.0.113.10,198.51.100.0/24 |
SECURITY_IP_WHITELIST_FORCE_DISABLE |
Runtime override | Substituição de emergência que desativa a aplicação da whitelist de IP armazenada (verificada antes de qualquer análise da lista, pelo que também recupera de uma lista armazenada inválida — e, como a whitelist agora protege o início de sessão, restaura a capacidade de entrar). Reinício necessário; apenas ENV, nunca a partir da interface. Desativa apenas a whitelist de IP — não o GeoIP, a deteção de bots ou o rate limiting. | false |
SECURITY_IP_WHITELIST_CONFIRMATION_WINDOW_SECONDS |
Prod / Dev | Quanto tempo uma ativação/restrição da whitelist na aplicação fica pendente de reconfirmação antes de reverter automaticamente para a lista anterior (segurança contra bloqueios). A sessão em edição confirma automaticamente quando o seu endereço atual está abrangido. | 120 |
Estas variaveis definem o baseline de seguranca da instancia. Devem ser revistas explicitamente antes de qualquer go-live.
CRM, ficheiros, importacoes e media de produto
| Variavel | Ambito | Objetivo | Valor tipico |
|---|---|---|---|
CRM_DEDUP_NAME_SIMILARITY_THRESHOLD |
Prod / Dev | Threshold de similaridade para aviso de duplicados | 0.8 |
CRM_DEDUP_EMAIL_DOMAIN_WARN |
Prod / Dev | Aviso quando dominios de email coincidem | true |
CRM_ATTACHMENT_MAX_SIZE_MB |
Prod / Dev | Tamanho maximo de anexos CRM | 25 |
CRM_ATTACHMENT_ALLOWED_TYPES |
Prod / Dev | Extensoes permitidas para anexos CRM | pdf,doc,docx,... |
CSV_IMPORT_MAX_ROWS |
Prod / Dev | Limite de linhas em importacoes CSV de CRM | 5000 |
APP_PRODUCT_IMPORT_MAX_ROWS |
Prod / Dev | Limite de linhas em importacoes de produtos (CSV/XLSX) | 50000 |
STORAGE_PATH |
Prod / Dev | Diretoria raiz para uploads | /data/uploads |
PIM_MEDIA_MAX_SIZE_MB |
Prod / Dev | Tamanho maximo de uma imagem de produto | 3 |
PIM_MEDIA_MAX_PER_PRODUCT |
Prod / Dev | Numero maximo de media por produto | 5 |
PIM_MEDIA_THUMBNAIL_WIDTH |
Prod / Dev | Largura da miniatura usada no processamento de imagem | 300 |
PIM_MEDIA_ALLOWED_TYPES |
Prod / Dev | Extensoes de media permitidas | jpg,jpeg,png,webp,svg |
PIM_MEDIA_MAX_MEGAPIXELS |
Prod / Dev | Rejeita imagens cujas dimensoes em pixels excedem estes megapixels — verificado no cabecalho antes da descodificacao completa (protecao de memoria contra bombas de descompressao) | 40 |
PIM_MEDIA_OPTIMIZE_ENABLED |
Prod / Dev | Redimensiona e recodifica o original armazenado no upload; false mantem os originais inalterados |
true |
PIM_MEDIA_OPTIMIZE_MAX_DIMENSION |
Prod / Dev | Limite do lado maior (px) para o original armazenado quando a otimizacao esta ativa | 2560 |
PIM_MEDIA_OPTIMIZE_QUALITY |
Prod / Dev | Qualidade de recodificacao JPEG (0.0–1.0) na otimizacao de imagens | 0.85 |
IMPORT_ZIP_MAX_SIZE_MB |
Prod / Dev | Tamanho maximo do ZIP para importacao de imagens em lote | 100 |
IMPORT_ZIP_MAX_IMAGES |
Prod / Dev | Numero maximo de imagens dentro de um ZIP | 1000 |
IMPORT_IMAGE_MAX_SIZE_MB |
Prod / Dev | Tamanho maximo de uma imagem dentro do ZIP | 5 |
IMPORT_IMAGE_FUZZY_THRESHOLD |
Prod / Dev | Threshold de correspondencia difusa nome-de-ficheiro→produto | 0.82 |
MULTIPART_MAX_FILE_SIZE |
Prod / Dev | Teto global para um unico ficheiro carregado (envelope de upload; os limites por funcionalidade sao mais restritos) | 200MB |
MULTIPART_MAX_REQUEST_SIZE |
Prod / Dev | Teto global para um pedido multipart inteiro | 220MB |
MULTIPART_FILE_SIZE_THRESHOLD |
Prod / Dev | Uploads acima deste tamanho vao para um ficheiro temporario em vez de memoria | 2MB |
Email, links publicos e notificacoes
| Variavel | Ambito | Objetivo | Valor tipico |
|---|---|---|---|
SMTP_HOST |
Prod / Dev | Hostname do servidor SMTP | provider ou localhost |
SMTP_PORT |
Prod / Dev | Porta SMTP | 587, 1025, 1026 |
SMTP_USERNAME |
Prod / Dev | Username SMTP | conta do provider |
SMTP_PASSWORD |
Prod / Dev | Password SMTP | segredo |
SMTP_AUTH |
Prod / Dev | Ativa autenticacao SMTP | true, false |
SMTP_STARTTLS |
Prod / Dev | Ativa STARTTLS | true, false |
PUBLIC_LINK_TOKEN_BYTES |
Prod / Dev | Entropia dos tokens de links publicos | 32 |
PUBLIC_LINK_DEFAULT_EXPIRY_DAYS |
Prod / Dev | Validade por defeito do link publico | 0 |
PUBLIC_RATE_LIMIT_OPEN_PER_HOUR |
Prod / Dev | Limite horario de abertura | 60, 999 |
PUBLIC_RATE_LIMIT_ACTION_PER_HOUR |
Prod / Dev | Limite horario para acoes publicas | 5, 999 |
NOTIFICATIONS_ENABLED |
Prod / Dev | Ativa subsistema de notificacoes | true |
NOTIFICATIONS_EMAIL_ENABLED |
Prod / Dev | Ativa entrega email de notificacoes | true, false |
NOTIFICATIONS_PUBLIC_PREFERENCES_URL |
Prod | URL publico para gestao de preferencias de notificacao | https://yourdomain.com/notifications/preferences |
NOTIFICATIONS_PREFERENCE_TOKEN_TTL_DAYS |
Prod | Validade do token dos links de preferencias | 30 |
NOTIFICATIONS_OFFER_EXPIRY_WARN_DAYS |
Prod / Dev | Agenda de lembrete antes da expiracao de propostas | 7,2 |
NOTIFICATIONS_LICENSE_EXPIRY_WARN_DAYS |
Prod / Dev | Agenda de lembrete antes da expiracao de licencas | 30,14,7,1 |
REMINDERS_JOB_INTERVAL_MINUTES |
Prod / Dev | Cadencia de polling dos jobs de lembrete | 5 |
CLIENT_CONFIRM_EMAIL_ENABLED |
Prod / Dev | Envia email de confirmacao ao cliente apos aceitacao | false |
TRACKING_IP_ANONYMIZE |
Prod / Dev | Ativa anonimizacao de IP nos dados de tracking | false |
TRACKING_IP_ANONYMIZE_AFTER_DAYS |
Prod / Dev | Periodo de anonimizacao diferida dos IPs de tracking | 0 |
TRACKING_RETENTION_DAYS |
Prod / Dev | Janela de retencao dos dados de tracking de links publicos | 365 |
Shipping, FX e defaults de proposta
| Variavel | Ambito | Objetivo | Valor tipico |
|---|---|---|---|
SHIPPING_DEFAULT_VOLUMETRIC_DIVISOR |
Prod / Dev | Divisor para peso volumetrico | 4000 |
SHIPPING_OVERRIDE_REQUIRES_REASON |
Prod / Dev | Obriga justificacao para override de shipping | true |
FX_PROVIDER |
Prod / Dev | Fonte das taxas FX | NBP, ECB, CUSTOM |
FX_PROVIDER_URL |
Prod / Dev | URL custom do provider FX | vazio ou URL |
FX_REFRESH_INTERVAL_MIN |
Prod / Dev | Cadencia de refresh das taxas | 60 |
FX_DEFAULT_MARGIN_PERCENT |
Prod / Dev | Margem default aplicada sobre a taxa | 0 |
FX_DEVIATION_WARN_PERCENT |
Prod / Dev | Threshold de aviso para taxas FX ajustadas manualmente | 3 |
FX_DEVIATION_BLOCK_PERCENT |
Prod / Dev | Threshold de bloqueio para taxas FX ajustadas manualmente | 8 |
OFFER_NUMBER_PREFIX |
Prod / Dev | Prefixo de numeracao das propostas | OF |
| Variavel | Ambito | Objetivo | Valor tipico |
|---|---|---|---|
PDF_ENABLED |
Prod / Dev | Ativa geracao PDF | true, false |
PDF_GOTENBERG_URL |
Prod / Dev | URL interna do servico Gotenberg | http://gotenberg:3000 |
PDF_SYNC_TIMEOUT_MS |
Prod / Dev | Timeout para pedidos sincronos de PDF | 10000 |
PDF_SYNC_MAX_ITEMS |
Prod / Dev | Numero maximo de linhas para modo sincrono | 50 |
PDF_STORAGE_PATH |
Prod / Dev | Caminho do filesystem para PDFs gerados | /data/pdfs |
PDF_RETENTION_DAYS |
Prod / Dev | Periodo de retencao dos PDFs | 365 |
PDF_RETRY_BACKOFF_SECONDS |
Prod / Dev | Agenda de retry para jobs PDF assincronos | 30,120,600 |
PDF_WORKER_CONCURRENCY |
Prod / Dev | Concorrencia dos workers de PDF | 2 |
PDF_WORKER_POLL_INTERVAL_MS |
Prod / Dev | Intervalo de polling para jobs PDF | 2000 |
Licenciamento, relatorios e manutencao
| Variavel | Ambito | Objetivo | Valor tipico |
|---|---|---|---|
LICENSE_SKIP_SIGNATURE_CHECK |
Prod / Dev | Salta validacao de assinatura da licenca | false |
LICENSE_EXPIRY_CHECK_INTERVAL_H |
Prod / Dev | Cadencia de verificacao da expiracao | 24 |
REPORTS_DEFAULT_PERIOD_DAYS |
Prod / Dev | Janela default dos relatorios | 30 |
REPORTS_EXPORT_MAX_ROWS |
Prod / Dev | Limite de linhas para exportacao | 10000 |
Backups, GeoIP e privacidade
| Variavel | Ambito | Objetivo | Valor tipico |
|---|---|---|---|
BACKUP_ENABLED |
Prod / Dev | Ativa backups agendados | true, false |
BACKUP_CRON |
Prod / Dev | Expressao cron do backup | 0 0 2 * * * |
BACKUP_RETENTION_DAILY |
Prod / Dev | Numero de backups diarios a reter | 7 |
BACKUP_RETENTION_WEEKLY |
Prod / Dev | Numero de backups semanais a reter | 4 |
BACKUP_RETENTION_MONTHLY |
Prod / Dev | Numero de backups mensais a reter | 12 |
BACKUP_LOCAL_DIR |
Runtime / Compose | Diretorio local dos backups | /app/data/backups |
BACKUP_RCLONE_REMOTE |
Prod / Dev | Destino rclone para copias remotas | s3:bucket/path |
BACKUP_ARCHIVE_ENCRYPTION_MODE |
Prod / Dev | Modo de cifragem do arquivo | AGE (padrão), NONE |
BACKUP_AGE_RECIPIENT |
Prod / Dev | Recipient age público (gerado automaticamente) | age1… |
BACKUP_DATABASE_PAYLOAD_MODE |
Prod / Dev | Modo de payload da base de dados | APP_ENCRYPTED, PII_DECRYPTED |
JOBS_MODE |
Prod / Dev / Compose | Que tarefas agendadas o scheduler na JVM executa: all (web + backups num só contentor), web (só web — combinar com um worker backup-only), backup-only (worker de backup dedicado) |
all |
BACKUP_RUNTIME_PROFILE |
Prod / Dev | Etiqueta do perfil de execução registada nos logs/manifestos de backup. Combina WEB_MAINTENANCE com JOBS_MODE=all (sem worker separado); combina WORKER com JOBS_MODE=web + worker backup-only |
WORKER, WEB_MAINTENANCE, ONE_SHOT, OFFLINE_MAINTENANCE |
BACKUP_VERIFY_MODE |
Prod / Dev | Verificação pós-backup | FULL (padrão), CHECKSUM, NONE |
BACKUP_ALLOW_UNENCRYPTED_LOCAL_BACKUP |
Prod / Dev | Permite backups locais não cifrados | false |
BACKUP_DOWNLOAD_GRANT_TTL_SECONDS |
Prod / Dev | TTL do token de download | 300 |
BACKUP_OFFLINE_NOTICE_SECONDS |
Prod | Periodo de graca antes de a manutencao offline parar servicos | 300 |
BACKUP_MAINTENANCE_PAGE_ENABLED |
Prod | Serve pagina estatica de manutencao durante backup offline | false |
GEOIP_ENABLED |
Prod / Dev | Apenas interruptor de imposição por país (também interruptor de emergência). A base carrega e atualiza-se de forma independente — ver GEOIP_AUTO_UPDATE. |
false |
GEOIP_DB_PATH |
Prod / Dev | Caminho da base GeoIP (descarregada automaticamente no arranque; DB-IP sem chave por predefinição, MaxMind via MAXMIND_*). |
/app/data/geoip/... |
SECURITY_GEOIP_ALLOWED_COUNTRIES |
Prod / Dev | Allowlist de paises ISO | PT,ES,FR |
MAXMIND_ACCOUNT_ID |
Prod | Conta MaxMind para downloads GeoLite | account ID |
MAXMIND_LICENSE_KEY |
Prod | Chave de licenca MaxMind | segredo |
GEOIP_EDITION_ID |
Prod | Identificador da edicao MaxMind | GeoLite2-Country |
GDPR_ANONYMIZE_AUTO_AFTER_DAYS |
Prod / Dev | Horizonte de anonimização automatica | 0 |
Orientacao pratica
- comeca pelo template de producao para ambientes reais e pelo template de desenvolvimento para stacks locais
- trata
DB_ENCRYPTION_KEY,TIMING_TOKEN_SECRET,PUBLIC_LINK_PASSWORD_SESSION_SECRETe credenciais SMTP como segredos com backup seguro - evita levar portas de Compose e variaveis de frontend para o
.envde producao sem necessidade - para o setup minimo viavel, consulta o Guia de instalacao
- para topologia e modos de deploy, consulta Opcoes de deployment