Pular para o conteúdo principal

Instalação self-hosted

Este guia leva você do zero a uma instância do Almirant em execução na sua máquina ou servidor.

Tempo estimado: 15-25 minutos (a maior parte é a construção das imagens Docker na primeira vez).

Requisitos​

  • Docker 24+ e Docker Compose v2 instalados e em execução. Se você for executar o stack em um Mac usado como servidor por terminal, leia primeiro Runtime do Docker no macOS.
  • 4 GB de RAM e ~10 GB de espaço livre em disco.
  • Acesso ao repositório almirant-ai/almirant no GitHub. Enquanto o repositório for privado, você precisa de um método funcional de autenticação git (veja Passo 1). Quando o repositório se tornar público, esta etapa deixará de ser necessária.
  • Uma URL pública pela qual o serviço será acessado. Pode ser:
    • http://localhost:8080 para uso local.
    • Um domínio próprio com HTTPS.
    • Uma URL do Tailscale Funnel (https://<host>.<tailnet>.ts.net).
    • A URL de um túnel (Cloudflare Tunnel, ngrok etc.).

Runtime do Docker no macOS​

No macOS, o Docker é executado dentro de uma VM Linux. O "runtime" é o app que gerencia essa VM. Há três opções:

RuntimeMelhor paraTradeoff
Docker DesktopDesenvolvimento no Mac com UI abertaPesado (~500 MB em idle), exige sessão de GUI ativa
OrbStackDesenvolvimento no Mac com UI abertaMuito rápido, app da barra de menus — exige sessão de GUI ativa, pago para uso comercial
ColimaServidor headlessSomente CLI, inicia como serviço do macOS — sobrevive a reinicializações sem login na GUI, gratuito
Se você usa o Mac como servidor (acesso apenas por SSH)

Docker Desktop e OrbStack são apps do macOS que exigem que um usuário tenha feito login na sessão gráfica. Se o Mac reiniciar e ninguém desbloqueá-lo, o daemon do Docker ficará inativo e sua instância também não iniciará.

Para uso como servidor, use o Colima:

brew install colima docker docker-compose

# Sizing tipico para un Mac de 16 GB / 8 cores
colima start --cpu 4 --memory 6 --disk 40

# Que arranque solo al boot (sin necesidad de login GUI)
colima stop
brew services start colima

Verifique se ele responde:

docker ps   # debe responder en menos de un segundo

Alterar o runtime com dados existentes​

Mudar de OrbStack/Desktop para Colima remove os volumes (eles ficam dentro da VM do runtime antigo). Se você já tiver dados importantes:

  1. Com o runtime antigo em execução, exporte: pg_dump para o Postgres e snapshot manual para o Redis, se você o usar.
  2. Pare o stack: almirant down.
  3. Instale e inicie o Colima.
  4. Altere o contexto: docker context use colima.
  5. Execute novamente almirant install ou almirant upgrade para criar os novos volumes.
  6. Restaure os dumps.

Se a instância for nova ou estiver vazia, vá direto para o Passo 1.

Passo 1 — Autenticar o git no GitHub​

informação

Esta etapa desaparecerá quando o repositório do Almirant se tornar público. Se você estiver lendo isto depois dessa transição, pule-a.

O instalador executa git clone https://github.com/almirant-ai/almirant.git. Se o repositório for privado, o git solicitará credenciais. A forma mais limpa é usar gh:

# Instala gh si no lo tienes
brew install gh           # macOS
sudo apt install gh       # Debian/Ubuntu

# Login interactivo — elige protocolo HTTPS (no SSH)
gh auth login
# GitHub.com → HTTPS → Login with a web browser

# Configura git para usar las credenciales de gh
gh auth setup-git

Verifique se o credential helper do gh foi configurado:

git config --global --get-all credential.https://github.com.helper
# Debe mostrar: !/opt/homebrew/bin/gh auth git-credential   (o similar)

Se no macOS você vir erros como failed to get: -25308 durante o clone, seu Keychain está bloqueado (típico em sessões SSH sem interface gráfica). Desbloqueie-o:

security unlock-keychain ~/Library/Keychains/login.keychain-db

Passo 2 — Instalar a CLI​

bun add -g almirant@latest
# o
npm i -g almirant

Passo 3 — Executar almirant install​

A forma mais recomendada é passar --public-url desde o início com a URL exata pela qual você acessará o serviço:

almirant install --public-url https://almirant.miempresa.com
Por que a URL pública importa

almirant install insere a URL pública em quatro variáveis simultaneamente:

  • NEXT_PUBLIC_SITE_URL (compilada no bundle do frontend)
  • BETTER_AUTH_URL
  • BETTER_AUTH_TRUSTED_ORIGINS
  • CORS_ORIGIN

Se você acessar depois por uma URL diferente (por exemplo, definiu http://localhost:8080, mas acessa por https://mimac.tailnet.ts.net), o Better-Auth rejeitará a solicitação com Invalid origin e o cadastro falhará.

Alterar a URL depois exige uma reconstrução do frontend. Veja Alterar a URL pública.

O instalador:

  1. Verifica os requisitos (Docker + Compose v2).
  2. Clona almirant-ai/almirant em ~/.almirant/stack (ou faz fast-forward se já existir).
  3. Gera .env.production com segredos aleatórios, se ele não existir.
  4. Constrói as imagens Docker (backend, frontend, runner, db-init, shims…). Na primeira vez, demora 10-20 minutos.
  5. Inicia o stack com docker compose up -d.
  6. Aguarda até que o frontend esteja healthy.
  7. Imprime a URL final e os comandos do dia 2.

Flags importantes de install​

FlagQuando usar
--public-urlSempre que puder. Evita ter de reconstruir depois.
--non-interactiveScripts de CI ou provisionamento automático.
--with-proxySe você quiser o proxy reverso integrado (Caddy), em vez de expor portas diretamente.
--with-discordSe você for usar a ponte com o Discord.
--branchPara fixar uma versão específica (v1.2.3) em vez de main.
--from-dirInstalações air-gapped a partir de um clone já presente em disco.

Veja a lista completa em Referência → install.

Passo 4 — Concluir o onboarding​

Abra a URL exibida pelo instalador. A primeira visita leva você a /signup.

  • Se o banco de dados estiver vazio (primeira inicialização limpa), o formulário funciona no modo initial_admin_setup: o primeiro usuário registrado é criado com a função admin e redirecionado ao assistente em /onboarding.
  • Se já houver usuários (por exemplo, porque você reinstalou reutilizando o mesmo volume do Postgres), o formulário funciona como um cadastro normal: o usuário recém-criado não é admin e vai para o dashboard. Se quiser forçar um primeiro admin limpo, veja Começar do zero.

O assistente de /onboarding tem três etapas, todas com o botão "Skip for now":

  1. Admin account — confirma que o primeiro administrador existe e fecha o cadastro aberto.
  2. Public URL (Tailscale) — permite publicar a instância com Tailscale Funnel ou inserir uma URL externa própria.
  3. GitHub App — cria uma GitHub App com um manifesto pré-preenchido ou aceita credenciais já existentes, para que os agentes possam abrir PRs.

Ao concluir, a aplicação está pronta. O link para /onboarding permanece visível na barra lateral até você concluir todas as etapas.

Etapa opcional — Proteger o Postgres com Tailscale​

Por padrão, o Postgres fica dentro do Docker e não deve ser exposto na interface pública do VPS. Se você precisar se conectar do seu laptop com TablePlus, DBeaver, DataGrip ou psql, a forma segura é criar um acesso privado pelo Tailscale.

A ideia é a seguinte:

  • Seu laptop entra na sua tailnet normal do Tailscale.
  • O Almirant cria um nó separado chamado, por padrão, almirant-db.
  • Esse nó escuta somente na rede privada do Tailscale e encaminha a porta 5432 para o Postgres interno do Docker.
  • O Postgres continua sem ser publicado na internet.
Não abra o Postgres no firewall do VPS

Não publique 5432:5432 nem abra a porta 5432 para a internet "só para testar". Isso funciona, mas é uma base ruim de segurança. O banco de dados deve ficar acessível somente por dispositivos autorizados dentro da sua tailnet.

1. Prepare sua tailnet​

Primeiro, instale o Tailscale no seu laptop e inicie sessão. No painel do Tailscale, verifique se sua máquina aparece em Machines.

Depois, em Access controls, declare uma tag para o nó do banco de dados:

"tagOwners": {
  "tag:almirant-db": ["autogroup:admin"]
}

Se você já tiver tagOwners, não o substitua por completo: adicione somente a entrada tag:almirant-db.

2. Limite quem pode acessar o Postgres​

Adicione uma regra que permita ao seu usuário acessar o nó do banco de dados somente por TCP 5432:

"grants": [
  {
    "src": ["[email protected]"],
    "dst": ["tag:almirant-db"],
    "ip": ["tcp:5432"]
  }
]

Substitua [email protected] pelo email usado para acessar o Tailscale.

Comece de forma simples

Se você está começando a usar o Tailscale, use uma Auth Key. O fluxo com cliente OAuth é melhor para automação avançada, mas adiciona conceitos desnecessários para a primeira configuração.

3. Crie uma Auth Key para o Almirant​

No Tailscale Admin:

  1. Vá até Keys.
  2. Clique em Generate auth key.
  3. Use uma descrição como Almirant DB.
  4. Ative a tag tag:almirant-db.
  5. Se sua tailnet exigir aprovação de dispositivos, marque a key como pre-approved.
  6. Copie a key. Ela deve começar com tskey-auth-....

Não guarde essa key no repositório nem a cole em issues, logs ou capturas de tela.

4. Conecte o Almirant à tailnet​

No Almirant, entre como admin e vá para:

/settings/instance

Em Private database access:

CampoValor recomendado
Hostnamealmirant-db
Tagtag:almirant-db
MétodoAuth key
Auth keyA key tskey-auth-... do Tailscale

Clique em Connect. Enquanto estiver em provisioning, aguarde até que o status mude para connected.

Quando concluir, o Almirant mostrará uma connection string semelhante a:

postgresql://...@almirant-db.<tu-tailnet>.ts.net:5432/...

Use essa URL do seu laptop, enquanto estiver conectado ao Tailscale.

5. Checklist se não conectar​

Verifique nesta ordem:

  1. Seu laptop está conectado ao Tailscale.
  2. No Tailscale Admin, aparece uma máquina chamada almirant-db.
  3. Essa máquina tem a tag tag:almirant-db.
  4. A regra de acesso permite tcp:5432 para tag:almirant-db.
  5. No Almirant, o status de Private database access é connected.
  6. Você está usando a connection string mostrada pelo Almirant, não a DATABASE_URL interna do contêiner.

Se o MagicDNS não resolver o hostname, use temporariamente o IP do Tailscale 100.x.y.z mostrado pelo Almirant.

Passo 5 — Conectar a CLI à sua instância​

Até aqui você instalou o stack. Agora é preciso configurar a CLI para apontar para essa instância e poder executar init / link nos seus repositórios. Esta etapa é feita uma vez por máquina na qual você usar a CLI (seu laptop, uma VM de desenvolvimento, o próprio servidor etc.).

5.1 — Identifique a URL da API​

A URL da API é seu --public-url com /api no final:

--public-url do installURL da API
https://almirant.miempresa.comhttps://almirant.miempresa.com/api
https://<host>.<tailnet>.ts.nethttps://<host>.<tailnet>.ts.net/api
http://localhost:8080http://localhost:8080/api

5.2 — Autentique a CLI​

Da máquina na qual você usará a CLI:

# Instala el CLI si aun no lo tienes en esa maquina
bun add -g almirant@latest

# Login contra tu instancia self-hosted
almirant login --api-url https://almirant.miempresa.com/api

O navegador abre sua instância, você autoriza a sessão e a CLI captura uma API key que salva em ~/.almirant/config.json. A conta fica com um ID estável e um rótulo local que você pode renomear.

De outra máquina

Esta etapa é independente de onde o stack é executado. Se o stack estiver em um servidor remoto e você quiser usar a CLI do seu laptop, basta que seu laptop possa acessar a URL da API por HTTPS. Se estiver atrás do Tailscale, certifique-se de estar na mesma tailnet; se estiver atrás de um túnel/proxy, que a porta esteja acessível.

5.3 — Verifique a configuração​

almirant accounts list
almirant current

Você deverá ver sua conta self-hosted na lista, com API URL apontando para sua instância e a API key representada apenas pelo prefixo.

Se você tiver várias contas (por exemplo, também trabalha com o SaaS de almirant.ai), dê rótulos a elas e escolha qual está ativa:

almirant accounts rename 1 prod-saas
almirant accounts rename 2 local-m1pro
almirant use local-m1pro

Mais detalhes em Trabalhar com várias contas.

5.4 — Vincule um repositório​

Com a conta autenticada, vincular um repositório a um projeto da sua instância é idêntico ao fluxo SaaS:

cd mi-repo
almirant link
# Si tienes varias cuentas, elige la self-hosted
# Selecciona un proyecto o crea uno nuevo

A CLI grava .mcp.json com almirant mcp proxy --project-id ... --account .... A API key não fica no repositório; ela fica em ~/.almirant/config.json e o proxy a anexa em memória.

O fluxo completo passo a passo (com verificação pelo IDE) está em Conectar um repositório.

Começar do zero​

Se algo der errado e você quiser começar com um banco de dados limpo (destrói todos os dados do stack local):

almirant down --volumes
almirant install --public-url https://almirant.miempresa.com
aviso

almirant down --volumes remove os volumes do Postgres e do Redis. Use-o somente em instalações de teste ou quando tiver certeza de que deseja perder os dados.

Erros comuns na primeira instalação​

password authentication failed for user "almirant"​

Isso significa que o volume do Postgres tem uma senha antiga de uma instalação anterior, diferente da que acabou de ser gerada em .env.production. O Postgres só lê POSTGRES_PASSWORD do env na primeira inicialização do volume.

Correção: remova os volumes e reinstale (veja Começar do zero).

Invalid origin ao se cadastrar​

A URL pela qual você acessa não está em BETTER_AUTH_TRUSTED_ORIGINS.

Correção: reinstale com --public-url igual à URL exata da barra do navegador:

almirant install --public-url https://<lo-que-ves-en-tu-navegador>

Se você já tiver dados que não quer perder, é possível alterar a URL sem reinstalar: veja Alterar a URL pública.

404 após o signup​

Causa mais comum: seu usuário não tem a função admin (o banco de dados já tinha usuários de uma tentativa anterior) e o redirecionamento o envia para /board, que pode falhar se ainda não houver projetos criados.

Correção: comece do zero para que seu primeiro cadastro esteja no modo initial_admin_setup.

docker ps trava / não responde​

O cliente Docker espera pelo socket do daemon. Se esse socket apontar para um runtime que não está em execução, ele trava.

Diagnóstico rápido:

docker context ls
# Mira que context tiene el `*` y a que socket apunta.

ls -la /var/run/docker.sock 2>&1
ls -la ~/.docker/run/docker.sock 2>&1
ls -la ~/.orbstack/run/docker.sock 2>&1
# El socket del context activo tiene que existir y tener permiso de escritura.

pgrep -lf -i 'OrbStack|Docker Desktop|colima' | head -5
# Tiene que aparecer al menos uno.

Correções conforme o cenário:

  • Docker Desktop ou OrbStack instalado, mas o app está fechado → abra o app: open -a OrbStack (ou open -a "Docker Desktop"). Aguarde 30-60 s e tente docker ps novamente.
  • App iniciado, mas a VM está travada → feche e abra novamente ou execute colima stop && colima start se usar Colima.
  • Você mudou de runtime e o context aponta para o antigo → docker context use colima (ou o nome correto).
  • Mac usado como servidor e você quer que sobreviva a reinicializações → migre para o Colima como serviço (veja Runtime do Docker no macOS).

lockfile had changes, but lockfile is frozen durante o build​

RUN bun install --frozen-lockfile
error: lockfile had changes, but lockfile is frozen

Isso acontece quando o repositório do stack introduziu um novo workspace bun e algum Dockerfile não foi atualizado para copiá-lo para o contexto do builder. É um bug do stack, não da sua instalação.

Correção: execute git pull no repositório do stack para obter a versão mais recente (que já inclui a correção) e tente novamente:

cd ~/.almirant/stack
git pull --ff-only origin main
almirant upgrade

Se sua versão do stack for anterior à correção e você não puder atualizá-la, adicione manualmente a linha COPY services/<workspace>/package.json ./services/<workspace>/package.json nos Dockerfiles afetados antes de bun install.

Erros do Docker com Keychain no macOS​

error getting credentials — err: exit status 1, out: keychain cannot be accessed aparece quando você opera por SSH em um Mac sem sessão gráfica.

Correção rápida:

security unlock-keychain ~/Library/Keychains/login.keychain-db

Correção permanente (somente se você sempre operar por SSH):

# Desconecta Docker del keychain
jq 'del(.credsStore, .credHelpers)' ~/.docker/config.json > ~/.docker/config.json.tmp \
  && mv ~/.docker/config.json.tmp ~/.docker/config.json

Próxima etapa​

Stack em execução, admin criado, onboarding concluído. Para operar a instância no dia a dia (logs, upgrades, backups, alterações de URL), vá para Operar o stack.