Vercel function timeout (erreur 504) : migrer vers un VPS Coolify pour vos apps IA

Vous avez développé une application moderne avec Next.js, Nuxt, FastAPI ou un autre framework, et tout fonctionne parfaitement en local. ⚡Votre application appelle par exemple l’API Google Gemini, OpenAI ou Anthropic pour générer du texte, analyser un document ou produire une réponse complexe.🎉 Mais après le déploiement sur Vercel, un problème apparaît : l’interface affiche soudainement une erreur 504: GATEWAY_TIMEOUT, accompagnée du code FUNCTION_INVOCATION_TIMEOUT.✨

Cette erreur signifie que votre fonction serverless a dépassé la durée maximale autorisée par la plateforme. 💥Ce problème est particulièrement fréquent avec les applications d’intelligence artificielle, dont les traitements peuvent prendre plusieurs dizaines de secondes, voire plusieurs minutes selon la complexité de la requête.☺😪

Objectif

Ce tutoriel explique comment résoudre un vercel function timeout responsable des erreurs 504 Gateway Timeout dans les applications déployées sur Vercel, en particulier celles qui utilisent des APIs d’intelligence artificielle comme Gemini, OpenAI ou Anthropic.☑ Vous allez comprendre pourquoi ces limites existent dans l’architecture serverless, pourquoi elles peuvent bloquer certains traitements longs, et dans quels cas elles deviennent un véritable obstacle pour les applications IA.😉 La seconde partie du guide montre comment contourner ce problème en migrant votre application vers un VPS LWS avec Coolify. 🚀Cette approche permet de conserver un déploiement moderne basé sur Git, tout en supprimant les limitations strictes de durée d’exécution imposées par les fonctions serverless.

Pré-requis

Ce tutoriel s’adresse aux développeurs web JavaScript/TypeScript ou Python ayant déjà déployé une application sur Vercel (plan Hobby ou Pro) et rencontrant une erreur vercel function timeout ou 504 GATEWAY_TIMEOUT lors d’appels à une API d’IA comme Gemini, OpenAI ou Anthropic. Pour suivre la migration proposée :

• Vous devez disposer d’un compte client LWS actif et d’un VPS KVM LWS compatible Docker (la formule M est généralement recommandée pour les builds applicatifs),
• L’email de livraison fournit l’accès SSH root nécessaire à la configuration du serveur,
• Un dépôt GitHub, GitLab ou Bitbucket contenant votre projet est également requis pour le déploiement via Coolify,
• Un nom de domaine pour activer facilement le HTTPS Let’s Encrypt et de maîtriser les bases de Git, SSH et des variables d’environnement dans un projet web.

Besoin d’un serveur VPS KVM performant et flexible ?

Découvrez nos offres VPS KVM haut de gamme : des ressources garanties et un contrôle total pour vos projets. Profitez d’un hébergement 100 % SSD, d’un accès root complet, le tout dans un datacenter en France. Démarrez dès maintenant à partir de 4,99 €/mois !

Je choisis mon VPS KVM

Cadre technique : comprendre l’erreur vercel function timeout

Lorsqu’une application est déployée sur Vercel, la plupart des traitements backend sont exécutés sous forme de Vercel Functions. Ces fonctions serverless sont conçues pour exécuter des tâches courtes et rapides : génération d’une page, traitement d’une requête API ou récupération de données.

Le problème apparaît lorsque la durée d’exécution dépasse la limite autorisée par la plateforme. Dans ce cas, Vercel interrompt automatiquement la fonction et renvoie une erreur 504: GATEWAY_TIMEOUT, généralement accompagnée du code FUNCTION_INVOCATION_TIMEOUT dans les logs.

Cette situation est devenue fréquente avec les applications intégrant des API d’intelligence artificielle. Une requête vers Gemini, OpenAI ou Anthropic peut parfois prendre plusieurs dizaines de secondes, voire plusieurs minutes lorsque le modèle doit analyser un document volumineux, effectuer un raisonnement complexe ou générer une réponse longue.

En local, ces appels fonctionnent normalement puisque votre machine n’impose aucune limite stricte de durée d’exécution. Mais une fois l’application déployée sur Vercel, la fonction qui appelle l’API IA doit respecter les contraintes de la plateforme.

Le périmètre de ce tutoriel

Ce tutoriel ne vise pas à abandonner Vercel dans tous les cas. La plateforme reste excellente pour les sites statiques, les frontends Next.js ou les API rapides. En revanche, lorsque votre application doit exécuter des tâches longues : génération de texte IA, analyse de documents, workflows automatisés, traitement de données,… les limites du modèle serverless deviennent rapidement contraignantes.

Une application exécutée sur votre propre serveur peut lancer un script ou une requête IA aussi longtemps que nécessaire, sans déclencher de vercel function timeout.

Cas couverts et cas non couverts

Ce tutoriel s’adresse aux développeurs qui rencontrent un vercel function timeout lié à des traitements backend trop longs pour l’environnement serverless. Les cas couverts incluent notamment :

• une API Next.js qui appelle un modèle d’IA (Gemini, OpenAI, Anthropic)
• la génération de texte ou d’analyse de documents volumineux
• un endpoint qui traite des PDF, images ou datasets importants
• des workflows automatisés exécutés côté serveur
• des requêtes API qui dépassent régulièrement 30 à 300 secondes

Dans ces situations, migrer l’application vers un VPS avec Coolify permet d’exécuter des tâches longues sans interruption.

En revanche, ce guide ne concerne pas :

• les erreurs 504 liées à un problème réseau ou DNS
• les erreurs provenant d’une API externe indisponible
• les bugs applicatifs dans votre code backend
• les applications purement front‑end ou statiques

Si votre fonction échoue uniquement à cause d’un dépassement de durée d’exécution sur Vercel, alors la migration vers un VPS constitue une solution pertinente.

Besoin d'un serveur privé virtuel VPS sécurisé ?

LWS vous conseille sa formule d’hébergement sur VPS en promotion à -75% (offre à partir de 4,99€ par mois au lieu de 19,99 €). Non seulement les performances sont au rendez-vous mais vous profitez en plus d’un support exceptionnel.

