Exploiter la stack

Une fois installée avec almirant install, les commandes ps, logs, upgrade et down couvrent tout ce dont vous avez besoin pour maintenir l'instance.

Elles supposent toutes que la stack se trouve dans ~/.almirant/stack/. Si vous l'avez installée avec un autre --dir, transmettez ce même --dir aux commandes suivantes.

Voir l'état

almirant ps

Affiche l'état de tous les conteneurs (équivalent à docker compose ps sur docker-compose.prod.yml). Vérifiez que postgres, redis, backend, frontend et runner sont en Up (healthy). Si l'un d'eux apparaît en Exited ou Restarting, consultez ses logs.

Lire les logs

Suivre tous les logs en temps réel :

almirant logs -f

Limiter à un service (plus rapide lorsque vous recherchez un élément précis) :

almirant logs -f backend frontend

Uniquement les N dernières lignes :

almirant logs --tail 200 backend

Services utiles :

Service	Usage
backend	Erreurs d'API, d'authentification et métier
frontend	Erreurs de rendu SSR, build incomplet, 404 inattendus
db-init	Initialisation du schéma et seeds — ne vit qu'au démarrage
postgres	Erreurs de connexion, crashes
runner	Jobs d'agents IA
web-bridge	Communication en temps réel avec le frontend

Mettre à jour vers la dernière version

almirant upgrade

La mise à jour exécute trois étapes dans l'ordre :

1. git pull dans le répertoire de la stack.
2. Réconciliation de .env.production avec .env.production.example. Si la mise à jour introduit de nouvelles variables obligatoires (par exemple un secret généré, un chemin dérivé), elles sont ajoutées automatiquement sans modifier celles déjà présentes. Avant toute modification, une sauvegarde .env.production.bak.<unix-timestamp> est écrite à côté du fichier.
3. docker compose up -d --build --force-recreate : reconstruit les images et redémarre les conteneurs. Les volumes de données sont conservés.

Inspecter avant d'appliquer

Pour voir ce qui changerait sans rien modifier :

almirant upgrade --check-env

Liste les variables qui seraient ajoutées à .env.production et l'origine de chaque valeur (generated, derived, default, empty). N'exécute pas Docker et n'écrit pas le fichier.

Ignorer la réconciliation de l'environnement

Si vous gérez .env.production avec vos propres outils (Ansible, sealed secrets, etc.) et voulez que le CLI ne touche pas au fichier :

almirant upgrade --no-env-sync

Dans ce cas, vous restez responsable de maintenir .env.production cohérent avec le schéma. S'il manque une variable obligatoire, docker compose up échouera avec required variable X is missing a value.

Restaurer après une synchronisation erronée

Chaque almirant upgrade qui modifie .env.production laisse une sauvegarde horodatée :

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

Les sauvegardes ne sont pas automatiquement nettoyées : elles occupent peu d'espace et assurent la traçabilité de chaque changement.

Mettre à jour uniquement certaines parties

Si vous savez que seul le frontend a changé, limitez la mise à jour pour aller plus vite :

almirant upgrade frontend

Vous pouvez transmettre plusieurs services : almirant upgrade frontend backend.

Mettre à jour vers une version précise

almirant upgrade --branch v1.3.0

Mettre à jour une machine distante via SSH

Si la stack réside sur un autre serveur et que vous souhaitez la mettre à jour depuis votre ordinateur portable :

almirant upgrade --host [email protected]

Le CLI se connecte par SSH et exécute scripts/update-remote.sh sur la machine cible. Cette machine doit déjà avoir le dépôt cloné dans ~/.almirant/stack/. La réconciliation de .env.production s'exécute également sur l'hôte distant ; ainsi, la première mise à jour après l'ajout de nouvelles variables obligatoires à la stack synchronise automatiquement le serveur distant comme la machine locale.

Mise à jour par clic depuis le dashboard

À partir de la version de la stack qui inclut le sidecar updater, les administrateurs voient une bannière "Update now" dans le dashboard lorsque main est en avance sur le build en cours. C'est une alternative au CLI pour les administrateurs qui n'ont pas d'accès shell à la machine de la stack.

Fonctionnement

Le backend détecte une nouvelle version en comparant son SHA de build à main. Lorsqu'il en détecte une, il affiche un bouton à l'administrateur. En cliquant dessus :

