Déployer une application Next.js avec Coolify v4 : guide complet du self-hosting

Introduction

Vercel, Netlify, Railway — ces plateformes cloud simplifient le déploiement, mais à quel prix ? Factures imprévisibles, vendor lock-in, et dépendance totale à des services tiers. En 2026, de plus en plus de développeurs choisissent le self-hosting pour garder le contrôle total sur leur infrastructure.

Coolify v4 est une plateforme de déploiement open source (PaaS) que vous installez sur votre propre serveur. Elle offre les mêmes fonctionnalités que Vercel — déploiement automatique depuis Git, certificats SSL, preview environments — mais sur votre infrastructure, sans frais par projet.

Dans ce tutoriel, vous allez apprendre à :

• Installer et configurer Coolify v4 sur un VPS
• Déployer une application Next.js avec Docker
• Configurer le déploiement automatique via GitHub/GitLab
• Mettre en place des certificats SSL avec Let's Encrypt
• Configurer le monitoring et les alertes
• Gérer plusieurs environnements (staging/production)

Prérequis

Avant de commencer, assurez-vous d'avoir :

• Un VPS avec au minimum 2 Go de RAM et 2 vCPUs (DigitalOcean, Hetzner, OVH, etc.)
• Ubuntu 22.04 ou 24.04 installé sur le VPS
• Un nom de domaine pointant vers votre serveur
• Une application Next.js prête à déployer
• Des connaissances de base en Docker et ligne de commande Linux
• Un compte GitHub ou GitLab avec votre code source

Ce que vous allez construire

À la fin de ce tutoriel, vous aurez une infrastructure complète de déploiement :

• Un serveur Coolify gérant vos applications
• Une application Next.js en production avec SSL
• Un pipeline CI/CD automatique déclenché par chaque push
• Un système de monitoring avec alertes
• Des environnements de preview pour chaque pull request

Étape 1 : Préparer le serveur

1.1 Se connecter au VPS

Connectez-vous à votre serveur via SSH :

ssh root@votre-ip-serveur

1.2 Mettre à jour le système

apt update && apt upgrade -y

1.3 Configurer le pare-feu

Coolify nécessite certains ports ouverts. Configurez UFW :

ufw allow 22/tcp    # SSH
ufw allow 80/tcp    # HTTP
ufw allow 443/tcp   # HTTPS
ufw allow 8000/tcp  # Coolify UI
ufw allow 6001/tcp  # Coolify Websocket
ufw allow 6002/tcp  # Coolify API
ufw enable

1.4 Configurer le DNS

Avant d'installer Coolify, pointez votre domaine vers le serveur. Créez ces enregistrements DNS :

L'enregistrement wildcard (*) permet à Coolify de créer automatiquement des sous-domaines pour chaque application.

Étape 2 : Installer Coolify v4

2.1 Lancer le script d'installation

Coolify fournit un script d'installation automatique :

curl -fsSL https://cdn.coollabs.io/coolify/install.sh | bash

Ce script installe automatiquement :

• Docker et Docker Compose
• Coolify et ses dépendances
• Un reverse proxy Traefik
• Une base de données PostgreSQL pour Coolify

L'installation prend généralement 2 à 5 minutes.

2.2 Accéder à l'interface

Une fois l'installation terminée, ouvrez votre navigateur et accédez à :

http://votre-ip-serveur:8000

Vous verrez l'écran de création du premier compte administrateur.

2.3 Créer le compte administrateur

Remplissez le formulaire avec :

• Email : votre adresse email
• Mot de passe : un mot de passe fort (minimum 12 caractères)

Coolify vous redirige vers le tableau de bord principal.

2.4 Configurer le domaine de Coolify

Allez dans Settings et configurez :

Instance FQDN: https://coolify.votredomaine.com

Cela permet d'accéder à Coolify via votre domaine au lieu de l'IP avec le port 8000.

Étape 3 : Préparer l'application Next.js

3.1 Structure du projet

Voici la structure minimale d'un projet Next.js prêt pour Coolify :

mon-app-nextjs/
├── src/
│   └── app/
│       ├── layout.tsx
│       └── page.tsx
├── public/
├── next.config.js
├── package.json
├── Dockerfile
└── .dockerignore

3.2 Créer le Dockerfile

Créez un Dockerfile à la racine de votre projet :

FROM node:20-alpine AS base
 