Découvrir l'offre

Étapes techniques à suivre

Étape 1 : Identifier et lire l’erreur 504 dans Vercel

Avant de modifier votre architecture ou de migrer votre application, il est essentiel de confirmer que l’erreur provient bien d’un vercel function timeout. Plusieurs types d’erreurs peuvent provoquer un code 504, et toutes ne sont pas liées à la durée d’exécution d’une fonction.

Vercel fournit deux outils principaux pour diagnostiquer le problème :

• les Runtime Logs dans le dashboard Vercel
• les outils de développement du navigateur (DevTools)

L’objectif est de vérifier la présence du message FUNCTION_INVOCATION_TIMEOUT, qui indique qu’une fonction a dépassé sa durée maximale d’exécution.

1. Vérifier l’erreur dans le navigateur

La première indication apparaît généralement côté utilisateur. Lorsque la fonction dépasse la durée autorisée, la requête API échoue et le navigateur affiche une erreur de type : 504: GATEWAY_TIMEOUT

Selon la configuration de votre application, cette erreur peut apparaître :

• directement dans la page
• dans la console du navigateur
• dans la réponse d’un endpoint API

Dans la plupart des applications Next.js, l’erreur se manifeste lors d’un appel à une route comme :

/api/generate
/api/chat
/api/analyze

Pour analyser précisément la requête :

• Ouvrez les outils développeur du navigateur :

• Ouvrez l’onglet « Network »

• Relancez l’action qui déclenche la requête API
• Repérez la requête affichant le statut 504

En sélectionnant la requête, vous pouvez observer :

• Le code de statut 504
• L’URL de l’endpoint concerné
• La durée totale de la requête

Cette durée est un indice important : lorsqu’elle correspond exactement à la limite d’exécution configurée dans Vercel (par exemple 60 secondes ou 300 secondes), il s’agit presque toujours d’un timeout.

Captures d’écran à prévoir :

• requête API en erreur dans DevTools → Network
• code 504 Gateway Timeout
• durée d’exécution visible

2. Lire les logs dans le dashboard Vercel

Pour confirmer l’origine de l’erreur, il faut consulter les logs d’exécution de la fonction.

Dans le dashboard Vercel, rendez-vous dans la section « vercel.com/dashboard → [Nom du projet] → Logs → Runtime Logs ».

Les Runtime Logs affichent toutes les exécutions de fonctions serverless associées à votre projet. Lorsqu’un timeout se produit, vous verrez généralement apparaître un message similaire à :

FUNCTION_INVOCATION_TIMEOUT

Ce message indique que Vercel a interrompu la fonction car elle a dépassé la durée maximale autorisée.

Dans certains cas, les logs peuvent également afficher :

• la route API concernée
• la durée d’exécution atteinte
• l’identifiant de la fonction

Distinguer un vrai timeout d’une autre erreur

Un point important : toutes les erreurs 504 ne sont pas forcément des timeouts. Plusieurs situations peuvent produire un comportement similaire :

• une variable d’environnement manquante empêchant la connexion à une API externe
• une boucle infinie dans le code
• une API distante qui ne répond jamais
• un bug bloquant dans la logique de la fonction

La manière la plus fiable de confirmer un vercel function timeout consiste à comparer la durée de la requête avec la limite d’exécution configurée dans Vercel. Par exemple :

• fonction configurée avec maxDuration: 60
• requête qui échoue exactement après 60 secondes
• log contenant FUNCTION_INVOCATION_TIMEOUT

Dans ce cas, le diagnostic est clair : la fonction est simplement trop longue pour l’environnement serverless de Vercel.

Étape 2 : Comprendre la limite de durée Vercel selon le plan

Une fois l’erreur FUNCTION_INVOCATION_TIMEOUT identifiée dans les logs, l’étape suivante consiste à comprendre pourquoi la fonction dépasse la durée autorisée. Dans Vercel, chaque fonction serverless dispose d’un temps maximal d’exécution, qui dépend du plan utilisé et de la configuration du projet.

Cette limite est souvent suffisante pour des APIs rapides, mais elle peut devenir contraignante lorsqu’une application exécute des tâches lourdes, comme des appels à des modèles d’intelligence artificielle ou le traitement de documents volumineux.

Limites d’exécution selon le plan Vercel

Les limites de durée d’exécution varient selon le plan Vercel et selon que l’option Fluid Compute est activée ou non.

Sur le plan Hobby (gratuit), la limite historique était de 10 secondes, ce qui provoquait très rapidement un vercel function timeout dès qu’une requête prenait un peu de temps. Depuis les mises à jour de la plateforme, cette durée peut être configurée jusqu’à 60 secondes pour certaines fonctions.

Avec Fluid Compute, Vercel autorise des durées plus longues : une fonction peut théoriquement atteindre 300 secondes (5 minutes) sur le plan Hobby. Sur le plan Pro, les fonctions peuvent être configurées jusqu’à 300 secondes, et les environnements utilisant Fluid Compute disposent de limites encore plus élevées.

Enfin, le plan Enterprise peut atteindre 900 secondes d’exécution dans certains cas. Ces améliorations rendent Vercel beaucoup plus flexible qu’auparavant, mais elles ne suppriment pas totalement le problème. Les fonctions restent soumises à un plafond de durée, et surtout à des limitations de consommation mensuelle de CPU actif lorsque Fluid Compute est utilisé.

Ces valeurs représentent la durée maximale qu’une fonction peut exécuter avant d’être arrêtée automatiquement. Si votre application appelle une API d’IA qui met 2 à 4 minutes à répondre, elle peut déjà dépasser la limite du plan Hobby standard. Dans ce cas, l’erreur vercel function timeout devient presque inévitable.

Vérifier la configuration dans le dashboard Vercel

La première chose à faire est de vérifier la limite actuelle appliquée à votre projet. Dans le dashboard Vercel :

Rendez-vous dans la section « vercel.com/dashboard → [Projet] → Settings → Functions ». Dans cette section, vous trouverez le paramètre Function Max Duration, qui indique la durée maximale autorisée pour les fonctions serverless du projet.

Cette valeur dépend :

