Aller au contenu principal

Publier un site statique

Disponible

Fonctionnalité déployée et prise en charge. Les champs et commandes décrits ici sont stables au sein de la version v1alpha1.

Un site statique sert les fichiers d'un dossier (HTML, CSS, JS, images) derrière un cache, sous <nom>.<tenant>.dev.stackngo.app. Vous créez le site avec sng cdn create, puis vous publiez votre dossier de build avec sng cdn upload ; aucun serveur à faire tourner.

Prérequis​

  • La CLI sng authentifiée, une session sur votre tenant (sng tenant use acme) ; sng config show affiche le cluster et le tenant.
  • Les droits cdn:write (créer), cdn:upload et cdn:purge (publier et vider le cache) : inclus dans les policies gérées readwrite et admin.
  • Un dossier à publier, par exemple le dist/ produit par npm run build.

1. Créer le site​

sng cdn create docs
site docs créé : https://docs.acme.dev.stackngo.app (stockage default)
déposez le contenu : sng cdn upload docs ./dist
le site est servi dans quelques minutes.

Le nom du site devient le premier label du domaine : minuscules, chiffres et -, 63 caractères au plus. Le site est stocké par la plateforme (stockage default) ; vous n'avez ni bucket ni clé à gérer.

Le même site en manifeste :

docs-site.yml
apiVersion: cdn.stackngo.io/v1alpha1
kind: CDNSite
metadata:
  name: docs
spec:
  domain: docs.acme.dev.stackngo.app
  fallback: index.html       # servi pour les routes inconnues (application monopage)
sng apply docs-site.yml

2. Publier le contenu​

npm run build
sng cdn upload docs ./dist
envoyé 42/42
site docs : 42 fichier(s) publié(s), 0 retiré(s)

Les fichiers sont envoyés en parallèle, puis la plateforme vérifie que tout est arrivé et vide le cache du site. Les fichiers qui n'existent plus dans votre dossier restent en ligne ; pour les retirer :

sng cdn upload docs ./dist --prune
envoyé 40/40
site docs : 40 fichier(s) publié(s), 2 retiré(s)

3. Choisir le comportement des routes​

RequêteFichier servi
/index.html
/assets/app.3f9c.jsassets/app.3f9c.js, ou 404
/docs/intro/ (finit par /)docs/intro/index.html s'il existe, sinon le fallback
/docs/intro (pas d'extension)docs/intro s'il existe, sinon docs/intro/index.html, sinon le fallback

Chaque dossier sert donc son index.html, avec ou sans / final : un site produit par un générateur de site statique (Docusaurus, Hugo, MkDocs…) fonctionne tel quel, sans réglage des liens.

Le fallback (index.html par défaut avec sng cdn create) convient aux applications monopages (React Router, Vue Router) : toute route sans extension qui ne correspond à aucun fichier ni dossier renvoie votre index.html avec un code 200. Une route avec extension (.png, .js) qui manque renvoie 404.

Sans fallback : sng cdn create docs --fallback "", ou retirez fallback du manifeste.

Vérification​

sng cdn list
NAME  URL                                  STORAGE  STATUS   STATE
docs  https://docs.acme.dev.stackngo.app  default  enabled  Ready

sng cdn list montre ce que vous avez déclaré, et l'état du site dans la colonne STATE : Ready quand il est servi, Waiting ou Pending tant qu'il attend quelque chose (un message sous le tableau explique quoi). sng kind get CDNSite docs affiche son manifeste puis son état en commentaires (condition Ready, raison et message). Vérifiez-le aussi directement :

curl -sI https://docs.acme.dev.stackngo.app/

HTTP/2 200, content-type: text/html; charset=utf-8. Tant que le site n'est pas encore servi, il répond 404 not found : patientez quelques minutes (pour un domaine apporté, le temps de la vérification de sa zone).

HTTPS

Le site reçoit automatiquement un certificat HTTPS valide, sans rien déclarer, en général dans les minutes qui suivent sa création. Ce certificat joker couvre tous vos sites placés juste sous votre zone : le suivant (blog.acme.dev.stackngo.app) est en HTTPS dès sa création. Si curl signale encore un certificat non valide une heure après la création du site, contactez le support. Pour servir votre propre certificat, voir tlsSecretRef dans CDNSite.

Publier depuis une CI​

.gitlab-ci.yml
deploy-docs:
  stage: deploy
  image: node:22
  script:
    - npm ci && npm run build
    - sng tenant use acme
    - sng cdn upload docs ./dist --prune
  rules:
    - if: $CI_COMMIT_BRANCH == "main"

L'authentification de sng dans un job (compte machine ou fédération OIDC) est décrite dans CI/CD. Donnez à l'identité de la CI une policy limitée à ce site : cdn:upload et cdn:purge sur cdn/docs.

Pour aller plus loin​

  • Limites d'un envoi : 100 Mio par fichier, 20 000 fichiers par site et par envoi (envoyés par lots de 1 000). Noms de fichiers : lettres, chiffres et ._~@+=,- ; pas d'espace ni d'accent. Les liens symboliques sont ignorés (avertissement sur la sortie d'erreur), .git/ et .DS_Store ne sont jamais envoyés.
  • Parallélisme : --concurrency N (1 à 32, 8 par défaut).
  • Type de contenu : déduit de l'extension (.html, .css, .js, .mjs, .json, .svg, .woff2, .wasm…), application/octet-stream sinon.
  • Cache : voir Maintenance et cache.
  • Votre propre bucket : un site peut servir un bucket de stockage objet qui vous appartient (spec.s3) ; sng cdn upload ne s'applique pas alors, déposez les fichiers vous-même. Voir CDNSite.
  • Domaines : un site se nomme sous <tenant>.dev.stackngo.app (docs.acme.dev.stackngo.app, v2.docs.acme.dev.stackngo.app), ou sous un domaine apporté (docs.exemple.fr, voir Apporter un domaine). Vous pouvez déclarer le site avant sa zone : il reste en Waiting et se met en service dès que la zone est vérifiée, sans nouvelle commande.
  • Un seul périmètre : les sites sont ceux du tenant ; un nom de site et un domaine ne servent qu'une fois dans le tenant.

Voir aussi​