Referência de configuração

Todas as definições vivem em deploy/.env, copiado de .env.example. Só POSTGRES_PASSWORD e CAMPBOOKS_PUBLIC_URL são obrigatórias. Tudo o resto é opcional, e aplicam-se os valores por omissão abaixo quando uma definição não está definida. Depois de alterar o .env, execute docker compose up -d outra vez.

Base

Variável	Valor por omissão	O que faz
POSTGRES_PASSWORD	change-me (exemplo)	Palavra-passe da conta proprietária do Postgres incluído. Obrigatória. Apenas caracteres seguros para URL.
CAMPBOOKS_PUBLIC_URL	https://campbooks.example.com (exemplo)	O endereço que as pessoas usam para aceder a esta instância. Obrigatório. As ligações de convite são construídas a partir dele.
CAMPBOOKS_PORT	8080	Porta do anfitrião para a aplicação web e a API.
CAMPBOOKS_LOG_FORMAT	json	json ou pretty.
CAMPBOOKS_RUN_MIGRATIONS	true	Aplica as migrações da base de dados ao arrancar.
RUST_LOG	não definido	Filtro do nível de registo, por exemplo info.
CAMPBOOKS_ENV	não definido	development regista as ligações de convite. Nunca o defina num servidor usado por outras pessoas.

Contas da base de dados

O ficheiro compose incluído trata disto por si. Só interessam se usar o seu próprio Postgres. Veja Armazenamento e base de dados.

Variável	Valor por omissão	O que faz
CAMPBOOKS_DATABASE_URL	definido pelo compose	Conta de execução, sem privilégios de superutilizador.
CAMPBOOKS_DATABASE_PASSWORD_FILE	definido pelo compose	Ficheiro com a palavra-passe da conta de execução (opcional).
CAMPBOOKS_DATABASE_MIGRATION_URL	definido pelo compose	Conta proprietária, usada apenas para executar migrações.
CAMPBOOKS_DATABASE_ROLE	campbooks_app	Com um único URL privilegiado, o papel para o qual cada ligação muda. Mantenha o valor por omissão, a menos que o seu administrador de base de dados tenha criado outro.
CAMPBOOKS_DATABASE_ALLOW_RLS_BYPASS	false	Arranca mesmo que a conta contorne a segurança ao nível da linha. O isolamento dos espaços de trabalho passa a depender só das consultas.
CAMPBOOKS_DATABASE_MAX_CONNECTIONS	10	Tamanho do pool da base de dados. Mantenha-o acima de CAMPBOOKS_JOBS__CONCURRENCY.

Início de sessão

O Campbooks é o seu próprio início de sessão. Deixe CAMPBOOKS_AUTH__ISSUER por definir. Veja Início de sessão para o quadro completo. Cada segredo de cliente é um ficheiro em deploy/secrets/, montado no servidor em /run/secrets/campbooks.

Variável	Valor por omissão	O que faz
CAMPBOOKS_GOOGLE__CLIENT_ID	não definido	Ativa o início de sessão com Google e a ligação do Gmail. A Gmail API tem de estar ativa no mesmo projeto Google. URI de redirecionamento: ${CAMPBOOKS_PUBLIC_URL}/auth/callback/google.
CAMPBOOKS_GOOGLE__CLIENT_SECRET_FILE	não definido	Por exemplo /run/secrets/campbooks/google-client-secret.
CAMPBOOKS_MICROSOFT__CLIENT_ID	não definido	Ativa o início de sessão com Microsoft. URI de redirecionamento: ${CAMPBOOKS_PUBLIC_URL}/auth/callback/microsoft.
CAMPBOOKS_MICROSOFT__CLIENT_SECRET_FILE	não definido	Por exemplo /run/secrets/campbooks/microsoft-client-secret.
CAMPBOOKS_MICROSOFT__TENANT	common	common, organizations, consumers, ou o ID de um tenant.
CAMPBOOKS_ZOHO__CLIENT_ID	não definido	Ativa o início de sessão com Zoho e a ligação do Zoho Mail. URI de redirecionamento: ${CAMPBOOKS_PUBLIC_URL}/auth/callback/zoho.
CAMPBOOKS_ZOHO__CLIENT_SECRET_FILE	não definido	Por exemplo /run/secrets/campbooks/zoho-client-secret.
CAMPBOOKS_ZOHO__ACCOUNTS_SERVER	https://accounts.zoho.com	O servidor de contas do centro de dados em que a sua aplicação Zoho está registada, por exemplo https://accounts.zoho.eu. Deixe o valor por omissão só se a aplicação tiver o Multi-DC ativo.
CAMPBOOKS_<PROVIDER>__REDIRECT_PATH	/auth/callback/<provider>	Só se a sua aplicação OAuth registou outro caminho de retorno que o seu proxy inverso reescreve.
CAMPBOOKS_TRUSTED_PROXIES	não definido	Endereços ou blocos CIDR dos proxies inversos cujo X-Forwarded-For indica o cliente. Sem isto, os limites de pedidos do início de sessão contam todos os clientes como um só.
CAMPBOOKS_AUTH__AUDIENCE	campbooks-api	Só com um emissor externo: a audiência que a API tem de encontrar no aud do token.
CAMPBOOKS_AUTH__LEEWAY_SECONDS	60	Só com um emissor externo: desvio de relógio tolerado.
CAMPBOOKS_BFF__IDLE_TIMEOUT_MINUTES	2880	As sessões web terminam após este tempo sem uso.
CAMPBOOKS_BFF__ABSOLUTE_TIMEOUT_HOURS	720	As sessões web terminam, no máximo, este tempo após o início de sessão.
CAMPBOOKS_BFF__ROTATE_MINUTES	60	Com que frequência o valor do cookie de uma sessão é substituído.
CAMPBOOKS_BFF__LOGIN_TIMEOUT_SECONDS	600	Quanto tempo pode demorar um início de sessão no fornecedor.
CAMPBOOKS_BFF__SCOPES	openid profile email offline_access mais todos os âmbitos da API	Âmbitos a pedir.