• du plan Vercel utilisé
• de la configuration définie dans le projet
• de l’activation éventuelle de Fluid Compute

Lire ou configurer maxDuration dans le code

En plus de la configuration globale du projet, Vercel permet parfois de définir une durée maximale directement dans le code de certaines routes. Dans une application Next.js App Router, il est possible de définir la durée maximale d’une route API avec la constante suivante :

export const maxDuration = 60

Cette configuration indique à Vercel que la fonction peut s’exécuter jusqu’à 60 secondes. Dans certains projets, la configuration peut aussi apparaître dans le fichier vercel.json :

{ "functions": { "api/generate.js": { "maxDuration": 60 } } }

Qu’est‑ce que Fluid Compute ?

Pour répondre aux besoins d’applications plus lourdes, Vercel a introduit une option appelée Fluid Compute. Cette technologie modifie la manière dont les fonctions serverless sont exécutées afin de permettre :

• des durées d’exécution plus longues
• une gestion plus flexible des ressources
• une meilleure prise en charge des workloads intensifs

Lorsque Fluid Compute est activé, la durée maximale peut augmenter significativement selon le plan.

Par exemple :

• jusqu’à 300 secondes sur le plan Hobby

• jusqu’à 800 secondes sur le plan Pro

L’activation peut se faire depuis les paramètres du projet si l’option est disponible dans votre interface Vercel.

Comparaison économique : Vercel Pro vs VPS

Pour contourner ces limitations, certains développeurs passent au plan Vercel Pro, qui permet des fonctions plus longues et l’utilisation de Fluid Compute. Cependant, ce choix implique un abonnement mensuel et une facturation basée sur l’usage des fonctions.

À l’inverse, un VPS KVM chez LWS offre une approche différente :

• une machine dédiée
• aucune limite stricte sur la durée d’exécution des scripts
• un coût mensuel fixe

Dans certains cas notamment pour des applications IA exécutant des tâches longues l’utilisation d’un VPS peut devenir plus prévisible et économiquement rationnelle.

Besoin d’un serveur VPS KVM performant et flexible ?

Découvrez nos offres VPS KVM haut de gamme : des ressources garanties et un contrôle total pour vos projets. Profitez d’un hébergement 100 % SSD, d’un accès root complet, le tout dans un datacenter en France. Démarrez dès maintenant à partir de 4,99 €/mois !

Je choisis mon VPS KVM

Étape 3 : Pourquoi même Fluid Compute ne suffit pas pour l’IA intensive

L’activation de Fluid Compute améliore clairement les capacités d’exécution des fonctions Vercel. Les durées maximales deviennent plus longues et la gestion des ressources est plus flexible. Pour de nombreuses APIs classiques, cette évolution suffit à éliminer les erreurs FUNCTION_INVOCATION_TIMEOUT.

Cependant, lorsqu’une application repose fortement sur des modèles d’intelligence artificielle, certaines limites structurelles du serverless peuvent réapparaître. Ces limitations ne sont pas liées à une mauvaise configuration du projet, mais au fonctionnement même des plateformes serverless mutualisées. Comprendre ces contraintes permet de déterminer dans quels cas il devient plus pertinent d’utiliser un serveur long‑running, comme un VPS.

Une durée de génération imprévisible pour les modèles d’IA

Contrairement à une API traditionnelle, une requête vers un modèle d’IA n’a pas toujours une durée prévisible. Plusieurs facteurs peuvent influencer le temps de génération :

• la taille du prompt envoyé au modèle
• la taille du document à analyser
• le modèle utilisé
• les modes de raisonnement avancés
• la charge des serveurs de l’API externe

Par exemple, certains modèles récents incluent des mécanismes de raisonnement étendu. Des variantes comme Gemini 2.5 Pro avec mode « thinking » peuvent prendre plus de temps pour produire une réponse, car le modèle effectue des étapes de raisonnement supplémentaires avant de générer la sortie finale.

Dans une application réelle, ces variations peuvent entraîner :

• des réponses en 10 secondes
• puis parfois 2 à 4 minutes
• voire plus dans certains cas complexes

Dans un environnement serverless, cette variabilité devient problématique, car la durée maximale reste strictement limitée. Même avec Fluid Compute, une fonction qui dépasse la limite sera simplement interrompue par la plateforme.

Les quotas mensuels d’exécution

Un autre aspect souvent moins visible concerne les quotas mensuels d’exécution inclus dans les plans serverless. Sur le plan Hobby, Vercel inclut un volume limité de temps d’exécution cumulé pour les fonctions. Lorsque ce quota est atteint, les fonctions peuvent être :

• ralenties
• limitées
• ou temporairement suspendues

Pour une application classique, ces quotas sont rarement un problème. Mais une application d’IA peut rapidement consommer beaucoup de temps d’exécution, notamment si elle traite :

• des documents longs
• des analyses automatisées
• des requêtes utilisateurs multiples
• des workflows génératifs complexes

Dans ce contexte, la combinaison de fonctions longues + volume d’appels élevé peut atteindre les limites mensuelles plus rapidement que prévu.

La question du coût

Une solution naturelle consiste à passer au plan Vercel Pro, qui augmente les limites d’exécution et offre plus de ressources. Cette option est parfaitement adaptée à de nombreux projets professionnels. Vercel reste une plateforme très efficace pour le déploiement d’applications modernes.

Cependant, lorsque l’application repose fortement sur des tâches longues, le coût peut devenir un facteur à prendre en compte.

Les fonctions serverless sont facturées selon :

• la durée d’exécution
• la consommation de ressources
• le nombre d’invocations

Plus les traitements sont longs, plus la facture peut augmenter. À l’inverse, un VPS KVM chez LWS fonctionne sur un modèle différent : un coût mensuel fixe pour une machine dédiée. Le serveur peut exécuter des scripts pendant plusieurs minutes, voire plusieurs heures, sans être interrompu par une limite d’exécution imposée par la plateforme. Cette approche offre souvent une meilleure prévisibilité budgétaire pour certains types de workloads.

Serverless vs serveur long‑running

