Referência de ambiente auto-hospedado
Comece com o lançamento env.example, que você baixou como .env em Primeiros passos. É a menor configuração do Compose compatível. Usar env.full.example quando você precisar de uma configuração opcional; esta página explica quais configurações pertencem uma à outra e quando alterá-las.
Depois de editar .env, valide a interpolação sem imprimir a configuração resolvida:
docker compose config --quiet
Não se comprometa .env, cole-o em solicitações de suporte ou exponha a saída de docker compose config: a saída resolvida contém segredos.
Valores de produção necessários
Gere cada segredo de forma independente com openssl rand -hex 32. Mantenha os valores antigos em cada atualização e armazene uma cópia de recuperação fora do servidor.
| Variável | Valor de produção | Por que isso importa |
|---|---|---|
POSTGRES_PASSWORD | Senha aleatória única | Protege o banco de dados PostgreSQL incluído. |
WEB_ORIGIN | Origem do aplicativo HTTPS público, como https://kanera.example.com | Usado para links de navegador, CORS e fluxos de autenticação. Não inclua uma barra final. |
COOKIE_DOMAIN | Nome de host do aplicativo, como kanera.example.com | Escopo para o cookie de atualização. |
COOKIE_SECURE | true | Obrigatório quando o aplicativo é veiculado por HTTPS. |
JWT_SECRET | Segredo aleatório estável, pelo menos 16 caracteres | Assina sessões de usuário. A rotação desconecta todos. |
MCP_INTERNAL_SECRET | Segredo aleatório estável, com pelo menos 32 caracteres e diferente de JWT_SECRET | Permite que o MCP e os serviços de API pública troquem credenciais OAuth vinculadas ao público sem encaminhar um token MCP para /api/v1. Ambos os serviços devem usar sempre o mesmo valor. |
MFA_ENCRYPTION_KEY | Segredo aleatório estável, pelo menos 32 caracteres | Protege a inscrição e os desafios do autenticador. A rotação invalida autenticadores registrados. |
MEDIA_SIGNING_SECRET | Segredo aleatório estável, pelo menos 32 caracteres | Assina URLs de mídia privada. A rotação invalida os URLs assinados existentes. |
SECRETS_ENCRYPTION_KEY | Segredo aleatório estável, com pelo menos 32 caracteres e diferente de JWT_SECRET | Criptografa credenciais de SMTP, armazenamento, webhook e integração armazenadas no banco de dados. |
KANERA_DEPLOYMENT_MODE o padrão é self_hosted. O modo hospedado e suas variáveis Stripe, PostHog, limite de plano e licenciamento são para implantações operadas pelo Kanera e devem permanecer não definidas em uma instalação auto-hospedada.
Compor suprimentos NODE_ENV=production e ANALYTICS_ENABLED=false. Sair ANALYTICS_PROVIDER, POSTHOG_PROJECT_KEY, POSTHOG_API_HOST, cada STRIPE_*, HOSTED_*e token de modo hospedado não definido. Essas configurações não transformam uma instalação auto-hospedada no Kanera Cloud.
URLs e serviços públicos
| Variável | Padrão | Defina quando |
|---|---|---|
KANERA_ENVIRONMENT | production em produção Compor | Você precisa de um prefixo de chave de API diferente para desenvolvimento, teste ou preparação. |
API_PUBLIC_URL | WEB_ORIGIN | A API do aplicativo voltada para o navegador usa uma origem pública diferente. |
KANERA_PUBLIC_API_URL | http://public-api:3001 no Compose | O MCP ou outro processo interno alcança a API pública em algum lugar diferente do endereço do serviço Compose. Este é um URL interno, não a origem da API voltada para o navegador. |
PUBLIC_API_OAUTH_ISSUER | http://localhost:3001 | Você expõe o OAuth ou a API pública remotamente; use sua origem HTTPS acessível pelo navegador. |
MCP_SERVER_PUBLIC_URL | http://localhost:3002/mcp | Você expõe o MCP remoto; usar o público completo /mcp URL. |
MCP_PUBLIC_URL | Derivado de MCP_SERVER_PUBLIC_URL por Compor | Você executa o serviço MCP fora da fiação do Compose incluída. |
OAUTH_ISSUER_URL | Derivado de PUBLIC_API_OAUTH_ISSUER por Compor | Você executa o MCP fora da fiação do Compose incluída. |
API_PORT, PUBLIC_API_PORT, WORKER_PORT, MCP_PORT | 3000, 3001, 3003, 3002 | Você executa serviços fora do Compose ou precisa de portas de listener internas diferentes. |
API_TRUST_PROXY, PUBLIC_API_TRUST_PROXY, MCP_TRUST_PROXY | false, false, true | Um proxy reverso confiável fornece o IP real do cliente. Nunca confie em cabeçalhos encaminhados de clientes arbitrários. |
O navegador se conecta a web; não publique o principal api serviço. Veja Serviços e roteamento antes de expor a API pública ou MCP.
Contas e autenticação
| Variável | Padrão | Objetivo |
|---|---|---|
SIGNUPS_ENABLED | true | Definir false para impedir a inscrição pública e a criação de novas organizações. Os links de convite de organizações existentes ainda funcionam. |
EMAIL_VERIFICATION_ENABLED | false | Exija uma verificação de e-mail de seis dígitos para inscrição, inscrição de convite e alterações de e-mail. Habilite somente depois que o SMTP funcionar. |
AUTH_RATE_LIMIT_ENABLED | true | Habilite o acelerador de força bruta por IP em rotas de autenticação não autenticadas. |
AUTH_RATE_LIMIT_MAX / AUTH_RATE_LIMIT_WINDOW_MS | 10 / 60000 | Tentativas de autenticação permitidas por janela. |
JWT_ACCESS_TTL / JWT_REFRESH_TTL_DAYS | 5m / 10 | Tempos de vida do token de acesso e da sessão de atualização. |
CLOUDFLARE_TURNSTILE_SITE_KEY / CLOUDFLARE_TURNSTILE_SECRET_KEY | Desativar | Proteção de inscrição hospedada. Deixe não definido para auto-hospedagem normal. |
Os usuários configuram seu próprio autenticador em Configurações -> Sua conta -> Segurança. Os administradores da organização podem exigir isso em Configurações -> Organização -> Segurança. Veja Perfil e segurança.
Limites públicos de API e MCP
| Variável | Padrão | Objetivo |
|---|---|---|
PUBLIC_API_RATE_LIMIT_ENABLED | true | Ativa limites de solicitações públicas de API e MCP. |
PUBLIC_API_IP_RATE_LIMIT_PER_MINUTE | 60 | Limite para descoberta não autenticada e formatos de portador inválidos. |
PUBLIC_API_FAILED_KEY_RATE_LIMIT_PER_MINUTE | 10 | Limite por IP para falhas kanera_* principais tentativas. |
PUBLIC_API_KEY_RATE_LIMIT_PER_MINUTE | 400 | Limite de solicitação por chave após autenticação bem-sucedida. |
PUBLIC_API_UPLOAD_RATE_LIMIT_PER_MINUTE | 30 | Limite de upload de anexo por chave. |
PUBLIC_API_RATE_LIMIT_WINDOW_MS | 60000 | Janela de limite de taxa compartilhada pela API pública e pelo MCP. |
MCP_BODY_MAX_BYTES | 1048576 | Corpo máximo da solicitação MCP. |
MCP_REQUEST_TIMEOUT_MS | 30000 | Tempo máximo para uma solicitação MCP. |
MCP_HEADERS_TIMEOUT_MS / MCP_KEEP_ALIVE_TIMEOUT_MS | 10000 / 5000 | Tempos limite de conexão HTTP MCP. |
KANERA_API_KEY | Desativar | Exigido apenas pela ponte stdio MCP local, não pelo serviço HTTP MCP. |
Banco de dados, cache e capacidade
Compor suprimentos DATABASE_URL e REDIS_URL para os serviços agrupados PostgreSQL e Valkey. Configure-os você mesmo apenas ao executar um processo fora dessa rede ou ao usar serviços gerenciados.
| Variável | Compor padrão | Objetivo |
|---|---|---|
DATABASE_SSL | false | Habilite somente quando um banco de dados externo exigir SSL. |
POSTGRES_BIND_PORT | 5433 | Porta de host somente loopback para PostgreSQL incluído. |
API_REPLICAS / PUBLIC_API_REPLICAS / MCP_REPLICAS | 2 / 1 / 1 | Contagens de processos de serviço. Mantenha o trabalhador exatamente em um. |
PG_POOL_MAX / WORKER_PG_POOL_MAX | 20 / 5 | Máximo de conexões de banco de dados por processo de aplicativo e para o trabalhador. |
PG_IDLE_TIMEOUT_MS / PG_CONNECTION_TIMEOUT_MS | 30000 / 5000 | Tempo limite de inatividade e aquisição do pool. |
PG_STATEMENT_TIMEOUT_MS / SLOW_QUERY_LOG_MS | 30000 / 250 | Tempo limite de consulta ao banco de dados e limite de registro de consulta lenta. |
NODE_OPTIONS | Desativar | Sinalizadores de nó opcionais, como um limite de heap. |
UV_THREADPOOL_SIZE | 16 | Threads de trabalho nativos usados por hashing, criptografia e processamento de imagem. |
REALTIME_WEBSOCKET_COMPRESSION_ENABLED | true | Compactar mensagens maiores do Socket.IO WebSocket. |
REALTIME_WEBSOCKET_COMPRESSION_THRESHOLD_BYTES | 1024 | Tamanho mínimo do quadro em tempo real para compactar. |
REALTIME_OUTBOX_POLL_MS | 500 no Compose | Intervalo de pesquisa de fallback do trabalhador para linhas de caixa de saída em tempo real e de webhook. |
USER_DISPLAY_CACHE_TTL_MS | 60000 | Vida útil do cache em processo para pesquisas de nomes de exibição. |
Eleve réplicas e pools juntos somente após medir a capacidade. Veja Atualizações e dimensionamento.
Arquivos e armazenamento de objetos
| Variável | Padrão | Objetivo |
|---|---|---|
UPLOADS_DIR | /data/uploads no Compose | Diretório de upload local. O Bundled Compose corrige esse caminho e o persiste em kanera_uploads; alterar o mapeamento de volume em vez de .env. |
ATTACHMENT_MAX_BYTES | 104857600 | Tamanho máximo do anexo carregado em bytes. |
S3_REGION / S3_BUCKET | Desativar | Inicie o armazenamento compatível com S3 em toda a implantação quando fornecido com credenciais. |
S3_ACCESS_KEY_ID / S3_SECRET_ACCESS_KEY | Desativar | Credenciais para o bucket de upload. Ambos são necessários para S3 baseado em ambiente. |
S3_ENDPOINT | Desativar | Endpoint personalizado para MinIO, R2 ou outro provedor compatível com S3. Configurá-lo permite solicitações de estilo de caminho. |
S3_PUBLIC_URL_PREFIX | Desativar | Prefixo público ou CDN opcional para objetos armazenados. |
O armazenamento do ambiente tem precedência sobre o armazenamento da organização configurado no aplicativo. Veja Armazenamento e backups antes de mudar uma instalação que já possui uploads.
E-mail, notificações e integrações
| Variável | Padrão | Objetivo |
|---|---|---|
SMTP_HOST, SMTP_USER, SMTP_PASSWORD, SMTP_FROM_EMAIL | Desativar | Conexão SMTP de saída padrão e remetente. |
SMTP_PORT / SMTP_SECURITY | 587 / starttls | Porta e transporte SMTP: starttls, tls, ou none. |
SMTP_FROM_NAME | Kanera | Nome de exibição do remetente. |
SMTP_IDENTITY_DOMAIN | Domínio de e-mail do remetente | Domínio EHLO e Message-ID. |
INTERNAL_NOTIFICATION_EMAILS | Desativar | Destinatários separados por vírgula para inscrição em texto simples e alertas de convite. Requer ambiente SMTP. |
KANERA_ALLOW_PRIVATE_NOTIFICATION_DESTINATIONS | false | Permitir receptores pessoais ntfy, Gotify e webhook em redes HTTP ou privadas. Os endereços reservados e de metadados permanecem bloqueados. |
ALERT_WEBHOOK_URL | Desativar | Destino compatível com Slack para alertas de prontidão, tempo de execução e Grafana. |
OPS_ALERTS_ENABLED / OPS_ALERT_THROTTLE_MS | true / 300000 | Habilite e desduplicar alertas operacionais. Nada é enviado sem destino. |
SLOW_REQUEST_LOG_MS | 2500 | Limite para um aviso de solicitação lenta nos logs. |
GITHUB_APP_ID, GITHUB_APP_SLUG, GITHUB_APP_PRIVATE_KEY | Desativar | Aplicativo GitHub opcional definido pela implantação para visualizações de links privados. Os administradores auto-hospedados podem usar o fluxo de manifesto no aplicativo. |
TRELLO_API_KEY | Desativar | Permite que as importações do Trello autentiquem e copiem anexos. |
Veja E-mail e notificações e Integrações e APIs.
Backups e retenção
| Variável | Padrão | Objetivo |
|---|---|---|
DB_BACKUPS_ENABLED | false | Habilite backups criptografados agendados do PostgreSQL para armazenamento compatível com S3. |
DB_BACKUP_ENCRYPTION_PASSPHRASE | Desativar | Obrigatório quando os backups são ativados e necessário novamente para restaurá-los. |
DB_BACKUP_TIMES_UTC | 00:15,12:15,16:45 | Horários de backup UTC diários separados por vírgula. |
DB_BACKUP_RETENTION_DAYS | 14 | Janela de retenção de backup bem-sucedida. |
DB_BACKUP_S3_PREFIX | backups/postgres | Prefixo de objeto para dumps de banco de dados. |
DB_BACKUP_S3_BUCKET, DB_BACKUP_S3_REGION, DB_BACKUP_S3_ENDPOINT | Valores de armazenamento de upload | Destino de backup separado opcional. |
DB_BACKUP_S3_ACCESS_KEY_ID, DB_BACKUP_S3_SECRET_ACCESS_KEY | Valores de armazenamento de upload | Credenciais de backup separadas opcionais. |
ACTIVITY_EVENT_RETENTION_DAYS | 730 | Retenção do histórico de atividades. |
ADMIN_AUDIT_LOG_RETENTION_DAYS | 1095 | Retenção de log de auditoria de gerenciamento. |
NOTIFICATION_READ_RETENTION_DAYS / NOTIFICATION_MAX_RETENTION_DAYS | 90 / 365 | Notificação de leitura e retenção absoluta de notificação. |
AUTH_TOKEN_RETENTION_DAYS | 30 | Período de carência antes que os artefatos de autenticação expirados ou consumidos sejam eliminados. |
REALTIME_OUTBOX_RETENTION_DAYS / OUTBOX_STUCK_RETENTION_DAYS | 30 / 30 | Retenção de caixa de saída processada e permanentemente travada. |
Veja Armazenamento e backups para requisitos de backup e planejamento de restauração.
Monitoramento
| Variável | Padrão | Objetivo |
|---|---|---|
METRICS_ENABLED | true | Registra endpoints de métricas do Prometheus. Eles voltam 404 sem um token válido. |
METRICS_TOKEN | Desativar | Token do portador, com pelo menos 16 caracteres, necessário para raspagem. |
COMPOSE_PROFILES | Desativar | Incluir monitoring iniciar Grafana, Prometheus, Loki, Alloy e exportadores; incluir admin para o portal de gerenciamento. |
COMPOSE_PROJECT_NAME | kanera | Componha a identidade usada pelo Alloy para selecionar os logs desta implantação. Verifique docker compose ls em plataformas gerenciadas. |
GRAFANA_ADMIN_PASSWORD | Desativar | Obrigatório quando o perfil de monitoramento está ativado. |
MONITORING_BIND_IP | 127.0.0.1 | Interface de host para Grafana e Prometheus. Use um endereço VPN privado, nunca 0.0.0.0 em produção. |
GRAFANA_BIND_PORT / PROMETHEUS_BIND_PORT | 3000 / 9090 | Portas de host para as duas UIs de monitoramento. |
PROMETHEUS_RETENTION / PROMETHEUS_RETENTION_SIZE | 30d / 5GB | Limites de tempo e disco para dados do Prometheus. |
GRAFANA_ROOT_URL | Desativar | URL externo do Grafana ao servi-lo por meio de um proxy. |
POSTGRES_EXPORTER_DSN | Banco de dados agrupado | Substituição de um servidor PostgreSQL externo. |
REALTIME_EMIT_METRICS_ENABLED | false | Ative amostras de métricas de carga útil em tempo real. |
REALTIME_EMIT_METRICS_SAMPLE_RATE / REALTIME_EMIT_METRICS_MIN_BYTES | 0.01 / 0 | Amostragem de métricas em tempo real e tamanho mínimo de carga útil. |
Portal de gerenciamento opcional
O portal de gerenciamento é separado das configurações de locatário e possui seu próprio limite de autenticação. Habilite-o somente quando os operadores precisarem de administração entre organizações ou sessões de suporte auditadas.
| Variável | Padrão | Objetivo |
|---|---|---|
ADMIN_WEB_ORIGIN | http://localhost:4300 | Origem pública e limite CORS para o console administrativo. |
ADMIN_API_PORT | 3002 | Porta de ouvinte da API de administração interna quando executada fora da fiação agrupada. |
ADMIN_COOKIE_DOMAIN | Desativar | Substituição do domínio de cookie quando o nome do host do administrador está fora COOKIE_DOMAIN. |
ADMIN_JWT_SECRET | Desativar | Obrigatório para a API admin e deve ser diferente de JWT_SECRET. |
ADMIN_EMAIL / ADMIN_PASSWORD | Desativar | Propague o primeiro superadmin apenas enquanto a tabela admin-user estiver vazia. Eles não redefinem uma conta existente. |
ADMIN_JWT_ACCESS_TTL / ADMIN_JWT_REFRESH_TTL_DAYS | 15m / 7 | Acesso de administrador e tempos de atualização. |
ADMIN_LOGIN_RATE_LIMIT_MAX / ADMIN_LOGIN_RATE_LIMIT_WINDOW_MS | 5 / 300000 | Limitação de login de administrador por IP. |
ADMIN_TRUST_PROXY | true | Confie no proxy reverso do administrador para IPs de clientes reais. |
SUPPORT_SESSION_TTL_MINUTES | 60 | Vida útil da sessão de suporte de curta duração; máximo de oito horas e nenhum token de atualização. |
Mantenha o portal de gerenciamento privado, use um nome de host e um segredo separados e revise seu log de auditoria. A fiação de implantação completa está documentada em DEPLOY.md no repositório Kanera.
Aplicar e verificar alterações
A maioria das alterações exige a recriação dos serviços afetados:
docker compose config --quiet
docker compose up -d
docker compose ps
Verifique os logs de serviço relevantes após alterar as configurações de autenticação, entrega, armazenamento, API, MCP ou administrador. Um sintaticamente válido .env não prova que credenciais externas ou URLs funcionem.