Aller au contenu principal

Installation self-hosted

Ce guide vous accompagne de zéro jusqu'à une instance Almirant exécutée sur votre machine ou serveur.

Temps estimé : 15 à 25 minutes (la plus grande partie correspond à la construction initiale des images Docker).

Prérequis​

  • Docker 24+ et Docker Compose v2 installés et en cours d'exécution. Si vous exécutez la stack sur un Mac utilisé comme serveur depuis le terminal, lisez d'abord Runtime Docker sur macOS.
  • 4 Go de RAM et environ 10 Go d'espace disque libre.
  • Accès au dépôt almirant-ai/almirant sur GitHub. Tant que le dépôt est privé, vous avez besoin d'une méthode d'authentification git fonctionnelle (voir Étape 1). Cette étape ne sera plus nécessaire lorsque le dépôt deviendra public.
  • Une URL publique permettant d'accéder au service. Elle peut être :
    • http://localhost:8080 pour un usage local.
    • Un domaine personnel avec HTTPS.
    • Une URL Tailscale Funnel (https://<host>.<tailnet>.ts.net).
    • L'URL d'un tunnel (Cloudflare Tunnel, ngrok, etc.).

Runtime Docker sur macOS​

Sur macOS, Docker s'exécute dans une VM Linux. Le runtime est l'application qui gère cette VM. Trois options sont disponibles :

RuntimeIdéal pourCompromis
Docker DesktopDéveloppement sur Mac avec interface ouverteLourd (~500 Mo inactif), nécessite une session GUI active
OrbStackDéveloppement sur Mac avec interface ouverteTrès rapide, application de barre de menus — nécessite une session GUI active, payant pour un usage commercial
ColimaServeur headlessCLI uniquement, démarre comme service macOS — survit aux redémarrages sans connexion GUI, gratuit
Si vous utilisez le Mac comme serveur (accès uniquement par SSH)

Docker Desktop et OrbStack sont des applications macOS qui nécessitent qu'un utilisateur se soit connecté à la session graphique. Si le Mac redémarre et que personne ne le déverrouille, le daemon Docker reste arrêté et votre instance ne démarre pas non plus.

Pour un usage serveur, utilisez 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

Vérifiez qu'il répond :

docker ps   # debe responder en menos de un segundo

Changer de runtime avec des données existantes​

Passer d'OrbStack/Desktop à Colima supprime les volumes (ils se trouvent dans la VM de l'ancien runtime). Si vous avez déjà des données importantes :

  1. Avec l'ancien runtime actif, exportez : pg_dump pour Postgres, un snapshot manuel pour Redis si vous l'utilisez.
  2. Arrêtez la stack : almirant down.
  3. Installez et démarrez Colima.
  4. Changez le contexte : docker context use colima.
  5. Exécutez à nouveau almirant install ou almirant upgrade pour créer les nouveaux volumes.
  6. Restaurez les dumps.

Si l'instance est nouvelle ou vide, passez directement à l'étape 1.

Étape 1 — Authentifier git auprès de GitHub​

info

Cette étape disparaîtra lorsque le dépôt Almirant deviendra public. Si vous lisez ce document après cette transition, ignorez-la.

L'installateur exécute git clone https://github.com/almirant-ai/almirant.git. Si le dépôt est privé, git demande des identifiants. La méthode la plus propre consiste à utiliser 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

Vérifiez que le credential helper de gh a été configuré :

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

Si, sur macOS, des erreurs comme failed to get: -25308 apparaissent pendant le clone, votre Keychain est verrouillé (cas typique des sessions SSH sans interface graphique). Déverrouillez-le :

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

Étape 2 — Installer le CLI​

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

Étape 3 — Lancer almirant install​

La méthode la plus recommandée consiste à transmettre --public-url dès le départ avec l'URL exacte par laquelle vous accéderez au service :

almirant install --public-url https://almirant.miempresa.com
Pourquoi l'URL publique est importante

almirant install inclut l'URL publique dans quatre variables simultanément :

  • NEXT_PUBLIC_SITE_URL (compilée dans le bundle du frontend)
  • BETTER_AUTH_URL
  • BETTER_AUTH_TRUSTED_ORIGINS
  • CORS_ORIGIN