La différence fondamentale entre ces deux architectures concerne la manière dont les processus sont exécutés. Dans une plateforme serverless, chaque requête déclenche une invocation éphémère :

• la fonction démarre
• elle exécute le code
• elle doit terminer avant la limite maximale
• l’environnement est détruit

Ce modèle est extrêmement efficace pour des tâches rapides. Mais pour des traitements plus lourds, une approche long‑running devient souvent plus adaptée. Sur un serveur classique :

• le processus peut rester actif aussi longtemps que nécessaire
• aucune limite artificielle d’exécution n’est imposée
• les traitements IA peuvent se terminer naturellement

Concrètement, cela signifie qu’un workflow comme : envoyer un document de 200 pages à un modèle d’IA, attendre plusieurs minutes de traitement et générer un rapport complet, peut s’exécuter sans risque d’interruption technique liée à la plateforme.

Transition vers une architecture serveur

Lorsque les workloads IA deviennent plus lourds ou plus fréquents, de nombreux développeurs choisissent de migrer leur backend vers un VPS. Cette solution permet de conserver un déploiement moderne (Git, conteneurs, CI/CD) tout en supprimant les contraintes strictes du serverless.

Étape 4 : Commander un VPS KVM LWS avec le template Coolify

Une fois confirmé que les limitations serverless de Vercel bloquent votre application, la solution consiste à exécuter votre backend sur un serveur capable de faire tourner des processus longs. Pour cela, nous allons utiliser un VPS KVM LWS avec Coolify préinstallé. Coolify est une plateforme open‑source qui permet de déployer facilement des applications (Next.js, Node.js, Docker, bases de données, workers…) sur votre propre serveur.

Accéder aux offres VPS KVM LWS

Rendez‑vous sur la page des offres VPS KVM LWS.

Les VPS KVM proposés par LWS offrent :

• un accès root complet
• une virtualisation KVM isolée
• la compatibilité Docker
• des ressources dédiées (CPU, RAM, stockage)

Ces caractéristiques sont nécessaires pour exécuter Coolify et les conteneurs Docker qui hébergeront votre application. Choisissez une configuration adaptée pour faire fonctionner correctement :

• Docker
• Coolify
• les builds d’applications Next.js
• les appels à des APIs IA

Il est conseillé de choisir au minimum :

• 2 vCPU
• 4 Go de RAM

Cette configuration offre généralement suffisamment de ressources pour un projet IA ou SaaS en phase de démarrage.

Sélectionner le template Coolify

Lors de l’étape de personnalisation du serveur, LWS propose plusieurs templates préinstallés. Dans la liste des templates disponibles, sélectionnez Coolify. Ce template permet de recevoir un VPS déjà configuré avec Coolify, ce qui évite les étapes d’installation manuelle et permet de commencer immédiatement le déploiement de votre application.

Validez la commande.

Réception du VPS après la commande

Après validation de la commande, LWS procède automatiquement au déploiement du serveur. La livraison d’un VPS KVM LWS est généralement effectuée en moins de 600 secondes. Vous recevrez ensuite un email de livraison contenant les informations d’accès au serveur :

• adresse IP du VPS
• utilisateur root
• mot de passe initial
• lien vers le panel de gestion LWS

Accéder au panel VPS LWS

Une fois le serveur actif, vous pouvez accéder à son interface de gestion via le panel VPS KVM. Ce panel permet notamment de :

• redémarrer le serveur
• accéder à la console
• surveiller l’utilisation des ressources
• gérer certaines options réseau

Si le template Coolify n’est pas disponible

Dans certains cas, le template Coolify peut ne pas apparaître dans la liste lors de la commande. Si cela arrive, il reste très simple d’installer Coolify manuellement après réception du VPS. Connectez‑vous en SSH au serveur puis exécutez le script officiel :

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

Ce script installe automatiquement :

• Docker
• les dépendances nécessaires
• l’interface Coolify

L’installation prend généralement quelques minutes seulement.

Besoin d’un serveur VPS KVM performant et flexible ?

Découvrez nos offres VPS KVM haut de gamme : des ressources garanties et un contrôle total pour vos projets. Profitez d’un hébergement 100 % SSD, d’un accès root complet, le tout dans un datacenter en France. Démarrez dès maintenant à partir de 4,99 €/mois !

Je choisis mon VPS KVM

Étape 5 : Accéder à l’interface Coolify et créer le compte administrateur

Une fois votre VPS KVM LWS livré et opérationnel, l’étape suivante consiste à accéder à l’interface web de Coolify afin de finaliser l’installation et créer le premier compte administrateur. Coolify fournit une interface de gestion complète permettant de déployer des applications, gérer les bases de données, configurer des domaines et administrer votre serveur.

Accéder à l’interface Coolify depuis votre navigateur

Par défaut, l’interface web Coolify est accessible via le port 8000 du serveur. Dans votre navigateur, saisissez l’adresse suivante :

http://IP_DU_VPS:8000

Par exemple :

http://123.45.67.89:8000

Si l’installation s’est déroulée correctement, vous arriverez sur l’écran de création du premier compte administrateur.

Créer le compte administrateur

Lors de la première connexion, Coolify demande de créer un compte administrateur pour sécuriser l’instance.

Vous devrez renseigner :

• une adresse email
• un mot de passe administrateur

Ce compte vous permettra d’accéder au tableau de bord et de gérer l’ensemble de votre infrastructure. Après validation, vous serez automatiquement redirigé vers le dashboard principal de Coolify.

Ce tableau de bord permet notamment de :

• gérer les serveurs connectés
• déployer des applications
• ajouter des bases de données
• connecter des dépôts Git
• configurer les domaines et certificats HTTPS.

Associer un domaine personnalisé (optionnel)

Il est possible d’accéder à Coolify uniquement via l’adresse IP du serveur. Cependant, pour une utilisation plus confortable, il est recommandé d’associer un nom de domaine.

Dans l’interface Coolify, ouvrez  la section « Settings → Instance Settings → Domain ou URL ».

Dans ce champ, vous pouvez définir le domaine principal de votre instance Coolify.

Par exemple :

coolify.votredomaine.com

Configurer les sous-domaines automatiques

