Référence paas.toml

Le fichier paas.toml versionne la configuration de votre projet : contrat N3 pour les recettes publiées, ou configuration du parcours historique.

Le fichier paas.toml à la racine de votre dépôt configure votre application de manière déclarative. Une recette N3 publiée attend son contrat complet. Les fichiers historiques valides sans bloc [n3] conservent leur parcours ; l’absence de configuration N3 connue peut ouvrir une découverte et une réparation bornées.

Le contrat [n3] des recettes publiées

Le bloc [n3] lie la recette, la version applicative et ses paramètres au code client. Lorsqu’il est présent, il prime sur les anciens descripteurs de runtime ; les sources complètes et les verrous de dépendances restent indispensables.

Entrée du contrat	Rôle
`contract_version`	Version du format de configuration N3 publié, actuellement `1`. Ce n’est pas la version du contrat d’inventaire de chaque capacité.
`recipe` et `recipe_version`	Identifiant et version de la recette publiée. Une recette ne couvre que les logiciels et versions admis.
`version`	Version du logiciel applicatif choisie dans les couples publiés.
`services` et `bindings`	Services et raccordements attendus par la recette. Un fournisseur existant peut être réutilisé avec les seuls accès du projet.
`[n3.account]`	Identité initiale autorisée : `username`, `email` et `title`. Une mise à jour ne réinitialise pas implicitement le compte.
`[n3.node]`, `[n3.php]`, `[n3.go]`, `[n3.python]`, `[n3.npm]`, `[n3.jvm]`, `[n3.ruby]`, `[n3.elixir]`	Paramètres requis selon la recette : versions compatibles, dépendances, commandes et options admises. JVM, Ruby et Elixir sont notamment utilisés par Metabase, Discourse/Redmine et Plausible. Ne rajoutez pas une section dont la recette n’a pas besoin.

Partir d’une configuration complète

La référence de recette est fournie par le catalogue de configuration. Par exemple, la requête de lecture suivante sélectionne une version publiée de DokuWiki :

GET /v1/environment-catalogue/n3/configuration?recipe=dokuwiki&version=2026-07-14b

Utilisez le fichier complet retourné, puis adaptez les paramètres autorisés à votre projet. Cette requête de lecture ne crée ni ne déploie d’application. Une configuration seule ne remplace pas les sources et dépendances manquantes. Aucun mot de passe ou secret n’appartient au fichier Git.

Les noms d’entrées du catalogue de capacités décrivent des contrats techniques : ils ne sont pas tous des clés à copier dans paas.toml. Les versions des recettes, des logiciels et des contrats d’inventaire restent distinctes.

Valider puis faire évoluer

Une configuration connue et compatible est résolue sans appel de modèle. Une proposition de réparation peut modifier uniquement paas.toml, sur une branche du même dépôt, avec CI et PR avant intégration. Le budget automatique de découverte et de réparation est fixé à trois appels privés par incident ; une maintenance pendant une installation inachevée conserve ce compteur.

Après épuisement, une configuration revue par un intervenant autorisé repasse les mêmes contrôles. Un échec métier après l’état technique « ready » reste rattaché au commit servi. Les refus, appels historiques et éventuels écarts au budget restent visibles dans les limites du processus.

Installation et mise à jour · Personnaliser N0 à N3 · Ajouter une capacité manquante.

Le parcours historique sans bloc [n3]

Les sections ci-dessous documentent les usages existants. Leurs exemples ne qualifient pas automatiquement une option pour une recette N3 ; utilisez les paramètres admis de sa configuration publiée.

Exemple minimal

Le fichier le plus basique pour une app web. La plateforme détecte le langage automatiquement.

[[processes]]
type = "web"
command = "gunicorn app:app --bind 0.0.0.0:$PORT"

Section [build]

Personnalise le build. Optionnelle.

[build]
buildpack = "auto" # ou "heroku/python"
include = ["src/", "Pipfile*"]
exclude = ["tests/", "*.md"]
env = { NODE_ENV = "production" }

Clé	Description
buildpack	`"auto"` (détection) ou un buildpack explicite. Liste sur /docs/buildpacks.
include	Globs des fichiers à inclure dans le build. Par défaut tout sauf .git/
exclude	Globs à exclure
env	Variables d'environnement disponibles uniquement pendant le build

Section [[processes]]

Liste des process types. Au moins un web est attendu pour qu'une URL soit exposée.

[[processes]]
type = "web"
command = "gunicorn config.wsgi:application --bind 0.0.0.0:$PORT"

[[processes]]
type = "worker"
command = "celery -A config worker --loglevel=info"

[[processes]]
type = "cron-cleanup"
command = "python manage.py cleanup"
schedule = "0 3 * * *" # 3h du matin tous les jours

Clé	Description
type	`web`, `worker`, ou nom personnalisé pour cron
command	Commande à exécuter
schedule	Cron expression (uniquement pour les types personnalisés cron)
port	Port HTTP pour les process web. Défaut : `$PORT` injecté par la plateforme

Section [scaling]

Configure le scaling auto par type de process. Par défaut, manuel à 1 instance.

[scaling.web]
min = 2
max = 8
target_cpu = 70 # scale up si CPU moyen > 70 %
target_rps = 200 # ou si requêtes par seconde > 200

[scaling.worker]
min = 1
max = 4
target_queue_depth = 100 # scale selon la profondeur de queue

Section [resources]

Réserve de la mémoire au-delà du gabarit standard, pour les applications lourdes (GitLab, JVM, ERP). Validé jusqu’à 8 Gi.

[resources]
memory = "8Gi" # jusqu'à 8 Gi

La section [resources] est prise en compte uniquement en déploiement depuis les sources (git push). En déploiement par image, l’application reste sur le gabarit standard — voir les tailles de dynos.

Section [healthcheck]

Configure la sonde de santé HTTP de vos process web. Tant que la sonde ne répond pas, l’instance ne reçoit pas de trafic.

[healthcheck]
http_path = "/health"   # défaut : "/"
initial_delay_seconds = 5
period_seconds = 10       # intervalle entre deux sondes
failure_threshold = 3    # échecs tolérés avant redémarrage

Applications à démarrage long

Le budget de démarrage vaut period_seconds × failure_threshold. Pour une application qui met plusieurs minutes à démarrer, augmentez ces valeurs — tout se déclare ici, aucune intervention du support n’est nécessaire :

[healthcheck]
http_path = "/-/readiness"
period_seconds = 30
failure_threshold = 30 # 30 × 30 s = budget de 15 minutes

Si votre application restreint son endpoint de santé par IP source (GitLab avec monitoring_whitelist, par exemple), autorisez 127.0.0.0/8 et 10.42.0.0/16 : les sondes de la plateforme proviennent de ce réseau interne. Sans cette autorisation, l’endpoint répond 404 aux sondes et l’instance n’est jamais considérée prête.

Section [observability]

[observability]
tracing = true # auto-instrumentation OpenTelemetry
sample_rate = 0.1 # 10 % des traces collectées
log_level = "info"
metrics_path = "/metrics" # endpoint Prometheus custom

Section [release]

Commande exécutée à chaque release, avant le routage du trafic. Idéal pour les migrations de base de données.

[release]
command = "python manage.py migrate --noinput"
timeout = 600 # secondes
on_failure = "rollback" # ou "abort", "warn"

Si la commande release échoue, par défaut la release est annulée et l'ancienne version reste en production. Vous pouvez changer ce comportement avec on_failure.