docs

Instalar com Docker Compose

Em breve

O lançamento da versão instalável ainda está pendente. Hoje você pode usar o fazer.ai projects em projects.fazer.ai. O endereço da imagem e a tag usados neste exemplo são os atuais e podem mudar no lançamento.

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 openssl disponí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.

compose.yaml
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=
EOF

O 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ávelPara que serve
PUBLIC_URLEndereço público completo, com https://. O app usa esse endereço nos links e no login.
CORS_ORIGINO mesmo host de PUBLIC_URL, sem https://.
POSTGRES_PASSWORDSenha do PostgreSQL. O Compose usa esse valor para montar DATABASE_URL.
JWT_SECRETSegredo usado para assinar o cookie de sessão.
ENCRYPTION_KEYChave usada para cifrar dados no banco.
GOOGLE_CLIENT_IDIdentificador do cliente OAuth para login com Google.
GOOGLE_CLIENT_SECRETSegredo 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/health

O 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 setup

Abra 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.com

Atualizar

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).dump

Troque 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 -d

Confira 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.

On this page