Coolify permet également de générer automatiquement des sous-domaines pour vos applications déployées. Pour configurer cette fonctionnalité, ouvrez la section « Servers → [Nom du serveur] → General ».

Puis renseignez le champ Wildcard Domain

Exemple :

*.apps.votredomaine.com

Avec cette configuration, chaque nouvelle application déployée pourra recevoir automatiquement une URL comme :

mon-app.apps.votredomaine.com

Activer HTTPS avec Let’s Encrypt

Coolify peut générer automatiquement des certificats HTTPS via Let’s Encrypt. Pour que cela fonctionne, vous devez configurer votre domaine pour qu’il pointe vers votre VPS. Dans votre gestionnaire DNS, ajoutez un enregistrement :

Type : A

Valeur : IP_DU_VPS

Selon les fournisseurs DNS, la propagation peut prendre jusqu’à 48 heures avant d’être effective.

Une fois le domaine correctement configuré, Coolify pourra activer automatiquement le HTTPS sécurisé pour votre instance et vos applications.

Étape 6 : Connecter le dépôt GitHub et déployer l’application Next.js

Maintenant que votre instance Coolify est opérationnelle, vous pouvez connecter votre dépôt Git et déployer votre application Next.js. Coolify permet d’automatiser entièrement ce processus : chaque git push sur la branche choisie déclenche automatiquement un nouveau déploiement.

Cette approche permet de conserver un workflow de développement moderne tout en exécutant l’application sur votre VPS long‑running.

Ajouter une source Git dans Coolify

La première étape consiste à connecter votre plateforme Git à Coolify. Dans l’interface Coolify, ouvrez la section « Sources → Add ».

Vous pourrez alors choisir la plateforme utilisée pour votre dépôt :

• GitHub
• GitLab
• Bitbucket

Sélectionnez GitHub App si votre code est hébergé sur GitHub. Coolify va ensuite rediriger vers GitHub pour autoriser l’accès au compte.

Autoriser l’accès GitHub à Coolify

Lors de cette étape, GitHub affiche un écran d’autorisation OAuth demandant l’accès aux dépôts.

Vous pouvez choisir :

• tous les dépôts
• ou uniquement certains dépôts spécifiques

Après validation, GitHub renvoie automatiquement vers l’interface Coolify.

Une fois l’intégration terminée, vos dépôts deviennent sélectionnables lors de la création d’une application.

Créer une nouvelle application dans Coolify

Dans le tableau de bord, ouvrez la section « Projects → [Nom du projet] → New Resource → Application ».

Coolify vous demande alors de sélectionner :

• la source Git
• le dépôt

• la branche à déployer

Dans la plupart des cas, la branche utilisée est :

main ou master

Configurer les commandes de build et de démarrage

Coolify utilise Nixpacks pour détecter automatiquement l’environnement d’exécution (Node.js, Python, etc.). Cette détection fonctionne généralement très bien avec les projets Next.js, sans nécessiter de Dockerfile.

Pour une application Next.js avec App Router, les commandes par défaut sont généralement :

Build Command
npm run build
Start Command
npm run start

Ces valeurs peuvent être vérifiées ou ajustées directement dans l’interface de configuration. Il est également important de vérifier le port exposé par l’application.

Next.js écoute par défaut sur : 3000

Ce port doit correspondre à celui configuré dans Coolify afin que le reverse proxy puisse rediriger correctement les requêtes vers votre application.

Lancer le premier déploiement

Une fois la configuration validée, cliquez sur le bouton « Deploy ». Coolify lance alors automatiquement plusieurs étapes :

• récupération du dépôt Git
• détection de l’environnement via Nixpacks
• installation des dépendances
• build de l’application
• démarrage du conteneur

Vous pouvez suivre l’ensemble du processus dans la section Logs.

Lorsque le déploiement est terminé, Coolify génère automatiquement une URL publique permettant d’accéder à votre application. Vous aurez également le statut Running dans l’interface de l’application.

Déploiement automatique via git push

L’un des avantages majeurs de cette configuration est l’automatisation des déploiements. Chaque fois que vous exécutez :

git push

Sur la branche configurée, Coolify détecte la modification et déclenche automatiquement un nouveau déploiement. Votre application Next.js est ainsi mise à jour sans intervention manuelle sur le serveur.

Étape 7 : Sécuriser la clé API Gemini dans les variables d’environnement

Lorsque votre application Next.js utilise un modèle d’intelligence artificielle (comme Google Gemini, OpenAI ou Anthropic), elle doit disposer d’une clé API permettant d’authentifier les requêtes envoyées vers le service. Cependant, pour des raisons de sécurité, il est impératif de ne jamais stocker une clé API directement dans le code source ni dans le dépôt Git. Une fuite de clé API peut entraîner une utilisation abusive de votre compte et générer des coûts importants.

La bonne pratique consiste à stocker ces informations sensibles dans des variables d’environnement sécurisées, gérées directement par la plateforme d’hébergement. Dans Coolify, ces variables peuvent être marquées comme secrets, ce qui signifie qu’elles sont chiffrées au repos et que leur valeur n’est jamais affichée en clair dans l’interface.

Accéder aux variables d’environnement de l’application

Pour ajouter une clé API dans Coolify, ouvrez l’application déployée dans votre projet. Le chemin dans l’interface est le suivant : « Projects → [Nom du projet] → [Application] → Environment Variables → Add Variable ». Cette section permet de définir toutes les variables d’environnement utilisées par votre application.

Chaque variable est composée de deux éléments principaux :

• Name : le nom de la variable
• Value : la valeur associée

Ajouter la clé API Gemini

Cliquez sur le bouton « Add Variable » pour créer une nouvelle variable. Dans le champ « Name », saisissez le nom attendu par votre application. Par exemple :

GEMINI_API_KEY

Dans le champ « Value », collez la clé API fournie par le service d’intelligence artificielle. Pour renforcer la sécurité, activez l’option « Secret ».

Lorsque cette option est activée, la valeur est masquée dans l’interface et stockée sous forme chiffrée. Cette méthode garantit que les clés API restent hors du code source et ne sont jamais exposées dans le dépôt Git.