1. Le backend envoie une requête POST au sidecar updater (il se trouve sur le réseau interne Compose, non exposé).
2. Le sidecar exécute git pull --ff-only origin main + docker compose build + up -d --force-recreate pour tous les services, à l'exception de l'updater lui-même.
3. L'UI affiche la progression et reste sur "Restarting…" jusqu'à ce que le nouveau backend réponde aux healthchecks.

Le sidecar est exclu de la recréation pour survivre à la reconstruction qu'il déclenche lui-même.

Quand le bouton est visible

• L'utilisateur a le rôle admin.
• Le sidecar updater est en cours d'exécution et accessible depuis le backend (variables UPDATER_INTERNAL_URL et UPDATER_INTERNAL_TOKEN configurées — almirant upgrade les génère automatiquement si elles manquent).
• Des commits dans main sont en avance sur le SHA du build actuel.

Si le sidecar n'est pas accessible, les administrateurs voient à la place un bouton "Copy command" fournissant la commande almirant upgrade prête à coller dans un shell.

Désactiver la mise à jour par clic

Deux façons de n'utiliser que le 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

Limites

• Ne sélectionne pas de services — reconstruit toujours tout ce qui n'est pas dans la liste d'exclusion.
• Ne restaure pas la version précédente si la reconstruction rend la stack unhealthy. Pour davantage de contrôle, utilisez almirant upgrade <service> depuis le shell.
• Si une migration du nouveau build échoue, la sortie non nulle de db-init laisse le backend sans démarrer et vous devez diagnostiquer avec almirant logs db-init.

Pour ces cas, utilisez le CLI :

almirant upgrade --host [email protected]

Arrêter la stack

Sans perdre de données (le cas habituel — vous pouvez la redémarrer avec almirant upgrade ou une nouvelle installation) :

almirant down

En supprimant les images locales (pour forcer une reconstruction propre lors de la prochaine installation) :

almirant down --rmi local

En supprimant tout, y compris les volumes de données (destructif) :

almirant down --volumes

attention

--volumes supprime irréversiblement les données Postgres et Redis. Si vous avez du travail que vous ne voulez pas perdre, effectuez une sauvegarde avant. Consultez docs/self-hosting/backups.md dans le dépôt source pour la stratégie de sauvegarde.

Changer l'URL publique

Ce changement est particulièrement sensible, car NEXT_PUBLIC_SITE_URL est compilé dans le bundle du frontend. Modifier seulement .env.production ne suffit pas.

Option A — réinstaller proprement (plus simple, destructif)

Si la stack est destinée aux tests et que la perte de données ne vous importe pas :

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

Option B — modifier l'environnement et reconstruire (conserve les données)

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

Ajouter une origin sans reconstruction

Si vous avez seulement besoin que Better-Auth accepte une origin supplémentaire (par exemple pour autoriser à la fois http://localhost:8080 et votre URL Tailscale), vous pouvez en lister plusieurs, séparées par des virgules, dans BETTER_AUTH_TRUSTED_ORIGINS et CORS_ORIGIN, puis redémarrer uniquement le backend sans reconstruction :

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

Attention : le frontend continuera d'appeler la valeur de NEXT_PUBLIC_SITE_URL incluse dans le bundle. Si cette valeur ne correspond pas à l'URL à laquelle vous accédez, certains appels échoueront même si CORS et l'origin acceptent la requête. Pour un changement définitif, suivez l'option B en entier.

Sauvegarde et restauration

Les données de l'instance résident dans le volume almirant-prod_postgres_prod_data. Pour réaliser une sauvegarde pendant que l'instance s'exécute :

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

Consultez la documentation du dépôt source (docs/self-hosting/backups.md) pour des stratégies de sauvegarde plus robustes, notamment la rotation et l'envoi vers S3.

Changer les secrets

Si un secret est compromis (par exemple BETTER_AUTH_SECRET ou ENCRYPTION_KEY) :

1. Modifiez la valeur dans ~/.almirant/stack/.env.production.
2. Redémarrez les services concernés :

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

attention

La rotation de ENCRYPTION_KEY invalide toute valeur auparavant chiffrée (tokens OAuth enregistrés, intégrations externes, etc.). Ces tokens doivent être générés de nouveau.

Que faire si la stack ne démarre pas

Séquence de diagnostic :

# 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