From 55fef5a9931e3d8222fa62211409eff70ab061aa Mon Sep 17 00:00:00 2001
From: Moritz <moritz.m@local-it.org>
Date: Wed, 4 Feb 2026 16:20:39 +0100
Subject: [PATCH] Docs and .env.example for admin bootstrap and OIDC role sync

Documents ADMIN_EMAIL/PASSWORD, seed_admin, entrypoint; OIDC_ADMIN_GROUP_NAME,
OIDC_GROUPS_CLAIM and role sync on register/sign-in.
---
 .env.example                               | 13 ++++++
 docs/admin-bootstrap-and-oidc-role-sync.md | 54 ++++++++++++++++++++++
 2 files changed, 67 insertions(+)
 create mode 100644 docs/admin-bootstrap-and-oidc-role-sync.md

diff --git a/.env.example b/.env.example
index 13154f3..d5d35ed 100644
--- a/.env.example
+++ b/.env.example
@@ -11,9 +11,22 @@ PHX_HOST=localhost
 # Recommended: Association settings
 ASSOCIATION_NAME="Sportsclub XYZ"
 
+# Optional: Admin user (created/updated on container start via Release.seed_admin)
+# In production, set these so the first admin can log in. Change password without redeploy:
+#   bin/mv eval "Mv.Release.seed_admin()"  (with new ADMIN_PASSWORD or ADMIN_PASSWORD_FILE)
+# ADMIN_EMAIL=admin@example.com
+# ADMIN_PASSWORD=secure-password
+# ADMIN_PASSWORD_FILE=/run/secrets/admin_password
+
 # Optional: OIDC Configuration
 # These have defaults in docker-compose.prod.yml, only override if needed
 # OIDC_CLIENT_ID=mv
 # OIDC_BASE_URL=http://localhost:8080/auth/v1
 # OIDC_REDIRECT_URI=http://localhost:4001/auth/user/rauthy/callback
 # OIDC_CLIENT_SECRET=your-rauthy-client-secret
+
+# Optional: OIDC group → Admin role sync (e.g. Authentik groups from profile scope)
+# If OIDC_ADMIN_GROUP_NAME is set, users in that group get Admin role on registration/sign-in.
+# OIDC_GROUPS_CLAIM defaults to "groups" (JWT claim name for group list).
+# OIDC_ADMIN_GROUP_NAME=admin
+# OIDC_GROUPS_CLAIM=groups
diff --git a/docs/admin-bootstrap-and-oidc-role-sync.md b/docs/admin-bootstrap-and-oidc-role-sync.md
new file mode 100644
index 0000000..87dad27
--- /dev/null
+++ b/docs/admin-bootstrap-and-oidc-role-sync.md
@@ -0,0 +1,54 @@
+# Admin Bootstrap and OIDC Role Sync
+
+## Overview
+
+- **Admin bootstrap:** In production, no seeds run. The first admin user is created/updated from environment variables in the Docker entrypoint (after migrate, before server). Password can be changed without redeploy via `bin/mv eval "Mv.Release.seed_admin()"`.
+- **OIDC role sync:** Optional mapping from OIDC groups (e.g. from Authentik profile scope) to the Admin role. Users in the configured admin group get the Admin role on registration and on each sign-in.
+
+## Admin Bootstrap (Part A)
+
+### Environment Variables
+
+- `ADMIN_EMAIL` – Email of the admin user to create/update. If unset, seed_admin/0 does nothing.
+- `ADMIN_PASSWORD` – Password for the admin user. If unset (and no file), no user is created in production.
+- `ADMIN_PASSWORD_FILE` – Path to a file containing the password (e.g. Docker secret).
+
+### Release Task
+
+- `Mv.Release.seed_admin/0` – Reads ADMIN_EMAIL and password from ADMIN_PASSWORD or ADMIN_PASSWORD_FILE. If both are set, creates or updates the user with the Admin role. Idempotent.
+
+### Entrypoint
+
+- rel/overlays/bin/docker-entrypoint.sh – After migrate, runs seed_admin(), then starts the server.
+
+### Seeds (Dev/Test)
+
+- priv/repo/seeds.exs – Uses ADMIN_PASSWORD or ADMIN_PASSWORD_FILE when set; otherwise fallback "testpassword" only in dev/test.
+
+## OIDC Role Sync (Part B)
+
+### Configuration
+
+- `OIDC_ADMIN_GROUP_NAME` – OIDC group name that maps to the Admin role. If unset, no role sync.
+- `OIDC_GROUPS_CLAIM` – JWT claim name for group list (default "groups").
+- Module: Mv.OidcRoleSyncConfig (oidc_admin_group_name/0, oidc_groups_claim/0).
+
+### Sync Logic
+
+- Mv.OidcRoleSync.apply_admin_role_from_user_info(user, user_info) – If admin group configured, sets user role to Admin or Mitglied based on user_info groups.
+
+### Where It Runs
+
+1. Registration: register_with_rauthy after_action calls OidcRoleSync.
+2. Sign-in: sign_in_with_rauthy prepare after_action calls OidcRoleSync for each user.
+
+### Internal Action
+
+- User.set_role_from_oidc_sync – Internal update (role_id only). Used by OidcRoleSync; not exposed.
+
+## See Also
+
+- .env.example – Admin and OIDC group env vars.
+- lib/mv/release.ex – seed_admin/0.
+- lib/mv/oidc_role_sync.ex – Sync implementation.
+- docs/oidc-account-linking.md – OIDC account linking.