Provisionnement de sous-domaines

Le SDK de la plateforme expose des endpoints pour provisionner un certificat TLS et écrire un vhost actif pour un domaine. On les joint via le SDK loopback à http://127.0.0.1/__bext/sdk/*, authentifié par l'en-tête X-Bext-App-Id (voir Vue d'ensemble du SDK).

Il y a quatre endpoints. Dans la plupart des cas, utilisez le upsert_auto en un appel ; les endpoints individuels certs/provision + vhost/upsert existent pour un contrôle plus fin.

Recommandé : upsert_auto en un appel

upsert_auto provisionne le certificat en une passe (en réutilisant un certificat existant ayant plus de 30 jours de validité), écrit le vhost et recharge — en un seul appel.

POST http://127.0.0.1/__bext/sdk/vhost/upsert_auto
X-Bext-App-Id: <app-id>
Content-Type: application/json

{ "domain": "app.example.com", "root": "/path/to/site", "email": "ops@example.com" }
Champ Requis Notes
domain oui Le nom d'hôte à servir
root oui Racine des documents (bext détecte automatiquement le framework)
email non Email du compte ACME

Réponse :

{
  "ok": true,
  "vhost_path": "…/app.example.com.bext-auto.conf",
  "cert_path": "…/fullchain.pem",
  "key_path": "…/privkey.pem",
  "reloaded_pid": 12345,
  "cert_reused": false
}
Astuce

cert_reused: true signifie qu'un certificat existant avec plus de 30 jours de validité a été utilisé au lieu d'une nouvelle émission ACME.

Les endpoints individuels

certs/provision

Émet un certificat via ACME HTTP-01.

POST http://127.0.0.1/__bext/sdk/certs/provision
X-Bext-App-Id: <app-id>
Content-Type: application/json

{ "domain": "app.example.com", "email": "ops@example.com", "webroot": "…", "pem_dir": "…", "staging": false }
Champ Requis Notes
domain oui Nom d'hôte pour lequel émettre
email non Email du compte ACME
webroot non Webroot du challenge
pem_dir non Où écrire les fichiers PEM
staging non Utiliser l'environnement de staging ACME

Succès :

{ "ok": true, "domain": "app.example.com", "staging": false,
  "not_before": "…", "not_after": "…", "cert_path": "…", "key_path": "…" }
  • domain manquant → 400.
  • Échec → 500 { "ok": false, "error": "…", "domain": "…" }.

Le certificat/la clé écrits sont repris automatiquement par le résolveur SNI — aucun rechargement nécessaire. L'émission repose sur le fait que la plateforme sert /.well-known/acme-challenge/{token} pour n'importe quel hôte.

vhost/upsert

Écrit atomiquement <domain>.bext-auto.conf et recharge.

POST http://127.0.0.1/__bext/sdk/vhost/upsert
X-Bext-App-Id: <app-id>
Content-Type: application/json

{ "domain": "app.example.com", "cert_path": "…", "key_path": "…", "root": "/path/to/site" }
Champ Requis Notes
domain oui Nom d'hôte
cert_path oui Chemin du certificat
key_path oui Chemin de la clé privée
root / proxy_pass / php_fpm_socket non Backend — mutuellement exclusifs ; omettez-les tous pour un placeholder statique
aliases non Noms d'hôte supplémentaires

Réponse { "ok": true, "domain": "…", "vhost_path": "…", "reloaded_pid": 12345 } ; les erreurs de validation → 400.

vhost/remove

POST http://127.0.0.1/__bext/sdk/vhost/remove
X-Bext-App-Id: <app-id>
Content-Type: application/json

{ "domain": "app.example.com" }

Réponse { "ok": true, "domain": "…", "removed": true, "reloaded_pid": 12345 }.

Sous-domaines *.inklura.fr : pas de DNS, TLS automatique

Le DNS wildcard *.inklura.fr résout déjà vers l'edge de la plateforme, donc un nouveau sous-domaine inklura ne nécessite aucune modification DNS et son TLS est généré automatiquement. Vous écrivez tout de même le vhost (via upsert_auto), mais il n'y a rien à configurer au niveau DNS ou certificat.

C'est aussi pourquoi un nouveau sous-domaine inklura est déjà encadrable par la console sans modification de CSP — voir Embarquement en iframe.

Évincer la table de routes de l'edge

Après avoir ajouté un site flambant neuf, l'edge met en cache une table de routes qui ne le connaît pas encore. Évincez-la pour que les requêtes atteignent le nouveau vhost :

POST http://127.0.0.1:8444/nginx-cache/purge-site
Content-Type: application/json

{ "host": "app.example.com" }
Attention

Sautez cette étape sur un hôte flambant neuf et les requêtes risquent de ne pas se résoudre vers votre nouveau vhost jusqu'à ce que la table de routes se rafraîchisse naturellement. Exécutez-la une fois, juste après l'upsert du vhost.

Voir aussi