Installer Coolify et déployer une première application
Installez Coolify sur Debian ou Ubuntu sans exposer son tableau de bord, sécurisez l'instance, déployez une application en HTTPS, puis gérez les mises à jour et les sauvegardes.
Sur cette page
Vos valeurs
Renseignez-les une fois, les commandes du guide se mettent à jour.
Coolify est une plateforme auto-hébergée qui déploie vos applications, bases de données et services sur vos propres serveurs. Elle s'appuie sur Docker et sur un reverse proxy qui gère les domaines et les certificats HTTPS.
À la fin de ce guide, le tableau de bord répond sur https://coolify.votre-domaine.com, ses ports directs ne sont pas exposés sur Internet, le compte administrateur est protégé et une première application fonctionne sur https://app.votre-domaine.com.
Commander un serveur
Ce guide s'applique aux serveurs que vous administrez vous-même :
Prérequis
- Un serveur dédié à Coolify de préférence, sous Debian 12 ou 13, ou Ubuntu 22.04 ou 24.04
- Au minimum 2 cœurs, 2 Go de RAM et 10 Go d'espace libre, à augmenter selon vos applications et vos compilations
- Un accès SSH avec
rootou un utilisateur disposant desudo - Docker Engine 24 ou plus récent, installé avec le guide Installer Docker Engine et Docker Compose. À défaut, l'installateur de Coolify tente de l'installer lui-même, mais il refuse la version snap
- Un nom de domaine dont vous gérez la zone DNS
- Aucun service qui occupe les ports 80 et 443, comme Nginx, Apache ou Caddy
Ce guide utilise la version 4.7.5, la version stable au moment de la rédaction. Contrôlez la dernière version dans le fichier des versions de Coolify.
Ports utilisés
| Port | Rôle | Exposition dans ce guide |
|---|---|---|
| 22/tcp | SSH, y compris la connexion de Coolify au serveur | Ouvert |
| 80/tcp | HTTP et validation des certificats | Public, via le proxy |
| 443/tcp | HTTPS | Public, via le proxy |
| 443/udp | HTTP/3 | Public, via le proxy |
| 8000/tcp | Accès direct au tableau de bord | 127.0.0.1 uniquement |
| 6001/tcp | Mises à jour en temps réel | 127.0.0.1 uniquement |
| 6002/tcp | Terminal web | 127.0.0.1 uniquement |
| 8080/tcp | Port publié par la configuration Traefik par défaut | Retiré à l'étape 7 |
Si vous utilisez UFW, gardez SSH ouvert avec sudo ufw allow 22/tcp, sans règle limit : elle peut couper les connexions répétées de Coolify.
Étape 1 : préparer le DNS
Créez deux enregistrements A vers VOTRE_IP_SERVEUR :
| Nom | Usage |
|---|---|
coolify.votre-domaine.com |
Tableau de bord |
app.votre-domaine.com |
Première application |
Si votre domaine est géré chez HostMyServers, suivez le guide Créer un enregistrement A. Vérifiez ensuite :
dig +short A coolify.votre-domaine.com
dig +short A app.votre-domaine.com
dig +short AAAA coolify.votre-domaine.comLes deux premières commandes doivent renvoyer l'adresse du serveur. Si la dernière renvoie une adresse IPv6, elle doit aussi mener à ce serveur, sinon la création du certificat peut échouer.
Étape 2 : autoriser la connexion SSH de Coolify
Coolify se connecte au serveur en SSH avec le compte root et une clé dédiée. Contrôlez le réglage actif :
sudo sshd -T | grep -i '^permitrootlogin'Les valeurs prohibit-password, without-password et yes conviennent. Si vous obtenez no, autorisez root uniquement par clé :
echo 'PermitRootLogin prohibit-password' | sudo tee /etc/ssh/sshd_config.d/00-coolify.conf
sudo sshd -t
sudo systemctl reload sshGardez votre session ouverte et testez une nouvelle connexion avant de la fermer.
Si vous avez suivi Sécuriser son serveur, SSH écoute sur le port 2222. Remplacez 22 par 2222 dans les règles UFW de ce guide, puis indiquez ce port dans Servers > localhost > General une fois Coolify installé.
Étape 3 : réserver les ports à l'adresse locale
Sans précaution, le tableau de bord serait publié en HTTP sur le port 8000, et le premier visiteur pourrait y créer le compte administrateur. Créez donc le fichier de personnalisation avant l'installation. Coolify le conserve lors des mises à jour.
Passez en root :
sudo -i
mkdir -p /data/coolify/source
nano /data/coolify/source/docker-compose.custom.ymlCollez ce contenu :
services:
coolify:
ports: !override
- "127.0.0.1:${APP_PORT:-8000}:8080"
- "127.0.0.1:${SOKETI_PORT:-6001}:6001"
- "127.0.0.1:6002:6002"Étape 4 : installer Coolify
Toujours en root, téléchargez le script officiel, parcourez-le, puis lancez-le avec la version choisie :
curl -fsSL https://cdn.coollabs.io/coolify/install.sh -o /root/coolify-install.sh
less /root/coolify-install.sh
bash /root/coolify-install.sh 4.7.5Le script installe les paquets nécessaires, adapte la configuration de Docker, crée /data/coolify, génère la clé SSH de Coolify et démarre ses conteneurs. Il peut redémarrer Docker : c'est une raison de plus de partir d'un serveur neuf.
À la fin, il affiche une adresse en http://...:8000. Elle ne répondra pas depuis Internet, et c'est le résultat voulu. Vérifiez les ports :
docker ps --format 'table {{.Names}}\t{{.Status}}\t{{.Ports}}'La ligne coolify doit indiquer healthy et des ports commençant par 127.0.0.1:.
Étape 5 : ouvrir le tunnel SSH
Dans un terminal sur votre poste, ouvrez un tunnel vers les trois ports :
ssh -N -L 8000:127.0.0.1:8000 -L 6001:127.0.0.1:6001 -L 6002:127.0.0.1:6002 VOTRE_USER@VOTRE_IP_SERVEURLa commande reste active sans rien afficher. Laissez ce terminal ouvert pendant la configuration. Le trafic entre votre poste et le serveur est chiffré par SSH.
Étape 6 : créer le compte administrateur
Ouvrez http://localhost:8000 et créez immédiatement le compte, avec un mot de passe long et unique. Coolify n'accepte le premier compte que pendant 10 minutes après son démarrage.
Suivez ensuite l'assistant et choisissez d'utiliser ce serveur (localhost). Dans Servers > localhost, la connexion doit être validée. Si ce n'est pas le cas, consultez la section de dépannage.
Copiez tout de suite la clé de chiffrement de l'instance dans un gestionnaire de mots de passe :
grep '^APP_KEY=' /data/coolify/source/.envÉtape 7 : démarrer le proxy
Ouvrez Servers > localhost > Proxy. Traefik est le proxy par défaut.
Dans Configuration, retirez la ligne suivante, inutile pour ce montage, puis enregistrez :
- '8080:8080'Cliquez ensuite sur Start Proxy, ou redémarrez le proxy s'il tourne déjà. Sur le serveur, vérifiez qu'il écoute :
docker ps --filter name=coolify-proxy --format '{{.Names}} {{.Status}} {{.Ports}}'Les ports 80 et 443 doivent apparaître sur 0.0.0.0, et 8080 ne doit plus figurer dans la liste.
Étape 8 : publier le tableau de bord en HTTPS
Ouvrez Settings > General. Dans URL, saisissez :
https://coolify.votre-domaine.comLaissez Redirect HTTP to HTTPS activé, puis cliquez sur Save changes. Après quelques instants, ouvrez https://coolify.votre-domaine.com et contrôlez le certificat :
curl -I https://coolify.votre-domaine.comVérifiez que les données se mettent à jour en direct et, si vous l'utilisez, que le terminal web fonctionne. Vous pouvez ensuite fermer le tunnel avec Ctrl+C. Il reste votre accès de secours si le domaine ne répond plus.
Étape 9 : sécuriser l'instance
| Réglage | Emplacement | Valeur conseillée |
|---|---|---|
| Inscriptions | Settings > Advanced > Registration | Registration disabled |
| Double authentification | Profile > Two-factor Authentication > Configure 2FA | Activée, codes de secours conservés à part |
| API | Settings > Advanced > API access | Disabled si vous ne l'utilisez pas |
| Serveur MCP | Settings > Advanced | Désactivé, sauf besoin précis |
| Adresses autorisées | Settings > Advanced > Allowed IPs | Vos adresses, si vous activez l'API |
| Équipe | Team | Rôle minimal pour chaque membre |
Depuis une autre machine, sans tunnel, contrôlez ce qui est joignable :
nmap -Pn -p 22,80,443,6001,6002,8000,8080 VOTRE_IP_SERVEURSeuls 22, 80 et 443 doivent apparaître comme open.
Étape 10 : déployer une première application
Cet exemple utilise une image prête à l'emploi : il ne demande ni dépôt Git, ni compilation.
- Ouvrez Projects, créez un projet nommé
demo, puis ouvrez-le. - Cliquez sur + New (ou Create New Resource), puis choisissez Docker Image.
- Saisissez l'image
nginx:1.30-alpineet continuez. - Dans Ports Exposes, indiquez
80. - Dans Domains, cliquez sur Add domain, choisissez
httpset saisissezapp.votre-domaine.com. - Cliquez sur Deploy et suivez les journaux du déploiement.
Vérifiez ensuite le résultat :
curl -I https://app.votre-domaine.comLa réponse doit être un code 200, et le navigateur doit afficher la page d'accueil de Nginx avec un certificat valide.
Déployer depuis un dépôt Git public
Dans le projet, cliquez sur + New, choisissez Public Repository, collez l'adresse HTTPS du dépôt, puis cliquez sur Check repository. Choisissez ensuite le Build pack, le port de l'application et son domaine, puis lancez Deploy.
La compilation s'exécute par défaut sur ce serveur et peut consommer beaucoup de CPU et de mémoire.
Mettre à jour Coolify
Une mise à jour de Coolify ne modifie ni vos applications, ni le système, ni Docker. Avant de la lancer, lisez les notes de version, attendez la fin des déploiements en cours et faites une sauvegarde.
Depuis le tableau de bord
Ouvrez Settings > Updates, gardez le canal Stable, puis cliquez sur Upgrade now lorsqu'une version est disponible. Le réglage Automatic updates détermine si Coolify installe seul les nouvelles versions. Désactivez-le si vous préférez garder la main sur le calendrier.
Depuis le terminal
Exécutez en root, en indiquant la version voulue sans v :
curl -fsSL https://cdn.coollabs.io/coolify/upgrade.sh | bash -s 4.7.5N'utilisez pas install.sh pour une mise à jour courante : il réinitialise les propriétaires et les droits sous /data/coolify. Le fichier docker-compose.custom.yml reste pris en compte. Contrôlez ensuite la version affichée dans le tableau de bord et, si besoin, les journaux /data/coolify/source/upgrade-*.log.
Sauvegarder et restaurer
Conservez ces éléments hors du serveur :
| Élément | Emplacement | Pourquoi |
|---|---|---|
| Base de données de Coolify | Sauvegarde .dmp |
Projets, réglages et secrets chiffrés |
Clé APP_KEY et fichier .env |
/data/coolify/source/.env |
Sans cette clé, les secrets restaurés sont illisibles |
| Clés SSH | /data/coolify/ssh/keys/ |
Connexion aux serveurs gérés |
| Personnalisation des ports | /data/coolify/source/docker-compose.custom.yml |
Conserve la protection des ports |
| Données des applications | Volumes et bases de données | Non incluses dans la sauvegarde de Coolify |
Depuis le tableau de bord
Ouvrez Settings > Backup, cliquez sur Configure backup, puis sur Back up now. Contrôlez le résultat dans Executions et utilisez Download pour récupérer une copie. Vous pouvez aussi ajouter un stockage S3. Laissez Backup before update activé pour obtenir une sauvegarde avant chaque mise à jour lancée depuis l'interface.
Depuis le terminal
En root :
mkdir -p /data/backups
docker exec coolify-db pg_dump --format=custom --no-acl --no-owner --username=coolify coolify > "/data/backups/coolify-db-$(date +%F).dmp"
test -s "/data/backups/coolify-db-$(date +%F).dmp" && echo OK
tar czf "/data/backups/coolify-files-$(date +%F).tar.gz" -C /data/coolify source/.env source/docker-compose.custom.yml ssh/keys
chmod 600 /data/backups/*Ces fichiers contiennent des secrets : copiez-les dans un emplacement chiffré.
Restaurer sur le même serveur
Remplacez AAAA-MM-JJ par la date de la sauvegarde. La base actuelle sera remplacée. Vérifiez d'abord que APP_KEY dans /data/coolify/source/.env correspond à la clé enregistrée, puis exécutez en root :
docker stop coolify coolify-redis
docker exec -i coolify-db pg_restore --clean --if-exists --exit-on-error --no-acl --no-owner --username=coolify --dbname=coolify < /data/backups/coolify-db-AAAA-MM-JJ.dmp
curl -fsSL https://cdn.coollabs.io/coolify/install.sh -o /root/coolify-install.sh
bash /root/coolify-install.sh 4.7.5Indiquez la version installée lors de la sauvegarde. Sur un nouveau serveur, suivez la procédure officielle de restauration, qui reprend aussi les clés SSH.
En cas de problème
Setup window closed
Le délai de 10 minutes est dépassé. Redémarrez Coolify, puis rechargez la page :
docker restart coolifyL'adresse en :8000 ne répond pas
C'est normal depuis Internet. Passez par le tunnel de l'étape 5 et ouvrez http://localhost:8000. Si le tunnel échoue, contrôlez l'état des conteneurs avec docker ps.
Les données ne se mettent pas à jour dans le tableau de bord
La connexion temps réel n'aboutit pas. Avec le tunnel, vérifiez que les ports 6001 et 6002 y figurent bien. Avec le domaine, vérifiez que le proxy tourne et qu'aucun autre proxy ne bloque les WebSockets.
Permission denied (publickey) lors de la validation du serveur
La clé de Coolify manque pour root, ou root ne peut pas se connecter. Vérifiez l'étape 2. L'installateur ne conserve pas la clé publique sur le disque : recalculez-la en root à partir de la clé privée, puis ajoutez-la :
ssh-keygen -y -f /data/coolify/ssh/keys/id.root@host.docker.internal | sed 's/$/ coolify/' >> /root/.ssh/authorized_keysSi ce fichier n'existe pas, listez le dossier avec ls /data/coolify/ssh/keys/ et utilisez la clé qui s'y trouve.
Le serveur localhost est injoignable ou instable
Coolify joint le serveur depuis son réseau Docker. Une règle ufw limit 22/tcp ou une restriction de SSH à votre seule adresse peut le bloquer. Remplacez la limite par sudo ufw allow 22/tcp, ou autorisez le réseau de Coolify :
docker network inspect coolify --format '{{(index .IPAM.Config 0).Subnet}}'
sudo ufw allow from SOUS_RESEAU to any port 22 proto tcpRemplacez SOUS_RESEAU par la valeur affichée.
Le proxy ne démarre pas : address already in use
Un autre service utilise le port 80 ou 443 :
sudo ss -ltnp | grep -E ':(80|443) 'Arrêtez et désactivez ce service, puis relancez le proxy.
Le proxy n'est joignable qu'en local
Vérifiez que /etc/docker/daemon.json ne contient pas "ip": "127.0.0.1" ni host_binding_ipv4. Retirez ces clés, redémarrez Docker, puis le proxy.
Le certificat n'est pas valide (TRAEFIK DEFAULT CERT)
Let's Encrypt n'a pas pu valider le domaine. Contrôlez les enregistrements A et AAAA, puis l'accès au port 80 depuis l'extérieur. Si le domaine passe par le proxy de Cloudflare, désactivez ce dernier le temps de la validation ou utilisez un challenge DNS. Si le port reste injoignable alors que tout est correct sur le serveur, contactez le support depuis votre espace client.
Erreur 502 Bad Gateway
Le proxy joint le conteneur, mais pas l'application. Vérifiez que Ports Exposes correspond au port réel de l'application, et que celle-ci écoute sur 0.0.0.0 et non sur 127.0.0.1.
no available server
Traefik ne trouve aucun conteneur sain pour ce domaine. Contrôlez l'état du déploiement, le contrôle de santé de l'application et l'orthographe du domaine dans Domains.
Le port 8000 reste accessible depuis Internet
Le fichier de personnalisation n'est pas appliqué. Vérifiez son emplacement et sa syntaxe, puis appliquez-le en root :
cd /data/coolify/source
docker compose --env-file .env -f docker-compose.yml -f docker-compose.prod.yml -f docker-compose.custom.yml config --quiet
docker compose --env-file .env -f docker-compose.yml -f docker-compose.prod.yml -f docker-compose.custom.yml up -d --remove-orphansLe serveur ralentit fortement pendant un déploiement
La compilation consomme les ressources du serveur. Déployez une image déjà construite, compilez ailleurs (par exemple dans votre CI) ou augmentez les ressources.
Invalid MAC après une restauration
La clé APP_KEY ne correspond pas à celle de la sauvegarde. Remettez la clé enregistrée dans /data/coolify/source/.env, puis relancez l'installateur avec la même version.