judu/ex-ego · eacbeb6

⑂ eacbeb6

docs: procédure de déploiement de la doc, vérifiée sur l'app statiqueUnverified

L'app ex-ego-doc est créée et déployée sur son URL cleverapps (build zola
distant, 3 s, types de contenu corrects y compris image/jxl). Reste à
brancher ex-ego.durillon.family/documentation et à retirer le --base-url
de prévisualisation.

Julien Durillon committed 2026-08-11T14:09:53+02:00 Browse files

eacbeb6 parent: 64f28fc

modified docs/site-documentation/DEPLOIEMENT.md +41 -47 Viewed

@@ -1,78 +1,73 @@
1	1	# Déployer la documentation sur Clever Cloud
2	2
3		-La doc est servie par une seconde application, de type `static`, branchée
4		-sur le domaine de production avec un préfixe de chemin :
	3	+La doc est servie par une seconde application, de type `static`, destinée
	4	+au domaine de production avec un préfixe de chemin :
5	5	`https://ex-ego.durillon.family/documentation`. L'application Rust
6	6	(`app_f7c88187-…`) garde la racine du domaine, elle n'est pas touchée.
7	7
	8	+\| \| \|
	9	+\|---\|---\|
	10	+\| Application \| `ex-ego-doc`, alias `doc`, `app_ee0c92a2-3c2f-436a-bd15-fe58881edce3` \|
	11	+\| Zone, taille \| `par`, flavor `pico` \|
	12	+\| URL actuelle \| https://app-ee0c92a2-3c2f-436a-bd15-fe58881edce3.cleverapps.io/documentation \|
	13	+\| Domaine cible \| `ex-ego.durillon.family/documentation` (pas encore branché) \|
	14	+
8	15	## Le point qui commande tout le reste
9	16
10	17	Sur Clever Cloud, le routage par chemin transmet le préfixe à
11	18	l'application : une requête sur `ex-ego.durillon.family/documentation/ecrans/`
12	19	arrive côté statique en tant que `/documentation/ecrans/`. La sortie du build
13		-doit donc vivre dans un dossier `documentation/`, et pas à la racine du
14		-webroot. D'où la construction :
15		-
16		-```bash
17		-cd docs/site-documentation
18		-zola build --output-dir ../../_site/documentation
19		-```
20		-
21		-soit un webroot `_site/` contenant un unique dossier `documentation/`. Le
22		-`base_url` du `config.toml` porte déjà ce même sous-chemin, les deux doivent
	20	+vit donc dans un dossier `documentation/`, et pas à la racine du webroot,
	21	+d'où `CC_WEBROOT=/_site` et une construction vers `_site/documentation`.
	22	+Le `base_url` du `config.toml` porte le même sous-chemin ; les deux doivent
23	23	rester d'accord.
24	24
25		-Vérification locale du montage complet :
	25	+## Configuration en place
26	26
27	27	```bash
28		-cd _site && python3 -m http.server 8099
29		-curl -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8099/documentation/
	28	+clever env --alias doc
	29	+# CC_WEBROOT="/_site"
	30	+# CC_BUILD_COMMAND="curl -sSL …/zola-v0.23.2-x86_64-unknown-linux-gnu.tar.gz \
	31	+# \| tar -xz -C /tmp && cd docs/site-documentation \
	32	+# && /tmp/zola build --base-url <url de l'app> --output-dir ../../_site/documentation"
30	33	```
31	34
32		-## Création de l'application (une seule fois)
	35	+Zola est téléchargé et épinglé au build. Le runtime statique sait pourtant
	36	+détecter Zola tout seul, mais uniquement si `config.toml` est à la racine du
	37	+dépôt, ce qui n'est pas le cas ici : d'où la commande explicite. Le build dure
	38	+trois secondes et n'a besoin ni de Chrome, ni de la base, ni de `cjxl`,
	39	+puisque les captures sont versionnées.
33	40
34		-```bash
35		-# Application statique, plus petite taille possible, dans l'org perso
36		-clever create --type static ex-ego-doc --region par --alias doc
	41	+Le `--base-url` de la commande n'existe que le temps de la prévisualisation
	42	+sur l'URL `cleverapps.io`. **Le retirer en même temps qu'on branche le vrai
	43	+domaine**, pour que Zola reprenne le `base_url` du `config.toml`.
37	44
38		-# Construction : zola épinglé, téléchargé au build (le runtime statique sait
39		-# détecter Zola tout seul, mais seulement si config.toml est à la racine du
40		-# dépôt, ce qui n'est pas le cas ici — d'où la commande explicite)
41		-clever env set --alias doc CC_BUILD_COMMAND \
42		- 'curl -sSL https://github.com/getzola/zola/releases/download/v0.23.2/zola-v0.23.2-x86_64-unknown-linux-gnu.tar.gz \| tar -xz -C /tmp && cd docs/site-documentation && /tmp/zola build --output-dir ../../_site/documentation'
43		-clever env set --alias doc CC_WEBROOT /_site
	45	+## Brancher le domaine de production (étape restante)
44	46
45		-# Le domaine de production, avec le chemin
	47	+```bash
