Operar o stack

Depois de instalar com almirant install, os comandos ps, logs, upgrade e down cobrem tudo de que você precisa para manter a instância.

Todos presumem que o stack está em ~/.almirant/stack/. Se você o instalou com outro --dir, passe o mesmo --dir nos comandos a seguir.

Ver o status

almirant ps

Mostra o status de todos os contêineres (equivalente a docker compose ps em docker-compose.prod.yml). É importante que postgres, redis, backend, frontend e runner estejam em Up (healthy). Se algum aparecer como Exited ou Restarting, verifique seus logs.

Ler logs

Para acompanhar todos os logs em tempo real:

almirant logs -f

Para limitar a um serviço (mais rápido quando você procura algo específico):

almirant logs -f backend frontend

Somente as últimas N linhas:

almirant logs --tail 200 backend

Serviços úteis:

Serviço	Para quê
backend	Erros de API, autenticação, lógica de negócio
frontend	Erros de renderização SSR, build incompleto, 404 inesperados
db-init	Bootstrap de schema e seeds — existe somente durante a inicialização
postgres	Erros de conexão, crashes
runner	Jobs de agentes de IA
web-bridge	Comunicação em tempo real com o frontend

Atualizar para a versão mais recente

almirant upgrade

O upgrade executa três etapas em ordem:

1. git pull no diretório do stack.
2. Reconciliação de .env.production com .env.production.example. Se o upgrade introduzir novas variáveis obrigatórias (por exemplo, um segredo gerado, um caminho derivado), elas serão adicionadas automaticamente sem alterar as que você já tinha. Antes de qualquer alteração, é salvo um backup .env.production.bak.<unix-timestamp> ao lado do arquivo.
3. docker compose up -d --build --force-recreate: reconstrução das imagens e reinicialização dos contêineres. Os volumes de dados são preservados.

Inspecionar antes de aplicar

Para ver o que mudaria sem alterar nada:

almirant upgrade --check-env

Lista as variáveis que seriam adicionadas a .env.production e de onde viria cada valor (generated, derived, default, empty). Não executa o Docker nem grava o arquivo.

Pular a reconciliação do env

Se você gerencia .env.production com sua própria ferramenta (Ansible, sealed secrets etc.) e quer que a CLI não altere o arquivo:

almirant upgrade --no-env-sync

Nesse caso, você é responsável por manter .env.production compatível com o schema. Se uma variável obrigatória estiver ausente, docker compose up falhará com required variable X is missing a value.

Recuperar de uma sincronização que adicionou algo estranho

Cada almirant upgrade que modifica .env.production deixa um backup com timestamp:

ls -la ~/.almirant/stack/.env.production.bak.*
cp ~/.almirant/stack/.env.production.bak.<ts> ~/.almirant/stack/.env.production

Os backups não sofrem rotação automática; ocupam pouco espaço e mantêm a rastreabilidade de cada alteração.

Atualizar somente partes específicas

Se você sabe que apenas o frontend mudou, limite-o para executar mais rápido:

almirant upgrade frontend

Você pode passar vários serviços: almirant upgrade frontend backend.

Atualizar para uma versão específica

almirant upgrade --branch v1.3.0

Atualizar uma máquina remota via SSH

Se o stack estiver em outro servidor e você quiser atualizá-lo do seu laptop:

almirant upgrade --host [email protected]

A CLI se conecta por SSH e executa scripts/update-remote.sh na máquina de destino. Isso exige que a máquina já tenha o repositório clonado em ~/.almirant/stack/. A reconciliação de .env.production também é executada no host remoto, portanto, na primeira atualização após o stack adicionar novas variáveis obrigatórias, o remoto se autossincroniza como o local.

Atualização por clique no dashboard

A partir da versão do stack que inclui o sidecar updater, administradores veem um banner "Update now" no dashboard quando main está à frente do build em execução. É uma alternativa à CLI para administradores que não têm acesso ao shell da máquina do stack.

Como funciona

O backend detecta uma nova versão comparando seu SHA de build com main. Quando isso acontece, exibe um botão ao administrador. Ao pressioná-lo:

1. O backend faz POST para o sidecar updater (fica na rede interna do compose, não exposto).
2. O sidecar executa git pull --ff-only origin main + docker compose build + up -d --force-recreate para todos os serviços, exceto o próprio updater.
3. A UI mostra o progresso e permanece em "Restarting…" até que o novo backend responda aos healthchecks.

O sidecar é excluído da recriação para sobreviver à reconstrução que ele mesmo dispara.

Quando o botão aparece

• O usuário tem a função admin.
• O sidecar updater está em execução e acessível pelo backend (variáveis UPDATER_INTERNAL_URL e UPDATER_INTERNAL_TOKEN configuradas — o almirant upgrade as gera automaticamente quando estão ausentes).
• Há commits em main à frente do SHA do build atual.

Se o sidecar não estiver acessível, os administradores veem no lugar um botão "Copy command" que fornece o almirant upgrade pronto para colar em um shell.

Desativar a atualização por clique

Duas formas de manter somente a CLI:

# A) Quitar el sidecar del compose
cd ~/.almirant/stack
# editar docker-compose.prod.yml y comentar el bloque `updater:`
docker compose -f docker-compose.prod.yml --env-file .env.production up -d
# El backend cae al fallback "Copy command" automaticamente.