# Installer les dépendances uniquement quand nécessaire
FROM base AS deps
RUN apk add --no-cache libc6-compat
WORKDIR /app
 
COPY package.json package-lock.json* ./
RUN npm ci --only=production
 
# Builder
FROM base AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
 
ENV NEXT_TELEMETRY_DISABLED=1
ENV NODE_ENV=production
 
RUN npm run build
 
# Runner de production
FROM base AS runner
WORKDIR /app
 
ENV NODE_ENV=production
ENV NEXT_TELEMETRY_DISABLED=1
 
RUN addgroup --system --gid 1001 nodejs
RUN adduser --system --uid 1001 nextjs
 
COPY --from=builder /app/public ./public
COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static
 
USER nextjs
 
EXPOSE 3000
 
ENV PORT=3000
ENV HOSTNAME="0.0.0.0"
 
CMD ["node", "server.js"]

3.3 Configurer Next.js pour le standalone

Modifiez votre next.config.js pour activer le mode standalone :

/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'standalone',
}
 
module.exports = nextConfig

Le mode standalone produit un build optimisé qui inclut uniquement les fichiers nécessaires, réduisant considérablement la taille de l'image Docker.

3.4 Créer le .dockerignore

node_modules
.next
.git
.gitignore
README.md
.env*.local

3.5 Tester localement

Vérifiez que votre image Docker fonctionne :

docker build -t mon-app-nextjs .
docker run -p 3000:3000 mon-app-nextjs

Ouvrez http://localhost:3000 pour vérifier que tout fonctionne.

Étape 4 : Connecter le dépôt Git

4.1 Ajouter une source Git

Dans Coolify, allez dans Sources puis cliquez sur Add :

Pour GitHub :

1. Sélectionnez GitHub App
2. Cliquez sur Register a GitHub App
3. Donnez un nom à l'app (ex: coolify-mon-serveur)
4. Coolify vous redirige vers GitHub pour autoriser l'application
5. Sélectionnez les repositories auxquels Coolify aura accès

Pour GitLab :

1. Sélectionnez GitLab
2. Entrez l'URL de votre instance GitLab
3. Créez un token d'accès avec les scopes api et read_repository
4. Collez le token dans Coolify

4.2 Vérifier la connexion

Une fois configuré, vous devriez voir vos repositories listés quand vous créez un nouveau projet.

Étape 5 : Déployer l'application

5.1 Créer un projet

Dans Coolify :

1. Cliquez sur Projects dans la barre latérale
2. Cliquez sur Add
3. Nommez votre projet (ex: mon-site-web)
4. Sélectionnez l'environnement Production

5.2 Ajouter une ressource

1. Dans votre projet, cliquez sur New Resource
2. Sélectionnez Public Repository ou Private Repository (GitHub/GitLab)
3. Choisissez votre repository
4. Sélectionnez la branche (main ou master)

5.3 Configurer le déploiement

Coolify détecte automatiquement le type de projet. Pour Next.js avec Docker :

Build Pack : Dockerfile

Configuration du réseau :

Port exposé: 3000
Domaine: https://monapp.votredomaine.com

5.4 Variables d'environnement

Ajoutez vos variables d'environnement dans l'onglet Environment Variables :

DATABASE_URL=postgresql://user:password@db:5432/mydb
NEXT_PUBLIC_API_URL=https://api.votredomaine.com
SECRET_KEY=votre-cle-secrete

Coolify chiffre automatiquement les variables sensibles. Vous pouvez aussi marquer certaines variables comme Build time only ou Preview only.

5.5 Lancer le déploiement

Cliquez sur Deploy. Coolify va :

1. Cloner votre repository
2. Construire l'image Docker
3. Démarrer le conteneur
4. Configurer le reverse proxy Traefik
5. Générer le certificat SSL via Let's Encrypt

Suivez la progression dans les logs en temps réel.

Étape 6 : Configurer le SSL automatique

6.1 Certificats Let's Encrypt

Coolify gère automatiquement les certificats SSL via Let's Encrypt. Assurez-vous que :

• Votre domaine pointe correctement vers le serveur
• Le port 80 est ouvert (nécessaire pour le challenge HTTP-01)
• Le FQDN est correctement configuré dans les paramètres de l'application

6.2 Vérifier le certificat

Après le déploiement, visitez votre site en HTTPS :

https://monapp.votredomaine.com

Le cadenas devrait apparaître dans la barre d'adresse. Le certificat se renouvelle automatiquement avant expiration.

