Initial commit medias platformHEADmain

1 files changed, 185 insertions, 0 deletions

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.