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#
- 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_PASSWORDetREDIS_PASSWORD. Rangez-les d'abord dans le coffre : ils sont indispensables à une restauration. - 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 (
mainpar défaut), build pack Docker Compose. - Désigner le fichier Compose. Base Directory :
/. Docker Compose Location :/compose.mvp.yaml. N'ajoutez jamais la surcouche localeinfra/compose/mvp.local.yaml. - Transmettre le commit. Activez Include Source Commit in Build. Sans cette option, l'image affiche le commit
unknown. - 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_URLest l'origine HTTPS publique, sans chemin. - Associer le domaine. Associez uniquement le service
webàhttps://maintenance.maintain.example:3333. Le suffixe:3333désigne le port interne, pas un port public. Aucun autre service ne reçoit de domaine. - Vérifier le stockage. Dans Storages, vérifiez les trois volumes nommés
postgres-data,redis-dataetplatform-storage. Ne les remplacez pas par des dossiers de l'hôte sans vérifier l'UID propriétaire. - Déployer. Cliquez sur Deploy. Dans les journaux, suivez : la construction,
Rôles MVP initialisés(premier démarrage seulement),release_completedavec le bon commit, puiswebetworkerà l'état healthy. - Contrôler. Vérifiez les points de la section suivante.
- 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.
- Créer le premier administrateur. Suivez Premier administrateur et récupération.
- Planifier les sauvegardes. Voir Sauvegarde et restauration.
Contrôles après le premier déploiement#
| Contrôle | Résultat attendu |
|---|---|
https://maintenance.maintain.example/healthz | 200, corps {"ok":true} |
https://maintenance.maintain.example/readyz | 200 avec "unavailable": [], une fois l'identité et la messagerie configurées |
Ligne release_completed | Commit attendu et runtimePrivileges: "verified" |
Label de l'image web | Commit de la branche déployée |
| PostgreSQL et Redis | Aucun port publié, aucun domaine |
Pour lire le commit de l'image sur le serveur :
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 :
- New Resource, même dépôt source, build pack Dockerfile.
- Désignez le Dockerfile de
apps/docs/. - Associez le domaine du site de documentation.
- 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ôme | Cause probable | Que faire |
|---|---|---|
release_failed | Migration 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émarrage | Variable 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 503 | Capacité indisponible : base, identité ou file. | Lisez le champ unavailable, voir Santé, métriques et alertes. |
Commit unknown | Include 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.