# B) Mantener el sidecar pero invalidar el token
sed -i '' 's|^UPDATER_INTERNAL_TOKEN=.*|UPDATER_INTERNAL_TOKEN=|' ~/.almirant/stack/.env.production
docker compose -f docker-compose.prod.yml --env-file .env.production up -d --force-recreate backend

Limitações

• Não seleciona serviços; sempre reconstrói tudo que não estiver na lista de exclusão.
• Não faz rollback se a reconstrução deixar o stack unhealthy. Para ter mais controle, use almirant upgrade <servicio> no shell.
• Se uma migração do novo build falhar, a saída não zero de db-init impede o backend de iniciar e você terá de diagnosticar com almirant logs db-init.

Para esses casos, recorra à CLI:

almirant upgrade --host [email protected]

Parar o stack

Sem perder dados (o normal — você pode iniciá-lo novamente com almirant upgrade ou uma nova instalação):

almirant down

Removendo imagens locais (para forçar uma reconstrução limpa na próxima instalação):

almirant down --rmi local

Removendo tudo, incluindo os volumes de dados (destrutivo):

almirant down --volumes

aviso

--volumes remove os dados do Postgres e do Redis de forma irreversível. Se você tiver trabalho que não quer perder, faça backup antes. Consulte docs/self-hosting/backups.md no repositório fonte para a estratégia de backup.

Alterar a URL pública

Esta é a alteração mais delicada porque NEXT_PUBLIC_SITE_URL é compilada no bundle do frontend. Alterar somente .env.production não basta.

Opção A — reinstalar de forma limpa (mais simples, destrutivo)

Se o stack for de teste e você não se importar em perder dados:

almirant down --volumes
almirant install --public-url https://nueva-url.example.com

Opção B — editar o env e reconstruir (preserva os dados)

cd ~/.almirant/stack

# 1. Edita las 4 variables relevantes en .env.production
sed -i '' \
  -e 's|^NEXT_PUBLIC_SITE_URL=.*|NEXT_PUBLIC_SITE_URL=https://nueva-url.example.com|' \
  -e 's|^BETTER_AUTH_URL=.*|BETTER_AUTH_URL=https://nueva-url.example.com|' \
  -e 's|^BETTER_AUTH_TRUSTED_ORIGINS=.*|BETTER_AUTH_TRUSTED_ORIGINS=https://nueva-url.example.com|' \
  -e 's|^CORS_ORIGIN=.*|CORS_ORIGIN=https://nueva-url.example.com|' \
  .env.production

# 2. Rebuild obligatorio de frontend + backend
docker compose -f docker-compose.prod.yml --env-file .env.production \
  up -d --build --force-recreate frontend backend

Adicionar uma origin sem reconstruir

Se você só precisa que o Better-Auth aceite uma origin adicional (por exemplo, permitir ao mesmo tempo http://localhost:8080 e sua URL do Tailscale), pode listar várias origens separadas por vírgula em BETTER_AUTH_TRUSTED_ORIGINS e CORS_ORIGIN, e reiniciar somente o backend sem reconstruir:

# .env.production
BETTER_AUTH_TRUSTED_ORIGINS=http://localhost:8080,https://mimac.tailnet.ts.net
CORS_ORIGIN=http://localhost:8080,https://mimac.tailnet.ts.net

cd ~/.almirant/stack
docker compose -f docker-compose.prod.yml --env-file .env.production \
  up -d --force-recreate backend

Observação: o frontend continuará fazendo chamadas ao valor de NEXT_PUBLIC_SITE_URL inserido no bundle. Se esse valor não corresponder à URL pela qual você acessa a aplicação, algumas chamadas falharão mesmo que CORS e a origin aceitem a solicitação. Para uma mudança definitiva, siga a Opção B completa.

Backup e restauração

Os dados da instância ficam no volume almirant-prod_postgres_prod_data. Para fazer um backup com a instância em execução:

docker compose -f ~/.almirant/stack/docker-compose.prod.yml --env-file ~/.almirant/stack/.env.production \
  exec postgres pg_dump -U almirant -d almirant > backup-$(date +%Y%m%d).sql

Consulte a documentação do repositório fonte (docs/self-hosting/backups.md) para estratégias de backup mais robustas, incluindo rotação e envio ao S3.

Alterar segredos

Se um segredo for comprometido (por exemplo, BETTER_AUTH_SECRET ou ENCRYPTION_KEY):

1. Edite o valor em ~/.almirant/stack/.env.production.
2. Reinicie os serviços afetados:

cd ~/.almirant/stack
docker compose -f docker-compose.prod.yml --env-file .env.production \
  up -d --force-recreate backend

aviso

Rotacionar ENCRYPTION_KEY invalida qualquer valor criptografado anteriormente (tokens OAuth salvos, integrações externas etc.). Esses tokens precisarão ser gerados de novo.

O que fazer se o stack não iniciar

Sequência de diagnóstico:

# 1. Ver que servicio esta caido
almirant ps

# 2. Logs del servicio problema
almirant logs --tail 200 <servicio>

# 3. Si es db-init (bootstrap de base de datos), es casi siempre:
#    - password authentication failed → reinstalar limpio
#    - Ver guia self-hosted → "Errores comunes"

# 4. Si es frontend, a menudo es build corrupto — fuerza rebuild sin cache:
cd ~/.almirant/stack
docker compose -f docker-compose.prod.yml --env-file .env.production \
  build --no-cache frontend
docker compose -f docker-compose.prod.yml --env-file .env.production \
  up -d --force-recreate frontend