---
title: Déployer sur Coolify
description: Créer la ressource Coolify de l'instance pas à pas, du dépôt aux contrôles après le premier déploiement, et publier le site de documentation.
---

# 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](02-variables-d-environnement.md) 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](04-premier-administrateur-et-recuperation.md).
12. **Planifier les sauvegardes.** Voir [Sauvegarde et restauration](08-sauvegarde-et-restauration.md).

> [!NOTE]
> Le service `release` reste à l'état *Exited (0)* après chaque déploiement : c'est attendu. Il s'exécute une fois par image déployée, puis s'arrête.

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

```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](07-sante-metriques-et-alertes.md).

## 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](06-github-app-et-fonctionnalites.md). Vérifiez au premier essai que Coolify démarre bien les services du profil.

> [!TIP]
> **Essai local.** Pour essayer l'instance sur un poste, copiez `infra/compose/mvp.env.example` vers un fichier privé, renseignez-le, puis lancez `docker compose --env-file <fichier-env> -f compose.mvp.yaml -f infra/compose/mvp.local.yaml up -d --wait`. La surcouche publie le web sur `127.0.0.1` seulement. Elle ne sert jamais sur Coolify.

## 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](../07-integration-api/07-agent-ia.md). 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](07-sante-metriques-et-alertes.md). |
| 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](04-premier-administrateur-et-recuperation.md).
