Next.js est devenu le framework React de référence en 2026, mais le déploiement en production reste un sujet épineux quand on veut éviter Vercel et ses prix en dollars qui explosent à la moindre montée en charge. Coolify permet de déployer Next.js sur votre propre VPS en quelques minutes, avec déploiement continu depuis GitHub, HTTPS automatique, zero-downtime et un coût fixe de quelques euros par mois quel que soit le trafic. Voici le tutoriel complet, testé sur Next.js 14 et 15 en production réelle.
Si vous n’avez pas encore installé Coolify, commencez par notre guide d’installation Coolify. Ce tutoriel suppose que votre instance est déjà fonctionnelle, accessible via HTTPS, et qu’une source GitHub est connectée.
Pourquoi Coolify pour Next.js ?
Vercel est le créateur de Next.js et la plateforme de référence pour le déployer. C’est excellent à petite échelle (plan gratuit généreux) mais devient cher dès que vous montez : 20 $ par utilisateur du plan Pro, surcoûts pour les fonctions edge, pour la bande passante au-delà de 100 Go, pour les builds dépassant les minutes incluses. Pour une PME ouest-africaine avec 50 000 visiteurs par mois, la facture Vercel peut grimper à 200 € par mois facilement.
Coolify sur un VPS Hetzner CX22 à 4 € par mois supporte facilement plusieurs applications Next.js avec leurs bases de données. Le seul « coût » est le temps initial de configuration (1 à 2 heures la première fois) et la maintenance mensuelle (mises à jour OS, audit logs). Pour qui sait déjà se connecter en SSH, c’est imbattable.
Prérequis
- Coolify v4.x installé et accessible en HTTPS
- Une application Next.js 14 ou 15 sur GitHub (ou GitLab, Forgejo, Gitea)
- Un nom de domaine pointant sur le VPS Coolify (record A ou AAAA)
- VPS avec 4 Go RAM minimum (Next.js consomme beaucoup pendant le build, surtout pour les apps avec beaucoup de pages statiques)
- Niveau attendu : intermédiaire (vous savez écrire un .env.local et déployer en local)
- Temps : 15 à 25 minutes pour le premier déploiement, ensuite chaque déploiement suivant est automatique
Étape 1 — Connecter GitHub à Coolify
Dans Coolify, allez dans Sources → New Source → GitHub App. Cliquez « Create new GitHub App », choisissez votre organisation et installez l’app sur les dépôts à déployer. Coolify pré-remplit toutes les permissions nécessaires (read code, read deployments, write webhooks). L’avantage du système GitHub App vs un token personnel : les déploiements se déclenchent automatiquement à chaque push, sans webhook manuel à maintenir, et la connexion ne dépend pas d’un seul utilisateur.
Si votre code est sur Forgejo ou Gitea (auto-hébergés sur le même Coolify, par exemple), la procédure est similaire mais via token personnel d’accès. Pour les dépôts privés via SSH classique, Coolify génère une clef que vous collez dans les Deploy Keys du dépôt.
Étape 2 — Préparer le projet Next.js
Avant de déployer, optimisez votre projet pour la production. Dans next.config.js :
// next.config.js (Next.js 14)
/** @type {import('next').NextConfig} */
const nextConfig = {
output: 'standalone', // build autonome, plus léger
reactStrictMode: true,
images: {
formats: ['image/avif', 'image/webp'],
remotePatterns: [{ protocol: 'https', hostname: '**' }],
},
experimental: {
optimizePackageImports: ['lodash', 'date-fns'],
},
};
module.exports = nextConfig;L’option output: 'standalone' est cruciale : elle produit un build autonome avec uniquement les dépendances nécessaires, ce qui réduit drastiquement la taille du conteneur et accélère les démarrages. Sans elle, Next.js inclut tout node_modules dans le runtime, ce qui peut faire des conteneurs de plusieurs centaines de Mo.
Ajoutez aussi un endpoint de healthcheck simple, par exemple /api/health qui retourne un 200 :
// app/api/health/route.ts
export async function GET() {
return Response.json({ status: 'ok', time: Date.now() });
}Étape 3 — Créer le projet et l’application dans Coolify
Dans Projects, créez un projet (par exemple « production »). Ajoutez un environnement, puis « + New Resource » → Application → Public Repository ou Private Repository selon votre cas. Sélectionnez la branche (typiquement main) et le buildpack Nixpacks. Coolify détecte automatiquement Next.js et propose la configuration suivante :
# Build command (auto-détecté)
npm run build
# Start command (auto-détecté)
npm start
# Port exposé
3000
# Build environment
NODE_ENV=productionCes valeurs par défaut conviennent à 95 % des projets Next.js. Si vous utilisez pnpm ou yarn, Coolify détecte le lockfile et adapte la commande automatiquement.
Étape 4 — Variables d’environnement
Onglet « Environment Variables ». Ajoutez vos secrets : DATABASE_URL, NEXTAUTH_SECRET, NEXT_PUBLIC_API_URL, STRIPE_SECRET_KEY, etc. Coolify chiffre les valeurs au repos et ne les expose jamais dans les logs.
Point critique : pour les variables qui doivent être disponibles pendant le npm run build (notamment toutes les NEXT_PUBLIC_* et certaines variables Prisma), cochez la case « Build variable ». Next.js inline les variables NEXT_PUBLIC au build, donc si elles sont absentes pendant npm run build, elles seront undefined en production — et vous passerez 30 minutes à debugger pourquoi votre app appelle undefined/api/users.
Tip : pour gérer plusieurs environnements (dev, staging, prod) sans dupliquer toutes les variables, créez un environnement Coolify séparé par stage. Chacun a ses propres variables.
Étape 5 — Domaine et HTTPS
Onglet « Domains ». Ajoutez votre domaine (par exemple app.exemple.sn). Vérifiez d’abord que votre DNS pointe bien sur l’IP du VPS Coolify (record A ou AAAA) avec dig app.exemple.sn ou nslookup. La propagation DNS peut prendre quelques minutes à quelques heures selon votre registrar.
Activez « Force HTTPS Redirect » et « Generate SSL ». Coolify lance Traefik avec un challenge HTTP-01 vers Let’s Encrypt — vous obtenez un certificat valide en moins d’une minute. Si vous avez besoin d’un certificat wildcard (*.exemple.sn), il faut activer le challenge DNS-01 avec une clef API chez votre registrar.
Étape 6 — Premier déploiement
Cliquez sur « Deploy ». Coolify clone le dépôt, lance Nixpacks qui détecte Next.js, exécute npm ci && npm run build puis démarre npm start dans un conteneur. Le build prend généralement 3 à 8 minutes selon la taille du projet et la puissance du VPS. Sur un Hetzner CX22 (4 Go RAM, 2 vCPU), un projet Next.js de taille moyenne (50 pages, 30 dépendances) build en environ 5 minutes.
L’onglet « Logs » affiche le processus en direct. Une fois « Application started » affiché, ouvrez votre domaine et vérifiez. Tout push ultérieur sur la branche déclenchera un nouveau déploiement automatique avec rollback possible en un clic.
Étape 7 — Optimiser pour la production
- Standalone output : déjà fait à l’étape 2. Le conteneur final pèse 100-150 Mo au lieu de 500 Mo+.
- Image optimization : Next.js Image fonctionne nativement avec sharp. Sur un VPS avec peu de CPU, considérez de servir les images via un CDN comme Cloudflare Free, qui marche très bien depuis l’Afrique et économise CPU + bande passante.
- Persistent storage : si votre app écrit des fichiers (uploads utilisateurs), ajoutez un volume persistant dans Coolify (onglet Storage). Sinon les fichiers disparaissent à chaque redeploy. Mieux encore, stockez les uploads sur un service S3 type Backblaze B2.
- Healthcheck : configurez le path
/api/healthdans Coolify (onglet General → Health Check). Les redéploiements zero-downtime en dépendent : Coolify attend que le nouveau conteneur réponde 200 sur le healthcheck avant de couper l’ancien. - Resource limits : si plusieurs apps cohabitent, fixez des limites CPU/RAM par application (onglet Advanced) pour éviter qu’une app gourmande ne tue le VPS entier.
Étape 8 — Base de données et services associés
Quasi tout projet Next.js sérieux a besoin d’une base. Provisionnez PostgreSQL en un clic via Coolify (voir notre guide PostgreSQL Coolify) et utilisez l’URL interne comme DATABASE_URL dans votre app. Idem pour Redis si vous utilisez du caching server-side ou des sessions.
Pour Prisma, ajoutez prisma generate dans le script postinstall du package.json pour qu’il soit lancé automatiquement à chaque build :
{
"scripts": {
"postinstall": "prisma generate",
"build": "prisma migrate deploy && next build"
}
}Adaptation Afrique de l’Ouest
Pour des utilisateurs au Sénégal accédant à votre app déployée sur un VPS européen, ajoutez Cloudflare devant votre domaine (gratuit) : le edge cache réduit dramatiquement les temps de chargement et économise la bande passante du VPS. Le mode « Proxied » (orange) suffit, gardez SSL « Full strict » puisque Coolify a déjà un certificat valide. Les Africains accèdent alors à votre app via le datacenter Cloudflare de Lagos, Casablanca ou Le Caire (quelques dizaines de millisecondes) au lieu de Frankfurt (200 ms).
Si votre app fait du paiement Mobile Money via Wave ou Orange Money, déployez l’application + base de données + worker queue (BullMQ par exemple) sur le même Coolify. Notre guide Mobile Money API 2026 montre l’intégration complète.
Erreurs fréquentes
| Erreur | Cause | Solution |
|---|---|---|
| Out of memory pendant npm run build | VPS < 4 Go RAM ou app très grosse | Ajouter 2 Go de swap, ou monter en gamme VPS |
| NEXT_PUBLIC_* undefined en prod | Variable pas marquée « Build variable » | Cocher la case dans l’onglet Variables |
| Erreur Prisma « Cannot find module » | prisma generate non lancé | Ajouter dans postinstall ou dans build script |
| 404 sur les API routes | Mauvais port ou redirection Traefik | Vérifier port 3000 dans config Coolify |
| Build infini sur ISR pages | API externe lente pendant getStaticProps | Ajouter timeout, ou passer en SSR/dynamic |
| Conteneur OOM killed après quelques minutes | Memory leak dans l’app | Profiler avec node –inspect, fixer la fuite |
| Images Next.js cassées | sharp absent ou domaine non whitelisté | Ajouter remotePatterns dans next.config.js |
Pour aller plus loin
- Guide complet Coolify self-hosted
- PostgreSQL managé avec Coolify
- Coolify vs Dokploy vs CapRover
- Backups Coolify S3 et MinIO
- Documentation officielle Next.js : nextjs.org/docs
- Documentation officielle Coolify : coolify.io/docs
FAQ
Coolify supporte-t-il Next.js App Router (Next.js 14+) ?
Oui, totalement. Coolify ne fait aucune supposition sur la version ou l’architecture de Next.js : il lance simplement les commandes npm run build et npm start que définit votre package.json. App Router, Pages Router, Turbopack, tout fonctionne.
Comment gérer ISR (Incremental Static Regeneration) ?
ISR fonctionne nativement, mais nécessite un volume persistant pour stocker le cache des pages régénérées. Sinon le cache est perdu à chaque redeploy. Configurez un volume Coolify monté sur /app/.next/cache.
Peut-on utiliser Edge Runtime sur Coolify ?
Non, Edge Runtime est spécifique à Vercel. Sur Coolify, vos routes API et middleware tournent en Node.js standard, ce qui est très bien dans 99 % des cas (et même supérieur en termes de fonctionnalités, puisque vous avez accès à toutes les API Node.js).
Comment faire du A/B testing ou du canary deployment ?
Coolify v4 supporte les déploiements multi-environnements. Vous pouvez héberger une version « canary » sur un sous-domaine séparé et router une fraction du trafic via Cloudflare Workers ou un middleware Next.js qui lit un cookie. Pour du blue-green plus simple, utilisez deux applications Coolify identiques et basculez le DNS.