Si vous accédez plus tard par une URL différente (par exemple vous avez indiqué http://localhost:8080, mais vous accédez à https://mimac.tailnet.ts.net), Better-Auth rejette la requête avec Invalid origin et l'inscription échoue.

Changer l'URL ensuite nécessite de reconstruire le frontend. Consultez Changer l'URL publique.

L'installateur :

  1. Vérifie les prérequis (Docker + Compose v2).
  2. Clone almirant-ai/almirant dans ~/.almirant/stack (ou effectue un fast-forward s'il existe déjà).
  3. Génère .env.production avec des secrets aléatoires s'il n'existe pas.
  4. Construit les images Docker (backend, frontend, runner, db-init, shims…). La première fois, cela prend 10 à 20 minutes.
  5. Démarre la stack avec docker compose up -d.
  6. Attend que le frontend soit healthy.
  7. Affiche l'URL finale et les commandes de jour 2.

Flags install importants​

FlagQuand l'utiliser
--public-urlChaque fois que possible. Évite de devoir reconstruire plus tard.
--non-interactiveScripts CI ou provisionnement automatisé.
--with-proxySi vous souhaitez utiliser le reverse proxy (Caddy) intégré, au lieu d'exposer des ports directs.
--with-discordSi vous utilisez le bridge Discord.
--branchPour fixer une version précise (v1.2.3) au lieu de main.
--from-dirInstallations air-gapped depuis un clone déjà présent sur le disque.

Consultez la liste complète dans Référence → install.

Étape 4 — Terminer l'onboarding​

Ouvrez l'URL affichée par l'installateur. La première visite vous amène à /signup.

  • Si la base de données est vide (premier démarrage propre), le formulaire fonctionne en mode initial_admin_setup : le premier utilisateur enregistré reçoit le rôle admin et est redirigé vers l'assistant dans /onboarding.
  • S'il existe déjà des utilisateurs (par exemple parce que vous avez réinstallé en réutilisant le même volume Postgres), le formulaire fonctionne comme une inscription normale : le nouvel utilisateur n'est pas administrateur et arrive sur le dashboard. Pour forcer un premier administrateur propre, consultez Repartir de zéro.

L'assistant de /onboarding comprend trois étapes, chacune avec le bouton "Skip for now" :

  1. Admin account — confirme que le premier administrateur existe et ferme l'inscription ouverte.
  2. Public URL (Tailscale) — permet de publier l'instance avec Tailscale Funnel ou de saisir une URL externe.
  3. GitHub App — crée une GitHub App avec un manifest prérempli ou accepte des identifiants existants afin que les agents puissent ouvrir des PR.

Une fois terminé, l'application est prête. Le lien vers /onboarding reste visible dans la barre latérale tant que toutes les étapes ne sont pas terminées.

Étape facultative — Protéger Postgres avec Tailscale​

Par défaut, Postgres réside dans Docker et ne doit pas être exposé sur l'interface publique du VPS. Si vous devez vous y connecter depuis votre ordinateur portable avec TablePlus, DBeaver, DataGrip ou psql, créez un accès privé avec Tailscale.

Le principe est le suivant :

  • Votre ordinateur portable rejoint votre tailnet Tailscale normal.
  • Almirant crée un nœud séparé nommé par défaut almirant-db.
  • Ce nœud écoute uniquement sur le réseau privé Tailscale et transmet le port 5432 au Postgres interne de Docker.
  • Postgres reste non exposé sur Internet.
N'ouvrez pas Postgres dans le firewall du VPS

Ne publiez pas 5432:5432 et n'ouvrez pas le port 5432 sur Internet « pour tester ». Cela fonctionne, mais fournit de mauvaises bases de sécurité. La base de données doit rester accessible uniquement aux appareils autorisés de votre tailnet.

1. Préparer votre tailnet​

Installez d'abord Tailscale sur votre ordinateur portable et connectez-vous. Dans le panneau Tailscale, vérifiez que votre machine apparaît sous Machines.

Ensuite, dans Access controls, déclarez un tag pour le nœud de base de données :

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

Si vous avez déjà tagOwners, ne le remplacez pas entièrement : ajoutez uniquement l'entrée tag:almirant-db.

2. Limiter les accès à Postgres​

Ajoutez une règle permettant à votre utilisateur d'accéder au nœud de base de données uniquement par TCP 5432 :

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

Remplacez [email protected] par l'e-mail que vous utilisez pour Tailscale.

Commencez simplement

Si vous débutez avec Tailscale, utilisez une Auth Key. Le flux OAuth client est préférable pour une automatisation avancée, mais ajoute des concepts inutiles pour la première configuration.

3. Créer une Auth Key pour Almirant​

Dans Tailscale Admin :

  1. Accédez à Keys.
  2. Cliquez sur Generate auth key.
  3. Utilisez une description telle que Almirant DB.
  4. Activez le tag tag:almirant-db.
  5. Si votre tailnet nécessite l'approbation des appareils, marquez la clé comme pre-approved.
  6. Copiez la clé. Elle doit commencer par tskey-auth-....

N'enregistrez pas cette clé dans le dépôt et ne la collez pas dans des issues, logs ou captures d'écran.

4. Connecter Almirant au tailnet​

Dans Almirant, connectez-vous en tant qu'administrateur puis accédez à :

/settings/instance

Dans Private database access :

ChampValeur recommandée
Hostnamealmirant-db
Tagtag:almirant-db
MéthodeAuth key
Auth keyLa clé Tailscale tskey-auth-...

Cliquez sur Connect. Pendant le provisioning, attendez que l'état devienne connected.

Une fois terminé, Almirant affiche une chaîne de connexion similaire à :

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

Utilisez cette URL depuis votre ordinateur portable connecté à Tailscale.

5. Checklist si la connexion échoue​

Vérifiez dans cet ordre :

  1. Votre ordinateur portable est connecté à Tailscale.
  2. Une machine nommée almirant-db apparaît dans Tailscale Admin.
  3. Cette machine porte le tag tag:almirant-db.
  4. La règle d'accès autorise tcp:5432 vers tag:almirant-db.
  5. Dans Almirant, l'état de Private database access est connected.
  6. Vous utilisez la chaîne de connexion affichée par Almirant, et non le DATABASE_URL interne du conteneur.

Si MagicDNS ne résout pas le hostname, utilisez temporairement l'IP Tailscale 100.x.y.z affichée par Almirant.

Étape 5 — Connecter le CLI à votre instance​

Jusqu'ici, vous avez installé la stack. Configurez maintenant le CLI pour qu'il pointe vers cette instance et pouvoir exécuter init / link dans vos dépôts. Cette étape s'effectue une fois par machine depuis laquelle vous utiliserez le CLI (ordinateur portable, VM de développement, serveur lui-même, etc.).

5.1 — Identifier l'URL de l'API​

L'URL API est votre --public-url suivi de /api :

--public-url de l'installationURL 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 — Authentifier le CLI​

Depuis la machine où vous utiliserez le 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

Le navigateur s'ouvre vers votre instance, vous autorisez la session et le CLI récupère une clé API qu'il enregistre dans ~/.almirant/config.json. Le compte reçoit un ID stable et un label local que vous pouvez renommer.

Depuis une autre machine

Cette étape est indépendante de l'emplacement où la stack s'exécute. Si elle réside sur un serveur distant et que vous voulez utiliser le CLI depuis votre ordinateur portable, il suffit que celui-ci puisse accéder à l'URL API en HTTPS. Si elle est derrière Tailscale, assurez-vous d'appartenir au même tailnet ; si elle est derrière un tunnel/proxy, vérifiez que le port est accessible.

5.3 — Vérifier la configuration​

almirant accounts list
almirant current

Vous devriez voir votre compte self-hosted dans la liste, avec l'API URL pointant vers votre instance et la clé API représentée uniquement par son préfixe.

Si vous avez plusieurs comptes (par exemple vous travaillez aussi avec le SaaS almirant.ai), attribuez des labels et choisissez le compte actif :

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

Plus de détails dans Travailler avec plusieurs comptes.

5.4 — Lier un dépôt​

Avec le compte authentifié, lier un dépôt à un projet de votre instance est identique au flux SaaS :

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

Le CLI écrit .mcp.json avec almirant mcp proxy --project-id ... --account .... La clé API ne reste pas dans le dépôt ; elle se trouve dans ~/.almirant/config.json et le proxy l'attache en mémoire.

Le flux complet, étape par étape (avec vérification depuis l'IDE), est décrit dans Connecter un dépôt.

Repartir de zéro​

Si quelque chose s'est mal passé et que vous souhaitez repartir avec une base de données propre (détruit toutes les données de la stack locale) :

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

almirant down --volumes supprime les volumes Postgres et Redis. Utilisez-le uniquement pour les installations de test ou si vous êtes certain de vouloir perdre les données.

Erreurs fréquentes lors de la première installation​

password authentication failed for user "almirant"​

Cela signifie que le volume Postgres contient un ancien mot de passe d'une installation précédente, différent de celui qui vient d'être généré dans .env.production. Postgres ne lit POSTGRES_PASSWORD depuis l'environnement qu'au premier démarrage du volume.

Correctif : supprimez les volumes et réinstallez (voir Repartir de zéro).

Invalid origin lors de l'inscription​

L'URL depuis laquelle vous accédez n'est pas incluse dans BETTER_AUTH_TRUSTED_ORIGINS.

Correctif : réinstallez avec --public-url égal à l'URL exacte de la barre d'adresse du navigateur :

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

Si vous avez déjà des données que vous ne voulez pas perdre, vous pouvez changer l'URL sans réinstaller : voir Changer l'URL publique.

404 après l'inscription​

Cause la plus fréquente : votre utilisateur n'a pas le rôle admin (la base de données contenait déjà des utilisateurs d'une tentative précédente) et la redirection l'envoie vers /board, ce qui peut échouer si aucun projet n'a encore été créé.

Correctif : repartez de zéro afin que votre première inscription utilise le mode initial_admin_setup.

docker ps reste bloqué / sans réponse​

Le client Docker attend le socket du daemon. Si ce socket pointe vers un runtime inactif, il reste bloqué.

Diagnostic rapide :

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.

Correctifs selon le scénario :

  • Docker Desktop ou OrbStack est installé mais l'application est fermée → ouvrez-la : open -a OrbStack (ou open -a "Docker Desktop"). Attendez 30 à 60 secondes, puis réessayez docker ps.
  • L'application est démarrée mais la VM est bloquée → fermez-la et rouvrez-la, ou exécutez colima stop && colima start si vous utilisez Colima.
  • Vous avez changé de runtime et le context pointe vers l'ancien → docker context use colima (ou le nom correct).
  • Mac utilisé comme serveur et vous souhaitez survivre aux redémarrages → migrez vers Colima comme service (voir Runtime Docker sur macOS).

lockfile had changes, but lockfile is frozen pendant le build​

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

Cela survient lorsque le dépôt de la stack introduit un nouvel espace de travail bun et qu'un Dockerfile n'a pas été mis à jour pour le copier dans le contexte de build. C'est un bug de la stack, pas de votre installation.

Correctif : exécutez git pull dans le dépôt de la stack pour obtenir la dernière version (qui inclut déjà le correctif), puis réessayez :

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

Si votre version de la stack est antérieure au correctif et que vous ne pouvez pas la mettre à jour, ajoutez manuellement la ligne COPY services/<workspace>/package.json ./services/<workspace>/package.json dans les Dockerfiles concernés avant bun install.

Erreurs Docker liées au keychain sur macOS​

error getting credentials — err: exit status 1, out: keychain cannot be accessed apparaît lorsque vous travaillez par SSH sur un Mac sans session graphique.

Correctif rapide :

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

Correctif permanent (uniquement si vous travaillez toujours via SSH) :

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

Étape suivante​

Stack exécutée, administrateur créé, onboarding terminé. Pour exploiter l'instance au quotidien (logs, mises à jour, sauvegardes, changements d'URL), consultez Exploiter la stack.