docs: mission, decisions d'architecture, guides de deploiement et contribution

2026-07-16 21:05:22 -04:00
parent fbd6527d07
commit 8a9bec0143
4 changed files with 546 additions and 0 deletions
@@ -0,0 +1,111 @@
+# JWE v2 — Guide de déploiement auto-hébergé
+
+Cible : un petit VPS (1 vCPU / 1 Go RAM suffit) sous Debian/Ubuntu, derrière nginx ou Caddy. Aucun service propriétaire, aucune clé API.
+
+## 1. Application SvelteKit
+
+```bash
+# Prérequis : Node.js >= 20 (via nodesource ou nvm)
+git clone https://codeberg.org/OKI/jwe.git
+cd jwe/app
+npm ci
+npm run build          # produit app/build (adapter-node)
+```
+
+Lancer en production (port 3000 par défaut) :
+
+```bash
+PORT=3000 node build
+```
+
+Service systemd `/etc/systemd/system/jwe.service` :
+
+```ini
+[Unit]
+Description=JWE — jeu de géolocalisation OKI
+After=network.target
+
+[Service]
+Type=simple
+User=jwe
+WorkingDirectory=/srv/jwe/app
+Environment=PORT=3000
+Environment=ORIGIN=https://jwe.o-k-i.net
+Environment=PUBLIC_TILES_URL=https://tiles.o-k-i.net/styles/oki/style.json
+ExecStart=/usr/bin/node build
+Restart=on-failure
+
+[Install]
+WantedBy=multi-user.target
+```
+
+## 2. Reverse proxy (exemple nginx)
+
+```nginx
+server {
+    server_name jwe.o-k-i.net;
+    location / {
+        proxy_pass http://127.0.0.1:3000;
+        proxy_set_header Host $host;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    }
+}
+# + TLS via certbot
+```
+
+## 3. Tiles cartographiques auto-hébergées (tileserver-gl)
+
+Par défaut l'application utilise OpenFreeMap (libre, sans clé). Pour une souveraineté complète, hébergez vos propres tiles OSM des 4 régions.
+
+### 3.1 Récupérer les extraits OpenStreetMap
+
+```bash
+mkdir -p /srv/tiles && cd /srv/tiles
+# Guadeloupe, Martinique, Guyane : extraits Geofabrik
+wget https://download.geofabrik.de/north-america/guadeloupe-latest.osm.pbf
+wget https://download.geofabrik.de/north-america/martinique-latest.osm.pbf
+wget https://download.geofabrik.de/south-america/french-guiana-latest.osm.pbf
+# La Réunion
+wget https://download.geofabrik.de/africa/reunion-latest.osm.pbf
+```
+
+### 3.2 Générer les .mbtiles
+
+Avec [openmaptiles](https://github.com/openmaptiles/openmaptiles) (Docker requis) : générez un `.mbtiles` par région puis fusionnez-les avec `tile-join` (paquet `tippecanoe`) :
+
+```bash
+tile-join -o dom-tom.mbtiles guadeloupe.mbtiles martinique.mbtiles guyane.mbtiles reunion.mbtiles
+```
+
+(Alternative plus légère : extraire les 4 régions d'un `.mbtiles` Monde basse-résolution `tile-join --bbox=…` par région, puisque la carte de devinette n'a pas besoin d'un zoom très fin partout.)
+
+### 3.3 Servir avec tileserver-gl
+
+```bash
+docker run --rm -d --name tiles -v /srv/tiles:/data -p 8080:8080 \
+  maptiler/tileserver-gl dom-tom.mbtiles
+```
+
+Copiez le style OKI de l'application (`app/src/lib/map/style-oki.json`) dans `/srv/tiles/styles/oki/`, adaptez son URL de source vers votre `dom-tom.mbtiles`, puis :
+
+```bash
+Environment=PUBLIC_TILES_URL=https://tiles.o-k-i.net/styles/oki/style.json
+```
+
+### 3.4 Fontes et sprites
+
+tileserver-gl sert aussi les fontes (glyphs) et sprites référencés par le style. Les fontes open-source utilisées par le style OKI (ex. Noto Sans) se récupèrent via `openmaptiles/fonts` ou `klokantech/tileserver-gl-fonts`.
+
+## 4. Cache Wikipedia
+
+Le endpoint `/api/wiki/[qid]` met en cache les extraits 24 h en mémoire. Aucune configuration requise ; pour un cache partagé entre instances, placez nginx en cache proxy devant `/api/wiki/` (respecte déjà `Cache-Control`).
+
+## 5. Mise à jour
+
+```bash
+cd jwe && git pull && cd app && npm ci && npm run build
+systemctl restart jwe
+```
+
+L'ajout de lieux (voir `docs/contribution.md`) ne demande qu'un rebuild + restart : le corpus est embarqué dans le build.