46	48	clever domain add --alias doc ex-ego.durillon.family/documentation
47		-
48		-clever deploy --alias doc
	49	+# puis retirer --base-url de CC_BUILD_COMMAND et redéployer
	50	+clever restart --alias doc --without-cache
49	51	```
50	52
51		-`clever create` ajoute un bloc dans `.clever.json`, qui est **ignoré par
52		-git** : chaque poste refait son `clever link` si besoin.
	53	+Ensuite vérifier que `https://ex-ego.durillon.family/` sert toujours
	54	+l'application Rust, et que `/documentation/`, `/documentation/en/` et
	55	+`/documentation/de/` répondent.
53	56
54	57	## Déploiements suivants
55	58
56	59	```bash
57		-clever deploy --alias doc # pousse le HEAD git, donc le parent du working copy jj
58		-clever logs --alias doc # si le build échoue, la sortie de zola est là
	60	+clever deploy --alias doc # pousse le HEAD git (= parent du working copy jj)
	61	+clever restart --alias doc --without-cache # si seule une variable a changé
	62	+clever logs --alias doc --since 10m # la sortie de zola s'y trouve
59	63	```
60	64
61		-Les captures d'écran sont versionnées, le build ne fait que du HTML : il n'a
62		-besoin ni de Chrome, ni de la base, ni de `cjxl`.
63		-
64		-## À vérifier après le premier déploiement
	65	+## Vérifié sur le déploiement du 11 août 2026
65	66
66		-1. `curl -sI https://ex-ego.durillon.family/documentation/img/fr/stats.jxl`
67		- doit renvoyer `content-type: image/jxl`. Si le serveur statique ne connaît
68		- pas l'extension et répond `application/octet-stream`, ajouter un
69		- `Caddyfile` (variables `CC_STATIC_SERVER=caddy` et `CC_STATIC_CADDYFILE`)
70		- qui pose le type sur `*.jxl`. Les navigateurs sans JPEG XL, eux, ne sont
71		- pas concernés : ils prennent le PNG de repli du `<picture>`.
72		-2. La racine `https://ex-ego.durillon.family/` doit continuer à servir
73		- l'application Rust.
74		-3. `https://ex-ego.durillon.family/documentation/en/` et `/de/` répondent, et
75		- le sélecteur de langue conserve la page courante.
	67	+Le serveur est `static-web-server`, et il envoie les bons types de contenu
	68	+sans configuration : `image/jxl` pour les captures JPEG XL, `image/png` pour
	69	+les replis, `font/woff2` pour les polices. Aucun `Caddyfile` n'est nécessaire.
	70	+Les navigateurs sans JPEG XL prennent le PNG du `<picture>`.
76	71
77	72	## Repli si le build distant pose problème
78	73
@@ -81,7 +76,6 @@ pousser que le résultat, sur une branche dédiée :
81	76
82	77	```bash
83	78	zola build --output-dir /chemin/vers/worktree/documentation
84		-# commit dans la branche de publication, puis
85	79	clever deploy --alias doc --branch <branche>
86	80	```
87	81

  # Déployer la documentation sur Clever Cloud
--La doc est servie par une **seconde application**, de type `static`, branchée
++La doc est servie par une **seconde application**, de type `static`, destinée
--sur le domaine de production avec un préfixe de chemin :
++au domaine de production avec un préfixe de chemin :
  `https://ex-ego.durillon.family/documentation`. L'application Rust
  (`app_f7c88187-…`) garde la racine du domaine, elle n'est pas touchée.
++| | |
++|---|---|
++| Application | `ex-ego-doc`, alias `doc`, `app_ee0c92a2-3c2f-436a-bd15-fe58881edce3` |
++| Zone, taille | `par`, flavor `pico` |
++| URL actuelle | https://app-ee0c92a2-3c2f-436a-bd15-fe58881edce3.cleverapps.io/documentation |
++| Domaine cible | `ex-ego.durillon.family/documentation` (pas encore branché) |
++
  ## Le point qui commande tout le reste
  Sur Clever Cloud, le routage par chemin **transmet le préfixe** à
  l'application : une requête sur `ex-ego.durillon.family/documentation/ecrans/`
  arrive côté statique en tant que `/documentation/ecrans/`. La sortie du build
--doit donc vivre dans un dossier `documentation/`, et pas à la racine du
++vit donc dans un dossier `documentation/`, et pas à la racine du webroot,
--webroot. D'où la construction :
++d'où `CC_WEBROOT=/_site` et une construction vers `_site/documentation`.
--
++Le `base_url` du `config.toml` porte le même sous-chemin ; les deux doivent
--```bash
--cd docs/site-documentation
--zola build --output-dir ../../_site/documentation
--```
--
--soit un webroot `_site/` contenant un unique dossier `documentation/`. Le
--`base_url` du `config.toml` porte déjà ce même sous-chemin, les deux doivent
  rester d'accord.
