# 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.