Caixas de correio

Todas opcionais. Veja Ligar caixas de correio. As definições dos clientes Google e Zoho estão na tabela de Início de sessão acima. As definições do IMAP (CAMPBOOKS_CONNECTORS__IMAP__*) estão listadas em Caixas de correio IMAP.

Variável	Valor por omissão	O que faz
CAMPBOOKS_CONNECTORS__GMAIL__BACKFILL_DAYS	90	Até onde lê uma ligação Gmail nova, em dias. De 1 a 3650.
CAMPBOOKS_CONNECTORS__GMAIL__MAX_MESSAGE_BYTES	52428800 (50 MiB)	As mensagens maiores são ignoradas e registadas como demasiado grandes.
CAMPBOOKS_CONNECTORS__GMAIL__RUN_BUDGET_BYTES	67108864 (64 MiB)	Uma execução de sincronização não inicia mais transferências depois deste número de bytes e continua na execução seguinte. Mantém a memória limitada.
CAMPBOOKS_CONNECTORS__POLL__MIN_SECONDS	60	Intervalo após uma sincronização que encontrou alterações.
CAMPBOOKS_CONNECTORS__POLL__MAX_SECONDS	14400 (4 horas)	Intervalo mais longo de uma caixa de correio parada.
CAMPBOOKS_CONNECTORS__GOOGLE__UNITS_PER_SECOND	5000	Unidades de quota da API Google por segundo, partilhadas por todos os processos do servidor. Um valor baixo só abranda envios grandes.
CAMPBOOKS_CONNECTORS__ZOHO__BACKFILL_DAYS	90	Até onde lê uma caixa Zoho nova, em dias. De 1 a 3650.
CAMPBOOKS_CONNECTORS__ZOHO__MAX_MESSAGE_BYTES	52428800 (50 MiB)	As mensagens maiores são ignoradas e registadas como demasiado grandes.
CAMPBOOKS_CONNECTORS__ZOHO__RUN_BUDGET_BYTES	67108864 (64 MiB)	Como no Gmail.
CAMPBOOKS_CONNECTORS__ZOHO__REQUESTS_PER_MINUTE	60	Pedidos que cada início de sessão do Zoho pode fazer por minuto, partilhados por todos os processos.
CAMPBOOKS_CONNECTORS__ZOHO__SWEEP_MINUTES	360	Minutos entre releituras completas da janela de uma caixa Zoho.
CAMPBOOKS_CONNECTORS__FAILING_AFTER	5	Execuções falhadas seguidas antes de uma caixa de correio aparecer com falhas.
CAMPBOOKS_CONNECTORS__BATCH_RETENTION_DAYS	7	Dias em que um lote de alterações produzido é guardado para repetição.

Política de registo

Variável	Valor por omissão	O que faz
CAMPBOOKS_SIGNUP__POLICY	open	Quem pode criar um espaço de trabalho: open, invite_only, approval ou code. O primeiro utilizador da instância pode sempre criar um.
CAMPBOOKS_SIGNUP__CODES	não definido	Códigos separados por vírgulas aceites em code. Cada um é reutilizável. Trate-os como segredo.

Tarefas e worker

O servidor executa o worker de tarefas junto à API. Cada tarefa em execução pode ocupar uma ligação à base de dados.

