Comment configurer un projet avec hodifly.json ?

Hodifly peut prendre ses réglages dans un fichier hodifly.json à la racine de votre dépôt, plutôt que dans le formulaire de cPanel. Le fichier est facultatif : sans lui, Hodifly détecte ce qu'est votre projet et le formulaire garde les réglages. Avec lui, le dépôt se configure lui-même, la configuration est versionnée avec votre code et revient en arrière avec lui. Déployer deux fois le même dépôt donne deux projets identiques.

{
  "mode": "php",
  "runtime": "php:8.3",
  "docroot": "public",
  "build": "npm run build",
  "persist": ["config/app.yaml", "storage/uploads/"],
  "env": { "required": ["DB_HOST", "DB_USER"] },
  "keepReleases": 5
}

Placez-le à la racine du dépôt, ou à la racine du sous-dossier du paquet pour un projet qui vit dans un monorepo. Vous n'avez pas à l'écrire à la main : dans cPanel, ouvrez votre projet et cliquez sur hodifly.json pour en générer un à partir des réglages que vous avez déjà.

Tous les réglages

Node et Python : le fichier d'entrée

Passenger n'exécute pas npm start : il exécute un fichier, et startup sert à dire lequel. Il accepte un chemin, pas seulement un nom, ce dont une application compilée a besoin :

{
  "mode": "node",
  "runtime": "node:22",
  "build": "npm run build",
  "startup": "dist/main.js"
}

Trois points à connaître :

• L'application est quand même lancée depuis la racine du projet, quelle que soit la profondeur de ce chemin. Les chemins relatifs de votre code, et les dossiers listés dans persist (uploads, assets), continuent de fonctionner.
• Le fichier doit être en CommonJS. Passenger le charge avec require() : une entrée en module ES (un fichier .mjs, ou un projet en "type": "module") a besoin d'un petit fichier passerelle à la racine, et startup pointe sur la passerelle. Dans un fichier server.cjs : import('./dist/server/server.mjs').catch(e => { console.error(e); process.exit(1); });. Next.js, Nuxt, Astro, SvelteKit et Remix n'ont besoin de rien de tout ça, Hodifly l'écrit pour eux.
• Votre serveur doit écouter. Un build Angular SSR n'écoute que si son server.mjs est le module principal, ce qu'il n'est pas sous Passenger : retirez cette condition pour que listen() s'exécute toujours, sur process.env.PORT.

Vous pouvez aussi le définir dans cPanel, dans le champ Fichier de démarrage du projet. Le fichier l'emporte sur le champ.

Une application Ruby n'a pas ce réglage : Rack démarre toujours depuis config.ru.

Ce qu'il ne peut délibérément pas régler

• Le sous-dossier du paquet et la branche. C'est par eux que Hodifly trouve ce fichier.
• Le domaine et le dossier sur votre compte. Le même dépôt sur deux domaines, ce sont deux projets : l'adresse appartient à l'hébergement, pas au code.
• Tout ce qui est secret : les valeurs des variables d'environnement, le secret du webhook de déploiement, l'URL du build hook, votre jeton GitLab. Un dépôt est le dernier endroit où ils doivent finir. env.required les nomme, cPanel les détient.

persist : ce qui survit à un déploiement

Chaque déploiement crée une nouvelle release, et les anciennes disparaissent dès qu'il en existe keepReleases plus récentes. Tout ce que votre application écrit dans son propre dossier est donc en sursis, et tout ce que votre dépôt ne livre pas est absent de chaque release. persist règle les deux : chaque chemin listé est déplacé une fois dans un dossier situé hors de toute release, puis relié dans chaque nouvelle, ce qui lui fait survivre aux déploiements et aux retours arrière.

