Instalar com Docker Compose
Em breve
Com este Compose, você sobe o fazer.ai projects e o PostgreSQL no mesmo servidor. Configure o proxy reverso com HTTPS à parte. Você pode usar Caddy, Traefik ou nginx para receber as conexões externas e encaminhá-las para 127.0.0.1:3000.
Antes de começar
- Tenha um servidor com Docker e Docker Compose.
- Separe o domínio que você vai usar no endereço público da instalação.
- Tenha o
openssldisponível para gerar os segredos. - Para configurar a primeira conta pelo
/setup, tenha um cliente OAuth do Google. Para criar a conta pelo terminal e definir a senha por e-mail, configure o e-mail transacional.
Veja os requisitos e as opções de configuração na visão geral do self-host.
O compose
Salve o arquivo do Compose em uma pasta no servidor. O Compose lê o .env dessa pasta e exige todas as variáveis obrigatórias para iniciar os serviços.
services:
app:
image: git.fazer.ai/fazer-ai/projects:v1.15.0
restart: unless-stopped
depends_on:
postgres:
condition: service_healthy
environment:
NODE_ENV: production
PORT: "3000"
PUBLIC_URL: ${PUBLIC_URL:?defina PUBLIC_URL no .env}
CORS_ORIGIN: ${CORS_ORIGIN:?defina CORS_ORIGIN no .env}
DATABASE_URL: postgres://projects:${POSTGRES_PASSWORD:?defina POSTGRES_PASSWORD no .env}@postgres:5432/projects
JWT_SECRET: ${JWT_SECRET:?defina JWT_SECRET no .env}
ENCRYPTION_KEY: ${ENCRYPTION_KEY:?defina ENCRYPTION_KEY no .env}
GOOGLE_CLIENT_ID: ${GOOGLE_CLIENT_ID:-}
GOOGLE_CLIENT_SECRET: ${GOOGLE_CLIENT_SECRET:-}
SIGNUP_ENABLED: ${SIGNUP_ENABLED:-false}
ports:
- "127.0.0.1:3000:3000"
healthcheck:
test: ["CMD-SHELL", "wget -qO- http://127.0.0.1:3000/api/health/ready || exit 1"]
interval: 10s
timeout: 5s
retries: 5
start_period: 30s
postgres:
image: postgres:18-alpine
restart: unless-stopped
environment:
POSTGRES_DB: projects
POSTGRES_USER: projects
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?defina POSTGRES_PASSWORD no .env}
volumes:
- postgres:/var/lib/postgresql
healthcheck:
test: ["CMD-SHELL", "pg_isready -h 127.0.0.1 -U projects -d projects"]
interval: 10s
timeout: 5s
retries: 10
volumes:
postgres:O serviço postgres usa a imagem postgres:18-alpine, cria o banco e o usuário projects e guarda os dados no volume postgres. O serviço app usa a imagem git.fazer.ai/fazer-ai/projects:v1.15.0, publica a porta 3000 apenas em 127.0.0.1 e espera o banco ficar saudável para iniciar. O healthcheck consulta /api/health/ready, que retorna HTTP 200 apenas quando o banco responde. Use esse endpoint para verificar se o app está pronto durante uma atualização.
As variáveis
Crie o .env na pasta do Compose com o comando abaixo. Para usar o login com Google, crie um cliente OAuth do tipo “Aplicativo da Web” no Google Cloud e adicione o endereço de PUBLIC_URL às origens JavaScript autorizadas.
cat > .env <<EOF
PUBLIC_URL=https://projects.example.com
CORS_ORIGIN=projects.example.com
POSTGRES_PASSWORD=$(openssl rand -hex 32)
JWT_SECRET=$(openssl rand -hex 32)
ENCRYPTION_KEY=$(openssl rand -hex 32)
GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=
EOFO comando usa openssl rand -hex 32 para gerar os três segredos em hexadecimal. Assim, a senha do banco fica livre de caracteres que quebram a URL de conexão. Gere os segredos uma vez e guarde o .env em um lugar seguro. Trocar JWT_SECRET encerra todas as sessões. Trocar ENCRYPTION_KEY torna ilegíveis os dados já cifrados. Se você mudar POSTGRES_PASSWORD com o volume existente, o app perde o acesso ao banco.
| Variável | Para que serve |
|---|---|
PUBLIC_URL | Endereço público completo, com https://. O app usa esse endereço nos links e no login. |
CORS_ORIGIN | O mesmo host de PUBLIC_URL, sem https://. |
POSTGRES_PASSWORD | Senha do PostgreSQL. O Compose usa esse valor para montar DATABASE_URL. |
JWT_SECRET | Segredo usado para assinar o cookie de sessão. |
ENCRYPTION_KEY | Chave usada para cifrar dados no banco. |
GOOGLE_CLIENT_ID | Identificador do cliente OAuth para login com Google. |
GOOGLE_CLIENT_SECRET | Segredo do cliente OAuth para login com Google. |
O Compose fixa PORT=3000 e NODE_ENV=production. No modo de produção, o app exige que você substitua os segredos padrão. O próprio Compose monta DATABASE_URL.
O .env.example do produto lista as variáveis opcionais e seus padrões. Com SIGNUP_ENABLED=false, o padrão, só entra quem recebe convite. Use ALLOWED_SIGNUP_DOMAINS para limitar os domínios de cadastro. Para e-mail transacional, defina MAIL_PROVIDER, MAIL_FROM e as credenciais do Resend ou do SMTP. Para anexos em S3, configure as quatro variáveis ATTACHMENTS_S3_* juntas. Para passar uma variável opcional ao app, acrescente-a ao .env e ao bloco environment do serviço app.
Subir
Na pasta do Compose, suba os serviços e confira o estado dos contêineres e a resposta de /api/health.
docker compose up -d
docker compose ps
curl -s http://127.0.0.1:3000/api/healthO app espera o banco, aplica as migrações e fica healthy em poucos segundos. A resposta de /api/health inclui a versão e "db":{"ok":true}. O log pode trazer um aviso que começa com rls:, esperado porque o usuário do Compose é superusuário do banco.
Primeiro acesso pelo /setup
Com o banco sem nenhuma pessoa cadastrada, procure First-run setup required nos logs para encontrar o endereço /setup?token=....
docker compose logs app | grep setupAbra o link para preencher o “Token de configuração”. O token vale para um único uso e muda a cada reinício enquanto ninguém se cadastra. Preencha “Nome da organização” e “Endereço” e clique em “Continuar com o Google”. O /setup exige login com Google, e a conta que você usar vira a administradora.
Para criar a conta por e-mail, configure o e-mail transacional e execute o comando abaixo com o endereço da pessoa que vai administrar a instalação. O comando cria a conta sem senha. A pessoa abre “Esqueci a senha” em /login, informa o e-mail e usa o código recebido para definir a senha.
docker compose exec app bun set-admin voce@example.comAtualizar
Faça um backup do PostgreSQL antes de alterar a tag. O comando usa pg_dump no formato custom e grava um arquivo com a data no nome.
docker compose exec -T postgres pg_dump -Fc -U projects projects > projects-$(date +%F).dumpTroque a tag da imagem do app por uma tag de versão no formato vX.Y.Z, nunca latest, que muda a versão sem ninguém decidir. Depois baixe a imagem e suba o serviço para que o novo contêiner aplique as migrações.
# em compose.yaml, troque a tag: image: git.fazer.ai/fazer-ai/projects:vX.Y.Z
docker compose pull app
docker compose up -dConfira a versão em /api/health. Para voltar à versão anterior, recoloque a tag antiga e suba o serviço de novo. O banco mantém as migrações aplicadas pela versão nova. Se elas deixarem o banco incompatível com a versão anterior, restaure o backup feito antes da atualização. A restauração descarta os dados gravados depois do backup.