6.3 Forcer HTTPS

Dans les paramètres de l'application, activez Force HTTPS pour rediriger automatiquement tout le trafic HTTP vers HTTPS.

Étape 7 : Déploiement automatique (CI/CD)

7.1 Webhooks automatiques

Si vous avez connecté Coolify via une GitHub App, les webhooks sont configurés automatiquement. Chaque push sur la branche configurée déclenche un nouveau déploiement.

7.2 Configuration des branches

Vous pouvez configurer différents comportements par branche :

main → Production (monapp.votredomaine.com)
develop → Staging (staging.monapp.votredomaine.com)

7.3 Preview Deployments

Coolify supporte les preview deployments pour les pull requests :

1. Dans les paramètres de l'application, activez Preview Deployments
2. Chaque PR reçoit un sous-domaine unique : pr-42.monapp.votredomaine.com
3. Le preview est automatiquement supprimé quand la PR est fermée

Cela permet à votre équipe de tester chaque changement avant le merge.

7.4 Stratégie de rollback

En cas de problème, Coolify conserve les versions précédentes. Pour revenir en arrière :

1. Allez dans l'onglet Deployments
2. Trouvez le déploiement précédent qui fonctionnait
3. Cliquez sur Redeploy

Étape 8 : Ajouter une base de données

8.1 Créer une base PostgreSQL

Coolify peut gérer vos bases de données en un clic :

1. Dans votre projet, cliquez sur New Resource
2. Sélectionnez Database
3. Choisissez PostgreSQL
4. Configurez :

Version: 16
Nom de la base: monapp_db
Utilisateur: monapp_user
Mot de passe: (généré automatiquement)
Port public: (désactivé par défaut - recommandé)

5. Cliquez sur Start

8.2 Connecter l'application à la base

Coolify crée un réseau Docker interne. Utilisez le nom du conteneur comme hôte :

DATABASE_URL=postgresql://monapp_user:motdepasse@nom-conteneur-pg:5432/monapp_db

Ajoutez cette variable dans les Environment Variables de votre application Next.js.

8.3 Sauvegardes automatiques

Configurez les backups dans l'onglet Backups de votre base de données :

• Fréquence : quotidienne (recommandé)
• Rétention : 7 jours minimum
• Destination : S3, local, ou serveur distant

# Coolify peut aussi envoyer les backups vers S3
# Configurez dans Settings > S3 Storage

Étape 9 : Monitoring et alertes

9.1 Métriques intégrées

Coolify affiche les métriques de base directement dans le tableau de bord :

• CPU : utilisation en pourcentage
• RAM : mémoire utilisée / totale
• Réseau : trafic entrant / sortant
• Disque : espace utilisé

9.2 Health Checks

Configurez un health check pour votre application :

Health Check Path: /api/health
Health Check Interval: 30 (secondes)
Health Check Timeout: 5 (secondes)
Health Check Retries: 3

Créez l'endpoint correspondant dans votre application Next.js :

// app/api/health/route.ts
import { NextResponse } from 'next/server'
 
export async function GET() {
  try {
    // Vérifier la connexion à la base de données
    // await db.query('SELECT 1')
 
    return NextResponse.json({
      status: 'healthy',
      timestamp: new Date().toISOString(),
      uptime: process.uptime(),
    })
  } catch (error) {
    return NextResponse.json(
      { status: 'unhealthy', error: 'Database connection failed' },
      { status: 503 }
    )
  }
}

9.3 Notifications

Configurez les alertes dans Settings > Notifications :

• Email : alertes par email (SMTP requis)
• Discord : webhook vers un canal Discord
• Telegram : notifications via bot Telegram
• Slack : intégration Slack

Exemple de configuration Telegram :

1. Créez un bot via @BotFather sur Telegram
2. Récupérez le token du bot
3. Obtenez votre chat ID
4. Ajoutez ces informations dans Coolify

Vous recevrez des notifications pour :

• Déploiements réussis ou échoués
• Health checks en échec
• Certificats SSL sur le point d'expirer
• Utilisation élevée des ressources

Étape 10 : Optimisations avancées

10.1 Cache Docker multi-étapes

Optimisez vos builds en exploitant le cache Docker. Coolify conserve les couches Docker entre les builds, ce qui accélère les déploiements suivants.

Astuce : placez les instructions qui changent rarement (comme npm ci) avant celles qui changent souvent (comme COPY . .) dans votre Dockerfile.

