From b34873f98052ac5fb4bf6731a25730075796d764 Mon Sep 17 00:00:00 2001 From: ertopogo Date: Fri, 13 Mar 2026 00:33:28 +0100 Subject: Initial commit medias platform --- docs/CONFIGURATION.md | 185 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 185 insertions(+) create mode 100644 docs/CONFIGURATION.md (limited to 'docs/CONFIGURATION.md') diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md new file mode 100644 index 0000000..6d9befa --- /dev/null +++ b/docs/CONFIGURATION.md @@ -0,0 +1,185 @@ +# CONFIGURATION + +## Objectif +Tracer tous les parametres techniques et choix de configuration. + +## Perimetre +- Composant: +- Environnement: +- Proprietaire technique: + +## Prerequis +- Installation terminee et validee +- Acces administrateur au composant +- Variables d'environnement disponibles + +## Parametres de configuration +| Cle | Valeur cible | Source | Sensible (oui/non) | Commentaire | +| --- | --- | --- | --- | --- | +| example.key | example.value | env/file | non | A adapter | + +## Procedure de configuration +1. Sauvegarder l'etat courant. +2. Appliquer les parametres. +3. Redemarrer/recharger le composant. +4. Controler les effets attendus. + +## Validation de configuration +- Parametres appliques et persistants +- Test fonctionnel reussi +- Test securite reussi (roles/scopes/groupes) + +## Rollback configuration +- Sauvegarde utilisee: +- Etapes de retour arriere: +- Verification apres retour arriere: + +## Logs et evidences +- Logs controles: +- Captures/preuves: +- Ticket/incident lie: + +## Historique des modifications +- Date: +- Auteur: +- Changement: + +## Exemple rempli: configuration OIDC Keycloak pour acces medias +### Perimetre +- Composant: media-access-api +- Environnement: dev +- Proprietaire technique: equipe plateforme + +### Parametres de configuration (exemple) +| Cle | Valeur cible | Source | Sensible (oui/non) | Commentaire | +| --- | --- | --- | --- | --- | +| OIDC_ISSUER | https://auth.local/realms/medias | env | non | URL issuer Keycloak | +| OIDC_AUDIENCE | media-access-api | env | non | Audience attendue | +| OIDC_JWKS_CACHE_TTL | 300 | env | non | Cache JWKS en secondes | +| RBAC_REQUIRED_ROLE | media_reader | env | non | Role minimal lecture | +| OIDC_CLIENT_SECRET | *** | secret store | oui | Secret client confidentiel | + +### Procedure de configuration (exemple) +1. Sauvegarder l'ancien `.env`. +2. Mettre a jour les variables OIDC et RBAC. +3. Redemarrer `media-access-api`. +4. Verifier le endpoint de sante et un endpoint media protege. + +### Validation de configuration (exemple) +- Token valide accepte (200). +- Token sans role `media_reader` refuse (403). +- Token avec mauvais `aud` refuse (401). + +### Rollback configuration (exemple) +- Sauvegarde utilisee: `.env.backup.2026-03-07` +- Etapes de retour arriere: restaurer backup puis redemarrer service. +- Verification apres retour arriere: tests 200/401/403 conformes. + +## Exemple rempli: ACL cumulatives Keycloak -> MinIO -> viewer BFF +### Perimetre +- Composant: media-access-api (enforcement) + viewer-bff (visualisation) +- Environnement: dev +- Proprietaire technique: equipe plateforme + +### Modele de roles cumulables (source Keycloak) +- Principe: deny-by-default, puis union des droits autorises par roles. +- Convention de roles client (client `media-access-api`): + - `media_reader:all` + - `media_reader:folder:photos/equipeA` + - `media_reader:folder:photos/projetX` + - `media_reader:folder:photos/partage` +- Regle d'evaluation: + - si `media_reader:all` est present, acces lecture global; + - sinon, acces limite aux prefixes declares dans les roles `media_reader:folder:*`; + - l'absence de role valide retourne 403. + +### Mapping role -> prefixe MinIO (exemple) +| Role Keycloak | Prefixe autorise | Type d'acces | +| --- | --- | --- | +| media_reader:folder:photos/equipeA | photos/equipeA/ | lecture | +| media_reader:folder:photos/projetX | photos/projetX/ | lecture | +| media_reader:folder:photos/partage | photos/partage/ | lecture | +| media_reader:all | photos/ | lecture globale | + +### Parametres de configuration (exemple) +| Cle | Valeur cible | Source | Sensible (oui/non) | Commentaire | +| --- | --- | --- | --- | --- | +| OIDC_ISSUER | https://kc.arauco.online/realms/chiruca | env | non | Realm existant | +| OIDC_AUDIENCE | media-access-api | env | non | Audience attendue | +| OIDC_CLIENT_ID | media-access-api | env | non | Client OIDC de l'API | +| OIDC_CLIENT_SECRET | *** | secret store | oui | Secret client confidentiel | +| RBAC_ROLE_PREFIX | media_reader:folder: | env | non | Prefixe de parsing des roles | +| RBAC_ROLE_ALL | media_reader:all | env | non | Role de bypass lecture globale | +| S3_BUCKET | medias-private | env | non | Bucket prive | +| PRESIGN_TTL_SECONDS | 120 | env | non | Duree de vie URL signee | + +### Procedure de configuration (exemple) +1. Creer/mettre a jour les roles client dans Keycloak (`media-access-api`). +2. Affecter les roles aux groupes/utilisateurs selon les dossiers autorises. +3. Aligner les prefixes MinIO avec la convention de roles. +4. Configurer `media-access-api` avec OIDC + S3 + TTL de signature. +5. Redemarrer API et front (`viewer-bff`/proxy) puis valider les acces. + +### Validation de configuration (exemple) +- Utilisateur avec 2 roles dossier voit la somme des 2 perimetres. +- URL signee hors prefixe autorise refusee (403). +- URL signee expiree refusee (403/401 selon implementation). + +### Rollback configuration (exemple) +- Sauvegarde utilisee: export realm Keycloak + backup `.env`. +- Etapes de retour arriere: restaurer roles precedents, recharger config API. +- Verification apres retour arriere: tests ACL et expiration conformes. + +## Exemple rempli: configuration viewer-bff (Node/Express) +### Perimetre +- Composant: viewer-bff +- Environnement: dev +- Proprietaire technique: equipe plateforme + +### Parametres de configuration (exemple) +| Cle | Valeur cible | Source | Sensible (oui/non) | Commentaire | +| --- | --- | --- | --- | --- | +| VIEWER_BFF_PORT | 8082 | env | non | Port HTTP du BFF | +| MEDIA_API_BASE_URL | http://media-access-api:8081 | env | non | URL interne de l'API ACL | +| CORS_ALLOWED_ORIGIN | https://photos.arauco.online | env | non | Origine frontend autorisee | + +### Procedure de configuration (exemple) +1. Copier `.env.photoprism-secure.example` vers `.env.dev`. +2. Renseigner `MEDIA_API_BASE_URL` et `CORS_ALLOWED_ORIGIN`. +3. Lancer `viewer-bff` via `docker compose`. +4. Verifier `GET /health` et les endpoints `/api/me/permissions`, `/api/media/presign`. + +### Validation de configuration (exemple) +- `curl -I https://photos.arauco.online/health` retourne 200. +- `GET /api/me/permissions` sans token retourne 401. +- `POST /api/media/presign` avec token autorise retourne URL signee. + +## Exemple rempli: configuration DNS local via dnsmasq (stack medias) +### Perimetre +- Composant: dnsmasq (LAN) +- Environnement: dev +- Proprietaire technique: equipe plateforme + +### Parametres de configuration (exemple) +| Cle | Valeur cible | Source | Sensible (oui/non) | Commentaire | +| --- | --- | --- | --- | --- | +| EDGE_PROXY_HOST | araucaria | infra | non | Point d'entree Caddy | +| EDGE_PROXY_IP | 192.168.99.10 | infra | non | IP Caddy (exemple) | +| BACKEND_MEDIA_VM_IP | 192.168.99.23 | infra | non | IP VM konenpan | +| DNS_RECORD_PHOTOS | photos.arauco.online -> 192.168.99.10 | dnsmasq | non | UI viewer-bff via Caddy | +| DNS_RECORD_MINIO | minio.arauco.online -> 192.168.99.10 | dnsmasq | non | API S3 via Caddy | +| DNS_RECORD_MINIO_CONSOLE | minio-console.arauco.online -> 192.168.99.10 | dnsmasq | non | Console MinIO via Caddy | +| DNS_RECORD_MEDIA_API | media-api.arauco.online -> 192.168.99.10 | dnsmasq | non | API ACL via Caddy | + +### Procedure de configuration (exemple) +1. Creer `/etc/dnsmasq.d/20-medias-araucaria.conf`. +2. Ajouter les `host-record` de `docs/DNSMASQ_MEDIAS.md` (vers IP `araucaria`). +3. Configurer les vhosts Caddy de `docs/CADDY_ARAUCARIA.md` (vers IP `konenpan`). +4. Tester `dnsmasq --test` et `caddy validate`. +5. Redemarrer `dnsmasq` puis recharger Caddy. +6. Valider la resolution DNS puis les endpoints HTTPS. + +### Validation de configuration (exemple) +- `dig +short photos.arauco.online` retourne l'IP de `araucaria`. +- `curl -I https://photos.arauco.online` retourne une reponse HTTP valide. +- La resolution de `kc.arauco.online` n'est pas surchargee localement. -- cgit v1.2.3