Redéployer l’application après modification

Après l’ajout ou la modification d’une variable d’environnementt, l’application doit être redéployée pour que la nouvelle configuration soit prise en compte. Dans Coolify, vous pouvez déclencher ce redéploiement depuis l’interface de l’application en cliquant sur le bouton « Redeploy ».

Ce redémarrage permet au conteneur de charger les nouvelles variables d’environnement au moment du démarrage.

Vérifier la correspondance avec le code

Il est essentiel de vérifier que le nom exact de la variable d’environnement correspond à celui utilisé dans votre code. Par exemple, si votre application lit la clé avec :

process.env.GEMINI_API_KEY

Alors la variable configurée dans Coolify doit s’appeler exactement :

GEMINI_API_KEY

Toute différence dans le nom de la variable entraînera une erreur d’authentification lors de l’appel à l’API. Une fois la variable correctement configurée et l’application redéployée, votre serveur peut appeler l’API Gemini de manière sécurisée, sans exposer la clé dans le code source ni dans le dépôt Git.

Étape 8 : Tester une requête IA longue durée sans timeout

L’un des objectifs principaux du déploiement sur VPS avec Coolify est d’éviter les limitations de durée d’exécution imposées par certaines plateformes serverless comme Vercel. Pour vérifier que votre infrastructure fonctionne correctement, il est recommandé d’effectuer un test avec une requête IA volontairement longue.

Ce test permet de confirmer que l’application peut traiter une opération dépassant 60 secondes d’exécution, sans générer d’erreur 504 Gateway Timeout ou FUNCTION_INVOCATION_TIMEOUT.

Lancer une requête IA longue depuis l’application

Ouvrez votre application Next.js déployée sur le VPS dans votre navigateur.

Depuis l’interface utilisateur de l’application, envoyez un prompt volontairement complexe afin de forcer une durée de traitement importante.

Exemples de tests possibles :

• demander un résumé détaillé d’un long document PDF
• générer un texte d’environ 2 000 mots
• analyser un document long avec Gemini 2.5 Pro
• demander une analyse structurée d’un contenu volumineux

L’objectif est que la requête nécessite plus d’une minute de traitement côté serveur. Contrairement à certaines plateformes serverless, le VPS n’impose pas de limite stricte de durée d’exécution pour ce type de tâche.

Observer les logs en temps réel dans Coolify

Pendant l’exécution de la requête, il est recommandé d’ouvrir les logs de l’application dans Coolify afin de surveiller le comportement du serveur. Voici le chemin à suivre dans l’interface : [Projet] → [Application] → Logs

Cette section affiche les logs en temps réel du conteneur, notamment :

• le démarrage de la requête
• l’exécution du traitement IA
• la réponse envoyée au client

Si l’application fonctionne correctement, les logs doivent se terminer par une fin normale du processus, sans message d’erreur.

Vérifier l’absence d’erreur de timeout

Un déploiement correct sur VPS se reconnaît facilement dans les logs. Les éléments suivants doivent être vérifiés :

• Absence de message FUNCTION_INVOCATION_TIMEOUT
• Absence de réponse 504 Gateway Timeout
• Présence d’une réponse complète envoyée au navigateur

Le navigateur doit afficher la réponse générée par l’IA même si la requête dure plus de 60 secondes.

Comparer avec le comportement sur Vercel (optionnel)

Pour illustrer la différence entre une infrastructure serverless et un VPS, il peut être utile de comparer le résultat avec un déploiement identique sur Vercel. Dans ce cas, une requête trop longue peut provoquer une erreur comme :

504: GATEWAY_TIMEOUT 
FUNCTION_INVOCATION_TIMEOUT

Une capture comparative peut montrer :

• l’erreur 504 dans le navigateur sur Vercel
• la réponse complète obtenue sur le VPS avec Coolify

Si ce test se déroule correctement, cela confirme que votre application peut désormais traiter des requêtes IA longues sans interruption, ce qui est particulièrement important pour des tâches comme l’analyse de documents, la génération de texte volumineux ou les workflows d’IA complexes.

Vérification du bon fonctionnement de votre application

Une fois l’application déployée sur votre VPS via Coolify, il est important de vérifier que l’ensemble de l’infrastructure fonctionne correctement. Cette étape permet de confirmer que votre application peut exécuter des requêtes d’IA longues, que l’intégration Git fonctionne et que la configuration réseau et sécurité est correctement appliquée.

Plusieurs tests simples permettent de valider le bon fonctionnement du système.

Tests concrets à effectuer

Commencez par envoyer un prompt volontairement complexe depuis l’interface de votre application déployée.

Par exemple :

• demander le résumé détaillé d’un long document PDF
• générer un texte d’environ 2 000 mots
• analyser un document volumineux avec Gemini 2.5 Pro

L’objectif est de produire une requête qui nécessite un temps de traitement long, afin de vérifier que l’application ne rencontre plus les limitations typiques des plateformes serverless. La réponse doit apparaître complètement dans le navigateur, sans afficher d’erreur 504 Gateway Timeout. Ensuite, ouvrez les logs dans Coolify pour observer le comportement du serveur.

Vérifiez qu’aucun message d’erreur lié à un timeout n’apparaît et que le processus se termine normalement après l’exécution de la requête. Vous pouvez également tester le fonctionnement du déploiement automatique. Depuis votre dépôt Git local, effectuez une modification simple puis exécutez :

git push

Dans Coolify, ouvrez la section « Projet → Deployments ». Un nouveau déploiement doit se déclencher automatiquement, sans intervention manuelle.

Si vous avez configuré un domaine personnalisé, vérifiez également que le certificat HTTPS est actif. Dans le navigateur, l’URL doit afficher un cadenas sécurisé et le certificat Let’s Encrypt doit être valide. Enfin, vérifiez que la clé API Gemini est correctement injectée dans l’environnement. Pour cela, déclenchez un appel simple à l’API depuis l’application et confirmez l’absence d’erreurs comme :

API_KEY_INVALID 
UNAUTHENTICATED

Critères objectifs de réussite

L’infrastructure peut être considérée comme fonctionnelle si les conditions suivantes sont remplies :

