Visão Geral da Implementação

O Campbooks é implementado como uma pilha Docker Compose autossuficiente. docker compose up executa toda a aplicação num único servidor — sem compilação Node, sem Redis e sem serviços externos a configurar além de um proxy reverso com terminação TLS.

Quer o passo a passo completo? Esta página apresenta o panorama geral. O Guia de Auto-Alojamento percorre um servidor de produção real de ponta a ponta.

A pilha

docker compose up inicia três contentores:

Serviço	O que é
postgres	PostgreSQL com a extensão pgvector (obrigatória — contém os dados da aplicação, cache, tarefas, Action Cable e embeddings vetoriais)
web	A aplicação Rails — Puma atrás do Thruster
worker	Tarefas em segundo plano — digitalização de email, IA, indexação, sincronização de calendário (Solid Queue)

Um quarto serviço, opensearch, é opcional (ativado com o perfil search) e apenas suporta o autocompletar de texto completo de contactos. Tudo o resto — pesquisa de email, pesquisa de documentos, a paleta Cmd+K — usa Postgres + pgvector.

Os ficheiros carregados (anexos de email guardados como Documentos) ficam num volume Docker local por omissão, ou em armazenamento de objetos compatível com S3, se configurado.

O que precisa

• Um servidor com Docker e o plugin Docker Compose (Docker Engine ≥ 24)
• Cerca de 2 GB de RAM para a pilha padrão (adicione ~1 GB se ativar o OpenSearch)
• Um nome de domínio e um proxy reverso com terminação TLS (Caddy, Traefik ou nginx)

Configuração

Tudo é configurado através de variáveis de ambiente em .env. bin/generate-secrets preenche os segredos obrigatórios; os restantes são opcionais e cada um ativa uma integração. A lista anotada encontra-se em .env.example.

Variável	Obrigatória	Finalidade
SECRET_KEY_BASE	Sim	Chave de sessão/assinatura do Rails
ACTIVE_RECORD_PRIMARY_KEY	Sim	Encripta tokens OAuth e chaves de IA em repouso
ACTIVE_RECORD_DETERMINISTIC_KEY	Sim	Idem
ACTIVE_RECORD_KEY_DERIVATION_SALT	Sim	Idem
CAMPBOOKS_DATABASE_PASSWORD	Sim	Palavra-passe do Postgres incluído
APP_HOST	Sim	O hostname pelo qual acede à aplicação (tem de corresponder ao cabeçalho Host)
FORCE_SSL	Sim	true atrás de um proxy TLS, false para uso local em HTTP simples
SELF_HOSTED	Sim	1 — registo aberto + lê chaves de IA a partir do ambiente

Não precisa de config/master.key. O auto-alojamento lê SECRET_KEY_BASE a partir do ambiente. Gere os segredos obrigatórios com bin/generate-secrets.

Passar a produção

1. Aponte um domínio para o servidor e defina APP_HOST, FORCE_SSL=true e WEB_PORT em .env.
2. Coloque um proxy reverso com terminação TLS à frente (com o Caddy são apenas duas linhas de configuração — HTTPS automático).
3. docker compose up -d --build. O entrypoint executa as migrações de base de dados no arranque.

Nunca exponha a aplicação em HTTP simples na internet. Com FORCE_SSL=false, as sessões e os cookies viajam sem encriptação. Utilize sempre um proxy TLS em produção.

Atualizações

git pull
docker compose up -d --build   # o entrypoint executa as migrações no arranque

Faça uma cópia de segurança da base de dados primeiro.

Verificação de estado

O Campbooks expõe um endpoint de saúde em /up (devolve 200 quando está saudável). Utilize-o para sondagens de balanceadores de carga e monitorização — mantém-se acessível em HTTP simples mesmo com FORCE_SSL=true.

Consulte o Guia de Auto-Alojamento para o percurso completo, incluindo cópias de segurança e cada integração.