10.2 Ressources et limites

Configurez les limites de ressources pour chaque conteneur :

CPU Limit: 2 (cores)
Memory Limit: 1024 (MB)
Memory Reservation: 512 (MB)

Cela empêche un conteneur défaillant de consommer toutes les ressources du serveur.

10.3 Mise à l'échelle horizontale

Pour les applications qui nécessitent plus de capacité, Coolify supporte :

Plusieurs instances :

Nombre de réplicas: 3

Traefik distribue automatiquement le trafic entre les instances (load balancing).

Serveurs distants :

1. Allez dans Servers et ajoutez un nouveau serveur
2. Coolify se connecte via SSH
3. Vous pouvez déployer des applications sur plusieurs serveurs

10.4 Persistance des données

Pour les fichiers uploadés ou les données persistantes, configurez des volumes Docker :

Source: /data/uploads
Destination: /app/public/uploads

Ces données survivent aux redéploiements.

Étape 11 : Sécurité

11.1 Accès SSH par clé

Désactivez l'authentification par mot de passe SSH :

# /etc/ssh/sshd_config
PasswordAuthentication no
PubkeyAuthentication yes

systemctl restart sshd

11.2 Mises à jour automatiques

Configurez les mises à jour de sécurité automatiques :

apt install unattended-upgrades -y
dpkg-reconfigure -plow unattended-upgrades

11.3 Mettre à jour Coolify

Coolify se met à jour depuis l'interface :

1. Allez dans Settings
2. Vérifiez la version actuelle
3. Cliquez sur Update si une nouvelle version est disponible

Vous pouvez aussi activer les mises à jour automatiques de Coolify.

11.4 Fail2ban

Protégez votre serveur contre les attaques par force brute :

apt install fail2ban -y
systemctl enable fail2ban
systemctl start fail2ban

Dépannage

Le déploiement échoue au build

Problème : Erreur "Out of memory" pendant npm run build

Solution : Augmentez la mémoire disponible ou ajoutez du swap :

fallocate -l 4G /swapfile
chmod 600 /swapfile
mkswap /swapfile
swapon /swapfile
echo '/swapfile none swap sw 0 0' >> /etc/fstab

Le site affiche une erreur 502

Causes possibles :

• Le conteneur n'a pas fini de démarrer — attendez quelques secondes
• Le port configuré dans Coolify ne correspond pas au port exposé par l'application
• L'application a crashé — vérifiez les logs dans Coolify

Le certificat SSL ne se génère pas

Vérifiez :

• Le DNS pointe bien vers le serveur (dig monapp.votredomaine.com)
• Le port 80 est ouvert
• Il n'y a pas de limite de rate-limiting Let's Encrypt (5 certificats par domaine par semaine)

Les variables d'environnement ne sont pas accessibles

• Les variables NEXT_PUBLIC_* doivent être disponibles au build time
• Marquez-les comme Build Variable dans Coolify
• Redéployez après avoir ajouté de nouvelles variables

Coolify vs. les alternatives

Prochaines étapes

Maintenant que votre infrastructure est en place, voici quelques améliorations possibles :

• Ajouter un CDN : Configurez Cloudflare devant votre serveur pour le cache et la protection DDoS
• Centraliser les logs : Intégrez un stack de logging comme Grafana + Loki
• Automatiser les backups : Configurez des backups S3 avec rétention et chiffrement
• Multi-serveurs : Ajoutez des serveurs dans différentes régions pour la redondance
• Monitoring avancé : Déployez Uptime Kuma via Coolify pour surveiller vos services

Conclusion

Vous avez maintenant une plateforme de déploiement complète, auto-hébergée et gratuite. Coolify v4 offre une expérience comparable à Vercel ou Netlify, mais avec un contrôle total sur vos données et votre infrastructure.

Les principaux avantages de cette approche :

• Coût prévisible : un VPS à prix fixe au lieu de factures variables
• Souveraineté des données : vos données restent sur votre serveur
• Flexibilité : déployez tout type d'application (pas uniquement des frameworks supportés)
• Pas de vendor lock-in : migrez vers un autre serveur quand vous voulez

Le self-hosting demande plus de responsabilité en termes de maintenance et de sécurité, mais les outils comme Coolify réduisent considérablement cette charge. Pour des équipes et des projets qui valorisent l'indépendance et le contrôle, c'est une alternative solide aux plateformes cloud propriétaires.