famapp/deploy/authentik/README.md

Authentik — manual bootstrap

Run these steps once after the first docker compose up -d in the deploy/ directory.

---

1. Set the admin password

Visit https://auth.yourdomain.com/if/flow/initial-setup/ and set the akadmin password.

---

2. Create the OIDC provider

1. Log in to the Authentik Admin UI at https://auth.yourdomain.com/if/admin/.
2. Go to Applications → Providers → Create.
3. Choose OAuth2/OpenID Provider.
4. Configure:
   • Name: famapp
   • Authorization flow: default-provider-authorization-explicit-consent
   • Client type: Confidential
   • Client ID: (auto-generated — copy this)
   • Client Secret: (auto-generated — copy this)
   • Redirect URIs: https://fam.yourdomain.com/api/auth/callback/authentik
   • Signing Key: authentik Self-signed Certificate
   • Token validity: 24 hours (or your preference)
5. Save and note the Issuer URL shown on the provider detail page.

The issuer URL will look like:

https://auth.yourdomain.com/application/o/famapp/

Set this (and the client ID/secret) in famapp's .env / production secrets:

AUTH_OIDC_ISSUER=https://auth.yourdomain.com/application/o/famapp/
AUTH_OIDC_CLIENT_ID=<client-id>
AUTH_OIDC_CLIENT_SECRET=<client-secret>

---

3. Create the Application

1. Go to Applications → Applications → Create.
2. Configure:
   • Name: famapp
   • Slug: famapp
   • Provider: select the famapp provider created above
   • Launch URL: https://fam.yourdomain.com
3. Save.

---

4. Create user accounts

1. Go to Directory → Users → Create.
2. Create accounts for Matt and wife. Recommended fields:
   • Username / Email: use real email addresses (famapp uses email as the identity key)
   • Name: display name shown in the app
3. Optionally invite them via email to set their own passwords.

---

5. Set up passkeys (optional but recommended)

Each user can enroll a passkey from their Authentik profile:

1. Sign in as the user at https://auth.yourdomain.com.
2. Go to Settings → MFA Devices → Add → WebAuthn Device.
3. Follow the browser prompt to register a Touch ID / Face ID / hardware key.

---

6. Generate AUTH_SECRET

Run this locally and put the output in your .env / production secrets:

openssl rand -base64 32

---

Notes

• The Authentik image in compose.yaml is currently pinned to latest. Before production, pin to a specific version tag (e.g. ghcr.io/goauthentik/server:2024.12.3).
• famapp uses database sessions (Auth.js). Sessions are stored in the sessions table and expire according to Auth.js defaults (30 days).
• The forward-auth / Outpost wiring for other services (Sonarr, Radarr, etc.) is a separate future task.