Déploiement et exploitation

Déployer sur Coolify

Cette page décrit la création d'une ressource Coolify pour l'instance, puis le premier déploiement. Elle se termine par le déploiement du site de documentation, qui est une ressource séparée.

Qui peut le faire : l'exploitant, avec les droits de création de ressource dans Coolify et l'accès à la GitHub App qui lit le dépôt source.

Avant de commencer#

  • Un serveur Coolify relié au dépôt source par une GitHub App de Coolify.
  • Un nom de domaine HTTPS pour l'instance, par exemple maintenance.maintain.example.
  • Le coffre de l'équipe, pour y ranger les secrets.
  • Les variables de Variables d'environnement sous la main.

Pas à pas#

  1. Préparer les secrets. Générez séparément APP_KEY, OTP_HMAC_KEY, POSTGRES_SUPERUSER_PASSWORD, MVP_DB_MIGRATION_PASSWORD, MVP_DB_RUNTIME_PASSWORD et REDIS_PASSWORD. Rangez-les d'abord dans le coffre : ils sont indispensables à une restauration.
  2. Créer la ressource. Dans le projet et l'environnement Coolify voulus : New Resource, dépôt privé via la GitHub App, branche à déployer (main par défaut), build pack Docker Compose.
  3. Désigner le fichier Compose. Base Directory : /. Docker Compose Location : /compose.mvp.yaml. N'ajoutez jamais la surcouche locale infra/compose/mvp.local.yaml.
  4. Transmettre le commit. Activez Include Source Commit in Build. Sans cette option, l'image affiche le commit unknown.
  5. Saisir les variables. Dans Environment Variables, saisissez chaque variable. Cochez Is Secret pour les mots de passe, clés et jetons. Utilisez une variable multiligne pour la clé privée de la GitHub App. APP_URL est l'origine HTTPS publique, sans chemin.
  6. Associer le domaine. Associez uniquement le service web à https://maintenance.maintain.example:3333. Le suffixe :3333 désigne le port interne, pas un port public. Aucun autre service ne reçoit de domaine.
  7. Vérifier le stockage. Dans Storages, vérifiez les trois volumes nommés postgres-data, redis-data et platform-storage. Ne les remplacez pas par des dossiers de l'hôte sans vérifier l'UID propriétaire.
  8. Déployer. Cliquez sur Deploy. Dans les journaux, suivez : la construction, Rôles MVP initialisés (premier démarrage seulement), release_completed avec le bon commit, puis web et worker à l'état healthy.
  9. Contrôler. Vérifiez les points de la section suivante.
  10. Activer le déploiement automatique. Activez Auto Deploy. Chaque mise à jour de la branche configurée déclenche le déploiement de son dernier commit.
  11. Créer le premier administrateur. Suivez Premier administrateur et récupération.
  12. Planifier les sauvegardes. Voir Sauvegarde et restauration.

Contrôles après le premier déploiement#

ContrôleRésultat attendu
https://maintenance.maintain.example/healthz200, corps {"ok":true}
https://maintenance.maintain.example/readyz200 avec "unavailable": [], une fois l'identité et la messagerie configurées
Ligne release_completedCommit attendu et runtimePrivileges: "verified"
Label de l'image webCommit de la branche déployée
PostgreSQL et RedisAucun port publié, aucun domaine

Pour lire le commit de l'image sur le serveur :

bash
docker inspect --format '{{index .Config.Labels "org.opencontainers.image.revision"}}' <conteneur-web>

Le détail des sondes est dans Santé, métriques et alertes.

Activer des profils optionnels#

Les profils scanner et benchmark s'activent avec la variable COMPOSE_PROFILES, par exemple scanner ou scanner,benchmark. Leurs prérequis sont dans GitHub App et interrupteurs. Vérifiez au premier essai que Coolify démarre bien les services du profil.

Déployer le site de documentation#

Le site de documentation que vous lisez est une ressource Coolify séparée de l'instance. Il n'a ni base, ni secret, ni accès à l'application : c'est un site statique.

Principe retenu :

  • le site est construit depuis le dossier apps/docs/ du dépôt, sans dépendance externe ;
  • l'image produite est un serveur nginx qui sert les pages générées ;
  • la ressource reçoit son propre domaine, par exemple https://docs.maintain.example.

Pas à pas, dans Coolify :

  1. New Resource, même dépôt source, build pack Dockerfile.
  2. Désignez le Dockerfile de apps/docs/.
  3. Associez le domaine du site de documentation.
  4. Déployez, puis ouvrez la page d'accueil.

Le site sert aussi en HTTP, à des adresses stables, les ressources destinées aux outils et aux agents IA : /openapi.json, /openapi.yaml, /llms.txt, /llms-full.txt et la source .md de chaque page. Après le déploiement, vérifiez que ces adresses répondent. Leur liste et leur usage sont décrits dans Ressources pour agents IA. Le détail de construction et de service HTTP (types de contenu, accès en lecture depuis d'autres origines) est dans le fichier README.md de apps/docs/.

Erreurs courantes#

SymptômeCause probableQue faire
release_failedMigration ou vérification des droits en échec.Lisez la ligne d'erreur. Web et worker ne démarrent pas : corrigez puis redéployez.
Message « … requis » au démarrageVariable obligatoire absente.Ajoutez la variable nommée.
« REDIS_PASSWORD trop court »Mot de passe Redis de moins de 24 caractères.Générez un mot de passe plus long.
/readyz en 503Capacité indisponible : base, identité ou file.Lisez le champ unavailable, voir Santé, métriques et alertes.
Commit unknownInclude Source Commit in Build désactivé.Activez l'option et redéployez.

Pour continuer#

Créez le premier compte avec Premier administrateur et récupération.