Dashboard completo, local e sem login

A imagem oficial leva painel, API, PostgreSQL, migrations e dados iniciais em um único artefato. O desenvolvedor trabalha contra localhost sem depender do deploy da Vercel ou de uma segunda imagem.

Inicie com um único container

Instale Docker 24 ou superior. A imagem é pública e pode ser baixada sem conta GitHub, token ou docker login. O primeiro boot inicializa a base, aplica migrations idempotentes e libera o dashboard quando o health check estiver pronto.

docker pull ghcr.io/leonardocaldas/feature-rollout:latest

docker run --detach \
  --name feature-rollout \
  --publish 127.0.0.1:3000:3000 \
  --volume feature-rollout-data:/var/lib/postgresql/data \
  ghcr.io/leonardocaldas/feature-rollout:latest

Use com Docker Compose

Como alternativa ao docker run, salve o arquivo abaixo como compose.yaml. Execute docker compose pull e docker compose up -d. Para acompanhar a inicialização use docker compose logs -f; para parar sem apagar os dados use docker compose down.

services:
  feature-rollout:
    image: ghcr.io/leonardocaldas/feature-rollout:latest
    container_name: feature-rollout
    ports:
      - "127.0.0.1:3000:3000"
    volumes:
      - feature-rollout-data:/var/lib/postgresql/data
    restart: unless-stopped

volumes:
  feature-rollout-data:
    name: feature-rollout-data

Acesse e valide

Abra http://localhost:3000. Tanto / quanto /login entram diretamente no dashboard com o usuário Desenvolvedor local. APIs de escrita, integrações e audit log usam essa mesma identidade owner.

docker inspect --format '{{.State.Health.Status}}' feature-rollout
curl --fail http://localhost:3000/api/health

Persista e atualize

O volume feature-rollout-data sobrevive ao container. Para atualizar, faça pull da nova versão, remova somente o container e execute o mesmo docker run; as migrations pendentes rodam automaticamente.

docker pull ghcr.io/leonardocaldas/feature-rollout:latest
docker rm --force feature-rollout
# execute novamente o docker run da seção anterior

Opere no dia a dia

Use os comandos abaixo para iniciar, parar, reiniciar, inspecionar e acompanhar o serviço. Parar o container não remove o banco: o conteúdo permanece no volume feature-rollout-data.

docker start feature-rollout
docker stop feature-rollout
docker restart feature-rollout
docker ps --filter name=feature-rollout
docker logs --follow --tail 200 feature-rollout
curl --fail http://127.0.0.1:3000/api/health

Faça backup antes de mudanças importantes

O comando gera no diretório atual um dump completo e portátil do PostgreSQL 17. Faça isso antes de importar dados, trocar uma versão principal ou executar uma operação destrutiva. O backup não interrompe o painel.

Uma restauração substitui estado e deve ser feita em janela de manutenção, preferencialmente em um volume novo. Preserve o volume atual até validar o novo ambiente; nunca rode pg_restore --clean no container em uso.

docker exec -e PGPASSWORD=feature_rollout_local feature-rollout \
  pg_dump -h 127.0.0.1 \
  -U feature_rollout \
  -d feature_rollout \
  --format=custom \
  --no-owner \
  --no-acl > feature-rollout.dump

test -s feature-rollout.dump && echo "Backup criado"

Conecte agentes de IA com ferramentas locais

O modelo, isoladamente, não acessa o seu localhost. Um agente executado na mesma máquina — por exemplo, em uma IDE com terminal e navegador — pode abrir o painel ou chamar a API local. Use o navegador para fluxos completos e HTTP para operações determinísticas e auditáveis.

As APIs locais usam a identidade owner Desenvolvedor local. Por isso, mantenha o bind em 127.0.0.1 e conceda ao agente apenas o terminal ou navegador necessários. Um chat hospedado sem ferramenta conectada ao seu computador não consegue alcançar essa instância.

export FEATURE_ROLLOUT_LOCAL_URL=http://127.0.0.1:3000

# confirme o modo local antes de ler ou alterar recursos
curl --fail "$FEATURE_ROLLOUT_LOCAL_URL/api/health"

# exemplo de leitura das documentações de um portfólio
curl --fail \
  "$FEATURE_ROLLOUT_LOCAL_URL/api/applications/<applicationId>/documents"

# exemplo de alteração determinística de um item existente
curl --fail-with-body --request PATCH \
  "$FEATURE_ROLLOUT_LOCAL_URL/api/checklist/<itemId>" \
  --header 'Content-Type: application/json' \
  --data '{"completed":true}'

Dê um contrato seguro ao agente

Inclua estas regras no prompt ou nas instruções do agente. Elas tornam cada alteração revisável e evitam que uma automação trate uma exclusão ou um volume Docker como estado descartável.

Use http://127.0.0.1:3000 como o Feature Rollout local.
Antes de qualquer mutação, consulte /api/health e leia o recurso atual.
Use somente o dashboard ou endpoints HTTP documentados; não altere o PostgreSQL diretamente.
Mostre o plano ou diff antes de gravar.
Não exclua projetos, documentos, containers ou volumes sem confirmação humana explícita.
Depois de cada gravação, leia o recurso novamente e informe os IDs alterados.

Habilite análises de coerência

Para que o painel chame os modelos selecionados na análise de coerência, defina OPENROUTER_API_KEY no host e acrescente --env OPENROUTER_API_KEY ao docker run, ou a mesma variável na seção environment do Compose. O segredo é encaminhado em runtime e não deve ser gravado na imagem, no arquivo Compose ou no repositório.

export OPENROUTER_API_KEY='<sua-chave>'
# acrescente ao docker run:
--env OPENROUTER_API_KEY \
  ghcr.io/leonardocaldas/feature-rollout:latest

Construa o checkout atual

Dentro do repositório, o Compose constrói a imagem feature-rollout:local com todo o código atual. Repita o comando após alterações para validar a mesma forma de execução entregue aos demais desenvolvedores.

npm run docker:up
docker compose ps
npm run docker:logs

# depois de alterar o código
npm run docker:up

Diagnóstico rápido

Se a porta estiver ocupada, use FEATURE_ROLLOUT_PORT=3100 npm run docker:up. Logs de migrations e PostgreSQL aparecem em docker logs feature-rollout. O endpoint de saúde deve responder com database: connected, auth: local-bypass e mode: local.