• Un / final veut dire dossier, sans slash c'est un fichier. C'est la seule façon pour Hodifly de savoir quoi créer quand le chemin n'existe encore nulle part.
• Le premier déploiement fixe le contenu de départ. Si votre dépôt livre le chemin, cette copie est conservée. Sinon, le chemin est créé vide et le journal de déploiement affiche exactement où, pour que vous le remplissiez en FTP. Rien n'est jamais recopié depuis un fichier .example : ce qu'un modèle doit devenir vous appartient.
• Ensuite, c'est la copie persistée qui gagne. Une version qui apparaîtrait plus tard dans le dépôt est ignorée.
• Le storage/ de Laravel, les var/log et var/sessions de Symfony et toute base SQLite nommée dans votre configuration sont déjà pris en charge. Ne les listez pas.
• Vous ne pouvez pas persister le dossier depuis lequel votre site est servi : il figerait le site sur une release et aucun déploiement ne pourrait plus remplacer le code.

Un retour arrière restaure le code, jamais les données : vos uploads, votre base et votre configuration restent ceux d'aujourd'hui. Voir « Puis-je revenir en arrière après un mauvais déploiement ? ».

HTTPS : votre site redirige tout seul

Hodifly envoie tout visiteur qui arrive en HTTP simple vers l'adresse en https de la même page, avec une redirection permanente. Les sites statiques, les applications PHP et les applications Node, Python ou Ruby en bénéficient toutes, et vous n'avez rien à demander.

Il y a une condition, et c'est toute la raison d'être de forceHttps : la redirection n'apparaît qu'une fois qu'un vrai certificat couvre effectivement votre domaine. Le premier déploiement d'un nouveau site arrive presque toujours avant que le certificat soit émis, et envoyer les visiteurs vers un https que leur navigateur refuse rendrait le site indisponible jusqu'à son arrivée. Le premier déploiement est donc servi en clair et le signale dans son journal, le certificat est émis, et le déploiement suivant active la redirection de lui-même.

• "forceHttps": false désactive la redirection, pour un site qui a une raison de répondre en clair.
• "forceHttps": true redirige sans attendre le certificat. À n'utiliser que si vous savez qu'il est déjà là : tant qu'il ne l'est pas, le site est injoignable.

Les adresses que votre autorité de certification vérifie, sous /.well-known/, ne sont jamais redirigées : l'émission et le renouvellement continuent de fonctionner en HTTP.

Quels réglages s'appliquent quand

Hodifly relit le fichier depuis votre code à chaque déploiement pour tout ce qui décrit le build : build, install, output, docroot, startup, persist, env.required, keepReleases, noindex et forceHttps. Vous modifiez, vous poussez, c'est fait.

startup est dans cette liste à dessein : c'est le build qui décide quel fichier lance votre application, donc déplacer votre point d'entrée ne doit jamais obliger à retourner dans cPanel pour que quelque chose démarre. La valeur utilisée est réenregistrée sur le projet : le champ Fichier de démarrage affiche donc ce qui tourne réellement.

Le reste (mode, runtime, autodeploy, previews, rebuildEvery, snippets) s'applique à la création du projet, ou quand vous changez son sous-dossier de paquet. Modifier l'un d'eux plus tard dans le fichier suppose de le modifier aussi dans le formulaire.

Là où hodifly.json et un « vercel.json » disent la même chose, hodifly.json l'emporte, et le journal de déploiement le signale.

Vérifier un fichier avant de le pousser

Collez-le dans le validateur sur hodifly.app/fr/validate. Il vous dit si le fichier est valide et, plus utile encore, ce qu'il fera exactement au prochain déploiement.

Bon à savoir

• Un fichier qui n'est pas du JSON valide ne casse jamais un déploiement : il est ignoré, avec un avertissement dans le journal, et le déploiement continue avec les réglages du formulaire.
• Limites : 256 Ko pour le fichier, 500 réglages, 4 Ko par valeur.
• env.required est un bon filet de sécurité. S'il manque une variable, le déploiement s'arrête en quelques secondes en la nommant, au lieu de laisser votre site répondre une page blanche.

Mis à jour le : 03/09/2026