--Vérification locale du montage complet :
++## Configuration en place
  ```bash
--cd _site && python3 -m http.server 8099
++clever env --alias doc
--curl -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8099/documentation/
++# CC_WEBROOT="/_site"
++# CC_BUILD_COMMAND="curl -sSL …/zola-v0.23.2-x86_64-unknown-linux-gnu.tar.gz \
++#   | tar -xz -C /tmp && cd docs/site-documentation \
++#   && /tmp/zola build --base-url <url de l'app> --output-dir ../../_site/documentation"
  ```
--## Création de l'application (une seule fois)
++Zola est téléchargé et épinglé au build. Le runtime statique sait pourtant
++détecter Zola tout seul, mais uniquement si `config.toml` est à la racine du
++dépôt, ce qui n'est pas le cas ici : d'où la commande explicite. Le build dure
++trois secondes et n'a besoin ni de Chrome, ni de la base, ni de `cjxl`,
++puisque les captures sont versionnées.
--```bash
++Le `--base-url` de la commande n'existe que le temps de la prévisualisation
--# Application statique, plus petite taille possible, dans l'org perso
++sur l'URL `cleverapps.io`. **Le retirer en même temps qu'on branche le vrai
--clever create --type static ex-ego-doc --region par --alias doc
++domaine**, pour que Zola reprenne le `base_url` du `config.toml`.
--# Construction : zola épinglé, téléchargé au build (le runtime statique sait
++## Brancher le domaine de production (étape restante)
--# détecter Zola tout seul, mais seulement si config.toml est à la racine du
--# dépôt, ce qui n'est pas le cas ici — d'où la commande explicite)
--clever env set --alias doc CC_BUILD_COMMAND \
--  'curl -sSL https://github.com/getzola/zola/releases/download/v0.23.2/zola-v0.23.2-x86_64-unknown-linux-gnu.tar.gz | tar -xz -C /tmp && cd docs/site-documentation && /tmp/zola build --output-dir ../../_site/documentation'
--clever env set --alias doc CC_WEBROOT /_site
--# Le domaine de production, avec le chemin
++```bash
  clever domain add --alias doc ex-ego.durillon.family/documentation
--
++# puis retirer --base-url de CC_BUILD_COMMAND et redéployer
--clever deploy --alias doc
++clever restart --alias doc --without-cache
  ```
--`clever create` ajoute un bloc dans `.clever.json`, qui est **ignoré par
++Ensuite vérifier que `https://ex-ego.durillon.family/` sert toujours
--git** : chaque poste refait son `clever link` si besoin.
++l'application Rust, et que `/documentation/`, `/documentation/en/` et
++`/documentation/de/` répondent.
  ## Déploiements suivants
  ```bash
--clever deploy --alias doc      # pousse le HEAD git, donc le parent du working copy jj
++clever deploy --alias doc                  # pousse le HEAD git (= parent du working copy jj)
--clever logs --alias doc        # si le build échoue, la sortie de zola est là
++clever restart --alias doc --without-cache # si seule une variable a changé
++clever logs --alias doc --since 10m        # la sortie de zola s'y trouve
  ```
--Les captures d'écran sont versionnées, le build ne fait que du HTML : il n'a
++## Vérifié sur le déploiement du 11 août 2026
--besoin ni de Chrome, ni de la base, ni de `cjxl`.
--
--## À vérifier après le premier déploiement
--1. `curl -sI https://ex-ego.durillon.family/documentation/img/fr/stats.jxl`
++Le serveur est `static-web-server`, et il envoie les bons types de contenu
--   doit renvoyer `content-type: image/jxl`. Si le serveur statique ne connaît
++sans configuration : `image/jxl` pour les captures JPEG XL, `image/png` pour
--   pas l'extension et répond `application/octet-stream`, ajouter un
++les replis, `font/woff2` pour les polices. Aucun `Caddyfile` n'est nécessaire.
--   `Caddyfile` (variables `CC_STATIC_SERVER=caddy` et `CC_STATIC_CADDYFILE`)
++Les navigateurs sans JPEG XL prennent le PNG du `<picture>`.
--   qui pose le type sur `*.jxl`. Les navigateurs sans JPEG XL, eux, ne sont
--   pas concernés : ils prennent le PNG de repli du `<picture>`.
--2. La racine `https://ex-ego.durillon.family/` doit continuer à servir
--   l'application Rust.
--3. `https://ex-ego.durillon.family/documentation/en/` et `/de/` répondent, et
--   le sélecteur de langue conserve la page courante.
  ## Repli si le build distant pose problème
  ```bash
  zola build --output-dir /chemin/vers/worktree/documentation
--# commit dans la branche de publication, puis
  clever deploy --alias doc --branch <branche>
  ```