• la réponse IA s’affiche correctement, même pour des générations dépassant 60, 120 ou 300 secondes
• aucun message 504, FUNCTION_INVOCATION_TIMEOUT ou GATEWAY_TIMEOUT n’apparaît dans les logs
• le déploiement automatique fonctionne à chaque git push
• le certificat SSL est valide et le domaine est accessible en HTTPS
• le service reste stable après plusieurs jours sans redémarrage manuel, indiquant un uptime stable

Erreurs fréquentes et cas de blocage connus

Lors de la mise en place d’une infrastructure VPS + Coolify pour remplacer une API serverless limitée par les timeouts, certains problèmes peuvent apparaître pendant l’installation, le déploiement ou l’exécution de l’application.

Le tableau suivant présente les erreurs les plus fréquentes, leur cause probable et la solution recommandée.

Coolify inaccessible via le navigateur sur le port 8000

Le port 8000 est bloqué par le firewall du VPS LWS. Dans ce cas, le serveur fonctionne mais l’interface web Coolify n’est pas accessible depuis le navigateur. Pour résoudre cela, il faut ouvrir le port 8000 dans le firewall physique du serveur via le LWS Panel KVM, puis recharger la page de l’interface Coolify.

Build failed lors du premier déploiement

Le build peut échouer si le répertoire racine du projet est incorrect, si le fichier package.json est absent ou si la commande de build configurée dans Coolify ne correspond pas au projet.

Il faut vérifier :

• le chemin racine du projet
• la présence du fichier package.json
• les logs de build disponibles dans Coolify

Les logs permettent généralement d’identifier précisément l’étape où le build échoue.

Certificat HTTPS non généré

Le domaine n’est pas encore correctement relié à l’IP du VPS. Dans ce cas, la génération automatique du certificat Let’s Encrypt ne peut pas s’effectuer. Cela se produit souvent lorsque la propagation DNS n’est pas terminée.

Dans ce cas, il faut attendre la propagation DNS, qui peut prendre jusqu’à 48 heures, puis vérifier que l’enregistrement A du domaine pointe bien vers l’adresse IP du VPS dans la zone DNS du registrar.

Variables d’environnement non reconnues par l’application

Après l’ajout ou la modification de variables d’environnement dans Coolify, l’application n’a pas été redéployée. Dans ce cas, les nouvelles variables ne sont pas chargées dans le conteneur.

Vous devez déclencher un redéploiement manuel depuis l’interface Coolify afin que l’application redémarre avec les nouvelles variables.

Erreur 502 — l’application répond mais renvoie une erreur

Le port exposé dans la configuration Coolify ne correspond pas au port d’écoute réel de l’application dans le conteneur.

Vérifiez que le port exposé dans Coolify et le port configuré dans le code de l’application sont parfaitement alignés.

GOOGLE_GENERATIVE_AI_ERROR: API_KEY_INVALID

La clé API Gemini est incorrecte ou la variable d’environnement est mal nommée.

Vérifiez que le nom exact de la variable correspond à celui attendu dans le code ou que la clé API est valide. Si nécessaire, générer une nouvelle clé depuis Google AI Studio.

Timeout toujours présent après migration

Le frontend continue d’appeler les anciens endpoints API hébergés sur Vercel, au lieu du nouveau backend déployé sur le VPS. Il faut mettre à jour les URL des endpoints API dans le code frontend afin qu’elles pointent vers le domaine ou l’adresse IP du serveur VPS.

Mémoire insuffisante pendant le build Next.js

Le VPS ne dispose pas de suffisamment de RAM pour effectuer le build du projet Next.js. Les builds modernes peuvent être relativement gourmands en mémoire.

Deux solutions sont possibles :

• passer à une formule VPS plus puissante
• ajouter de la swap Linux pour augmenter temporairement la mémoire disponible.

Erreur « docker: not found » pendant l’installation de Coolify

Docker a été installé via snap, ce qui n’est pas compatible avec l’installation standard de Coolify.

Piste de résolution : désinstaller la version snap de Docker, puis réinstaller Docker via apt en suivant la documentation officielle Docker et Coolify.

Bonnes pratiques reconnues

La mise en place d’une infrastructure VPS avec Coolify pour héberger une application d’intelligence artificielle nécessite l’application de bonnes pratiques en matière de sécurité, performance et maintenance. Ces pratiques permettent de garantir la stabilité du service, de protéger les clés API et d’assurer une exploitation durable de l’environnement serveur.

Sécurité

La première règle consiste à ne jamais versionner les clés API (Gemini, OpenAI, Anthropic ou autres) dans le code source Git. Les clés doivent être stockées exclusivement dans les variables d’environnement de Coolify, en utilisant l’option secret, qui permet de les chiffrer au repos.

Il est également recommandé d’activer HTTPS pour toutes les applications exposées sur Internet. Coolify gère automatiquement la génération et le renouvellement des certificats Let’s Encrypt via son reverse proxy Traefik, ce qui garantit une connexion sécurisée entre le navigateur et l’application.

Sur le plan système, il est conseillé de désactiver l’authentification SSH par mot de passe sur le VPS et d’utiliser uniquement l’authentification par clé SSH, une bonne pratique standard documentée dans les guides de sécurité Linux.

Le firewall du serveur doit également être configuré de manière restrictive. Seuls les ports strictement nécessaires doivent être ouverts dans le LWS Panel KVM, généralement 80 (HTTP), 443 (HTTPS), 22 (SSH) et 8000 pendant la phase de configuration de Coolify.

Enfin, il est recommandé de limiter les origines autorisées à appeler les endpoints IA côté application grâce aux règles CORS, afin d’éviter une utilisation abusive de la clé API par des sites tiers.

Performance

Le choix de la configuration du VPS doit être adapté aux besoins réels de l’application. Pour les applications d’IA utilisant des API externes, la charge CPU reste souvent modérée, mais la mémoire RAM peut devenir le facteur limitant, notamment lors des builds de projets Next.js.

Coolify propose l’utilisation de Nixpacks, un système de détection automatique qui génère l’environnement de build sans nécessiter de Dockerfile manuel. Cette approche simplifie la configuration et réduit les risques d’erreur lors des déploiements.