Variável	Valor por omissão	O que faz
CAMPBOOKS_JOBS__CONCURRENCY	4	Tarefas que um processo executa em simultâneo.
CAMPBOOKS_JOBS__PER_WORKSPACE	2	Tarefas de um espaço de trabalho que podem correr em simultâneo por fila.
CAMPBOOKS_JOBS__POLL_INTERVAL_MS	5000	Verificação em repouso. Tarefas novas acordam o worker de imediato de qualquer forma.
CAMPBOOKS_JOBS__RETENTION_HOURS	168	Quanto tempo se guardam as tarefas concluídas. As falhadas ficam até as eliminar.
CAMPBOOKS_JOBS__SHUTDOWN_GRACE_SECONDS	8	Quanto tempo um worker a parar espera pelas tarefas em execução. Mantenha abaixo do tempo limite de paragem.
CAMPBOOKS_JOBS__LEASE_SECONDS	60	Tempo de concessão de uma tarefa.
CAMPBOOKS_JOBS__RETRY_BASE_MS	1000	Atraso base de nova tentativa.
CAMPBOOKS_JOBS__RETRY_MAX_SECONDS	3600	Atraso máximo de nova tentativa.

Armazenamento de blobs

Veja Armazenamento e base de dados.

Variável	Valor por omissão	O que faz
CAMPBOOKS_BLOBS__BACKEND	fs	fs (disco local) ou s3.
CAMPBOOKS_BLOBS__PATH	/data/blobs	Diretório do backend fs (o volume blobs-data).
CAMPBOOKS_BLOBS__MAX_OBJECT_BYTES	52428800 (50 MiB)	Maior ficheiro aceite.
CAMPBOOKS_BLOBS__SWEEP_GRACE_HOURS	24	Quanto tempo um ficheiro que ninguém usa é mantido antes de ser eliminado.
CAMPBOOKS_BLOBS__S3__BUCKET	não definido	Nome do bucket.
CAMPBOOKS_BLOBS__S3__ENDPOINT	não definido (AWS)	URL do armazenamento. http:// é aceite numa rede privada.
CAMPBOOKS_BLOBS__S3__REGION	não definido	Região que o seu armazenamento espera.
CAMPBOOKS_BLOBS__S3__ACCESS_KEY_ID	não definido	Chave de acesso.
CAMPBOOKS_BLOBS__S3__SECRET_ACCESS_KEY	não definido	Chave secreta.
CAMPBOOKS_BLOBS__S3__PATH_STYLE	false	true para URLs <endpoint>/<bucket> (a maioria dos armazenamentos próprios).

Papéis de IA

Veja IA local. Um papel não definido fica simplesmente indisponível.

Variável	Valor por omissão	O que faz
CAMPBOOKS_AI__DECIDE__PROTOCOL	laya	laya ou openai.
CAMPBOOKS_AI__DECIDE__BASE_URL	http://laya:8000/v1	Onde o modelo decide é servido.
CAMPBOOKS_AI__DECIDE__MODEL	convaiinnovations/laya-multilingual	O modelo decide.
CAMPBOOKS_AI__DECIDE__API_KEY	vazio	Obrigatória para o Laya. Gere com openssl rand -hex 32.
CAMPBOOKS_AI__DECIDE__LOGPROBS	true	Defina como false para servidores que rejeitam o parâmetro logprobs (protocolo openai).
CAMPBOOKS_AI__DECIDE__CALIBRATION__*	1.0	Uma temperatura por tipo de pergunta (NOUL, CHOICE, CHOICE_2, SCORE). Acima de 1 torna as probabilidades menos seguras.
CAMPBOOKS_CONVERSATIONS__DECIDE_BACKFILL_DAYS	14	O correio com mais de tantos dias não recebe chamada a decide.
CAMPBOOKS_AI__COMPLETE__BASE_URL	http://ollama:11434/v1	Onde o modelo complete é servido.
CAMPBOOKS_AI__COMPLETE__MODEL	qwen3:8b	O modelo complete.
CAMPBOOKS_AI__EMBED__BASE_URL	http://embeddings:80/v1	Onde o modelo embed é servido.
CAMPBOOKS_AI__EMBED__MODEL	BAAI/bge-m3	O modelo embed (1024 dimensões).
CAMPBOOKS_AI__VISION__BASE_URL	não definido	Papel vision opcional, por exemplo http://ollama:11434/v1.
CAMPBOOKS_AI__VISION__MODEL	não definido	Opcional, por exemplo qwen2.5vl:7b.

Qualquer papel aceita também CAMPBOOKS_AI__<ROLE>__API_KEY para um fornecedor alojado.

Outras definições no .env.example

O .env.example documenta ainda estas áreas. Os valores por omissão estão lá indicados.

• Atualizações em direto (feed de alterações): o bloco CAMPBOOKS_CHANGES__*. Um proxy inverso à frente do servidor não pode colocar em buffer as respostas text/event-stream.
• Monitorização: CAMPBOOKS_TELEMETRY__METRICS_ADDR, CAMPBOOKS_TELEMETRY__OTLP_ENDPOINT, CAMPBOOKS_TELEMETRY__OTLP_HEADERS e CAMPBOOKS_TELEMETRY__SAMPLE_RATIO. Desativada por omissão.