From 25b68df5ec6478df29762773ea71abb599b684f1 Mon Sep 17 00:00:00 2001 From: Alpinux Date: Sun, 3 May 2026 20:36:35 +0200 Subject: [PATCH] docs: documente l'upload et les variables d'env de l'app Flask Co-Authored-By: Claude Sonnet 4.6 --- README.md | 104 ++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 101 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index e75d467..9889e77 100644 --- a/README.md +++ b/README.md @@ -11,10 +11,108 @@ CDN pour les fichiers binaires et assets statiques de l'association : logos, fav | `logo/favicon-32.png` | Favicon 32 px | | `logo/favicon-16.png` | Favicon 16 px | | `logo/favicon.ico` | Favicon ICO multi-taille | +| `wiki/` | Images pour wiki.alpinux.org | -Ces fichiers sont **copiés manuellement** sur le serveur dans le répertoire web de static.alpinux.org. Ils ne sont pas versionés dans ce dépôt. +Ces fichiers sont synchronisés sur le serveur via les scripts `push-assets.sh` / `pull-assets.sh`. Ils ne sont pas versionnés dans ce dépôt. -## Déploiement +## Configuration + +```bash +cp .env.example .env +``` + +Editer `.env` : + +| Variable | Obligatoire | Description | +|----------|-------------|-------------| +| `STATIC_HOST` | oui | Alias SSH ou nom d'hôte (`alpinux.org`) | +| `STATIC_PATH` | oui | Chemin absolu du web root sur le serveur | +| `LOCAL_ASSETS_DIR` | oui | Chemin absolu du dépôt local (`static/`) | +| `STATIC_USER` | non | Login SSH — laisser vide si `~/.ssh/config` définit l'utilisateur pour cet hôte | + +### Avec `~/.ssh/config` (recommandé) + +Si l'hôte est déclaré dans `~/.ssh/config` (ex : `Host alpinux.org` avec `User`, `IdentityFile`, etc.), laisser `STATIC_USER` vide. Les scripts utilisent l'alias directement. + +### Sans `~/.ssh/config` + +Renseigner `STATIC_USER=`. Les scripts construisent alors `USER@HOST:PATH`. + +## Scripts + +```bash +./scripts/pull-assets.sh # aperçu des changements + confirmation +./scripts/pull-assets.sh -y # récupère sans confirmation +./scripts/pull-assets.sh -n # dry-run + +./scripts/push-assets.sh # aperçu des changements + confirmation +./scripts/push-assets.sh -y # pousse sans confirmation +./scripts/push-assets.sh -n # dry-run +``` + +`push-assets.sh` n'envoie que les fichiers nouveaux ou modifiés ; il ne supprime jamais rien sur le serveur. + +## Tableau de bord Flask (`app/`) + +Application Flask déployée sur le serveur via `scripts/deploy-app.sh`. Accessible sur `static.alpinux.org` (proxy Apache → `127.0.0.1:5003`). + +### Fonctionnalités + +| Route | Description | +|-------|-------------| +| `/` | Tableau de bord — statistiques CDN par dossier | +| `/browse/` | Navigateur de fichiers — aperçu, suppression, **upload** | +| `/search` | Recherche par nom / contenu / date | +| `/stats/` | Rapport de trafic GoAccess | + +### Upload de fichiers + +Dans le navigateur (`/browse/`), une zone de dépôt est affichée en bas de chaque dossier. Elle accepte plusieurs fichiers à la fois (glisser-déposer ou sélection). Les fichiers sont écrits dans le dossier affiché. Les chemins protégés (`.git`, `app`, `scripts`, etc.) sont refusés avec 403. + +Pour limiter la taille des uploads, ajouter dans `app/app.py` : + +```python +app.config['MAX_CONTENT_LENGTH'] = 50 * 1024 * 1024 # 50 Mo +``` + +### Variables d'environnement + +| Variable | Obligatoire | Description | +|----------|-------------|-------------| +| `SECRET_KEY` | oui | Clé secrète Flask (chaîne aléatoire longue) | +| `ALPID_CLIENT_ID` | oui | Client Keycloak (`static-cdn`) | +| `ALPID_CLIENT_SECRET` | oui | Secret client Keycloak | +| `ALPID_DISCOVERY_URL` | oui | URL OIDC discovery AlpID | +| `ADMIN_GROUPS` | non | Groupes Keycloak autorisés (défaut : `admins`) | +| `ADMIN_EMAILS` | non | Fallback si le claim `groups` est absent du token | +| `ASSETS_ROOT` | oui | Racine du CDN (`/var/www/clients/client1/web17/web` en prod) | + +### Variables d'environnement spécifiques aux stats + +| Variable | Description | +|----------|-------------| +| `STATS_FILE` | Chemin du rapport HTML GoAccess (servi dans l'iframe et l'onglet) | +| `STATS_JSON` | Chemin du JSON GoAccess (badges "Vues" dans le navigateur) | +| `STATS_LOG_FILE` | Log Apache à analyser pour la génération à la demande | +| `STATS_GENERATE_CMD` | Commande complète de génération (remplace la commande par défaut) | + +### Génération du rapport à la demande + +Si `goaccess.html` est absent, la page `/stats/` affiche un bouton **Générer et ouvrir** : +1. Lance GoAccess en arrière-plan (thread daemon) +2. Interroge `/stats/status` toutes les 2 s +3. Ouvre le rapport dans un nouvel onglet dès qu'il est prêt + +**Prérequis serveur :** +- `abonnelc` doit appartenir au groupe `client1` pour lire les logs ISPConfig : + ```bash + sudo usermod -a -G client1 abonnelc + sudo systemctl restart static-cdn + ``` + +--- + +## Déploiement serveur (ISPConfig) Le sous-domaine est créé via **ISPConfig** (`https://owni.alpinux.org:8080`) : @@ -22,4 +120,4 @@ Le sous-domaine est créé via **ISPConfig** (`https://owni.alpinux.org:8080`) : 2. Activer **Let's Encrypt SSL** dans l'onglet SSL 3. Pointer le DocumentRoot vers le répertoire contenant les assets -Pas de configuration Apache manuelle — ISPConfig gère le VirtualHost et le certificat. +ISPConfig gère le VirtualHost et le certificat. Voir `../infra/static/` pour la configuration Apache de référence.