Il est également recommandé d’activer les sauvegardes automatiques via le LWS Panel KVM, afin de protéger l’environnement serveur en cas de problème technique ou de mauvaise manipulation.

Maintenance

Pour garantir la stabilité de l’infrastructure dans le temps, il est important de maintenir Coolify à jour. Les mises à jour disponibles peuvent être consultées dans l’interface via la section « Settings → Updates », où une notification apparaît lorsqu’une nouvelle version est disponible.

La surveillance des ressources du serveur est également essentielle. Le LWS Panel KVM propose des outils de monitoring permettant d’observer l’utilisation du CPU, de la RAM et du réseau, ce qui facilite l’identification d’un éventuel problème de performance.

Il est aussi recommandé de mettre en place une rotation régulière des clés API, conformément aux politiques de sécurité des fournisseurs comme Google AI Studio ou OpenAI.

Enfin, Coolify permet de configurer des notifications automatiques (email, Slack ou Discord) afin d’être alerté immédiatement en cas d’échec de déploiement ou d’erreur critique.

L’application de ces bonnes pratiques permet de maintenir une infrastructure IA sécurisée, stable et évolutive, adaptée aux besoins d’une application en production.

L’écosystème LWS pour le déploiement d’applications

Au‑delà du simple serveur VPS, LWS propose un écosystème complet d’outils d’hébergement et d’infrastructure qui facilite le déploiement et l’exploitation d’applications web modernes, y compris les applications intégrant des API d’intelligence artificielle.

Cet environnement permet aux développeurs de disposer d’une infrastructure cohérente, centralisée et évolutive, sans dépendre entièrement de plateformes serverless externes.

VPS KVM : une infrastructure flexible pour les applications modernes

Les VPS KVM LWS constituent la base de cet écosystème pour les développeurs souhaitant héberger leurs propres applications. Contrairement aux environnements serverless limités par des durées d’exécution strictes, un VPS permet d’exécuter des processus longs, nécessaires pour certaines opérations comme :

• l’analyse de documents volumineux
• la génération de contenus longs avec des modèles IA
• le traitement de fichiers ou d’images
• les workflows automatisés

L’hyperviseur KVM (Kernel‑based Virtual Machine) garantit une isolation complète des ressources du serveur et permet d’obtenir des performances proches d’un serveur dédié.

Associé à Coolify, ce type de VPS devient une plateforme de déploiement moderne compatible avec :

• Next.js
• Node.js
• Python
• Docker
• bases de données
• workers et tâches asynchrones

Cette architecture permet de conserver un workflow Git‑based deployment tout en gardant le contrôle total sur l’infrastructure.

LWS Panel KVM : gestion centralisée du serveur

Le LWS Panel KVM fournit une interface de gestion permettant d’administrer facilement le VPS.

Depuis ce panneau, il est possible de :

• redémarrer ou arrêter le serveur
• accéder à une console KVM en cas de problème réseau
• gérer les règles du firewall
• surveiller la consommation CPU, RAM et réseau
• activer des sauvegardes automatiques

Ces outils permettent de maintenir l’infrastructure sans nécessiter d’accès constant en ligne de commande. Le panel offre également un niveau de sécurité supplémentaire grâce à la possibilité d’intervenir directement sur la machine virtuelle, même si la configuration réseau devient inaccessible.

Intégration avec les services DNS et domaines

L’écosystème LWS inclut également la gestion des domaines et zones DNS, ce qui simplifie la configuration des applications déployées.

Une fois le VPS configuré, il suffit généralement de créer un enregistrement A pointant vers l’adresse IP du serveur pour connecter un domaine à l’application.

Cette intégration permet ensuite à Coolify de générer automatiquement les certificats HTTPS Let’s Encrypt, assurant un accès sécurisé au service.

Sauvegardes et continuité de service

Pour les applications en production, la sauvegarde de l’infrastructure est un élément essentiel.

Le panel LWS permet d’activer des sauvegardes automatiques du VPS, ce qui offre plusieurs avantages :

• restauration rapide en cas d’erreur de configuration
• récupération après incident serveur
• protection contre les pertes de données

Cette fonctionnalité constitue une couche de sécurité importante pour les projets professionnels ou les applications critiques.

Une alternative durable aux plateformes serverless

En combinant VPS KVM, gestion DNS, firewall, sauvegardes et monitoring, l’écosystème LWS offre une base solide pour héberger des applications web modernes.

Pour les développeurs travaillant avec des API d’intelligence artificielle, cette approche présente plusieurs avantages :

• suppression des limitations de durée d’exécution
• contrôle complet sur l’environnement serveur
• déploiement automatisé via Git et Coolify
• meilleure prévisibilité des coûts d’infrastructure

Cette architecture permet ainsi de construire une plateforme de déploiement stable et évolutive, adaptée aux applications IA qui nécessitent parfois des traitements longs ou des workflows complexes.

Besoin d’un serveur VPS KVM performant et flexible ?

Découvrez nos offres VPS KVM haut de gamme : des ressources garanties et un contrôle total pour vos projets. Profitez d’un hébergement 100 % SSD, d’un accès root complet, le tout dans un datacenter en France. Démarrez dès maintenant à partir de 4,99 €/mois !

Je choisis mon VPS KVM

Conclusion

Migrer une application IA depuis un environnement serverless vers un VPS orchestré avec Coolify permet de lever plusieurs limitations techniques, notamment les timeouts et les contraintes d’exécution imposées par certaines plateformes. ✨En combinant Coolify, un VPS KVM et l’écosystème LWS, il devient possible de déployer des applications modernes tout en conservant un workflow proche des plateformes PaaS. ✍Cette approche offre davantage de contrôle sur l’infrastructure, une meilleure stabilité pour les traitements longs et une gestion simplifiée des déploiements via Git.🚀

En appliquant les bonnes pratiques de sécurité, de performance et de maintenance, cette architecture constitue une base fiable pour héberger durablement des applications IA. Et si vous avez des questions ou besoin d’aide, n’hésitez pas à nous contacter dans la section Commentaires.