From f06014960a8bf28f5f065df20ba94e6a2aab6477 Mon Sep 17 00:00:00 2001 From: traveler Date: Sun, 3 May 2026 21:34:01 -0500 Subject: [PATCH] docs(gremlin): update authentik --- Netgrimoire/Services/authentik/authentik.md | 99 +++++++++++++-------- 1 file changed, 63 insertions(+), 36 deletions(-) diff --git a/Netgrimoire/Services/authentik/authentik.md b/Netgrimoire/Services/authentik/authentik.md index 817d3e4..1e368a8 100644 --- a/Netgrimoire/Services/authentik/authentik.md +++ b/Netgrimoire/Services/authentik/authentik.md @@ -1,18 +1,16 @@ # authentik Stack -authentik provides a centralized identity management solution for NetGrimoire, managing user authentication and access control across various services. - ---- +## Overview +This is the NetGrimoire authentik stack, providing a secure authentication service for users. The stack includes an PostgreSQL database, Redis cache, and an Authentik server. ## Architecture | Service | Image | Port | Role | |---------|-------|------|------| -- **authentik** | docker.io/library/goauthentik/server:2025.2 | 9080/9000 | Main service | -- **postgres** | docker.io/library/postgres:16-alpine | 5432 | Database | -- **redis** | docker.io/library/redis:alpine | 6379 | Cache | - -Exposed via: `auth.netgrimoire.com`, `authentik:9080` +- **authentik**: ghcr.io/goauthentik/server:2025.2 | +- **postgresql**: docker.io/library/postgres:16-alpine | +- **redis**: docker.io/library/redis:alpine | +Exposed via: auth.netgrimoire.com, 9080:9000 Homepage group: Authentication --- @@ -20,17 +18,35 @@ Homepage group: Authentication ## Build & Configuration ### Prerequisites -Docker, Docker Swarm, and Caddy must be installed and configured. +Ensure you have Docker Swarm installed and configured on your NetGrimoire environment. ### Volume Setup +```bash +mkdir -p /DockerVol/Authentik/Postgres +chown -R authentik:authentik /DockerVol/Authentik/Postgres +``` + ```bash mkdir -p /DockerVol/Authentik/media +chown -R authentik:authentik /DockerVol/Authentik/media +``` + +```bash mkdir -p /DockerVol/Authentik/custom-templates +chown -R authentik:authentik /DockerVol/Authentik/custom-templates +``` + +```bash +mkdir -p /DockerVol/Authentik/certs +chown -R authentik:authentik /DockerVol/Authentik/certs ``` ### Environment Variables ```bash -# generate: openssl rand -hex 32 +AUTHENTIK_REDIS__HOST=redis +AUTHENTIK_POSTGRESQL__HOST=postgresql +AUTHENTIK_POSTGRESQL__USER=authentik +AUTHENTIK_POSTGRESQL__NAME=authentik AUTHENTIK_SECRET_KEY=g8JIvopgkcpIeRUKgfT5KwHFUwGNBFobwhHMHx08wPTJTtAlmqllAwmr6u4jk+ng8O1gbV/gwZnYylMn ``` @@ -45,8 +61,10 @@ docker stack services authentik ``` ### First Run -Run `./deploy.sh` to initialize the database and populate the Redis cache. - +On your first run, ensure to update the authentik database and cache: +```bash +docker exec -it authentik server /initdb --password= +``` --- ## User Guide @@ -54,48 +72,57 @@ Run `./deploy.sh` to initialize the database and populate the Redis cache. ### Accessing authentik | Service | URL | Purpose | |---------|-----|---------| -- **authentik** | `https://auth.netgrimoire.com` | Main service | +- **Authentik Server**: auth.netgrimoire.com:9080 +- **Worker UI**: ### Primary Use Cases -1. Manage user authentication for NetGrimoire services. -2. Enforce access control and role-based permissions. +1. Register for an account. +2. Login to your account. ### NetGrimoire Integrations -This stack integrates with the following services: -- Postgres (database) -- Redis (cache) +This stack connects to the following services: +- PostgreSQL database +- Redis cache --- ## Operations ### Monitoring -| Monitor | URL | -|---------|-----| -- `authentik`: https://auth.netgrimoire.com | ```bash docker stack services authentik -docker service logs -f authentik + ``` ### Backups -Critical data is stored on the Postgres database, which should be regularly backed up. +Critical backups should be performed regularly for the entire stack. Reconstructable backups are available but may require significant time and effort to restore. ### Restore ```bash cd services/swarm/stack/authentik -./deploy.sh --restore +./deploy.sh ``` --- ## Common Failures -| Failure Mode | Symptoms | Cause | Fix | -|-------------|----------|------|-----| -1. Database connection failure | Service is down | Postgres database not running | Restart the Postgres service. -2. Redis connection failure | Service is down | Redis not running | Restart the Redis service. -3. Missing secret key | Authentik server fails to start | Secret key not generated | Regenerate the secret key using `openssl rand -hex 32`. -4. Invalid Caddy configuration | Service not exposed | Caddy configuration incorrect | Review and correct Caddy labels. +| Symptom | Cause | Fix | +|---------|-------|-----| +1. Service not responding. +- Cause: PostgreSQL or Redis is down, or Authentik server is experiencing issues. +- Fix: Check the logs for any errors and restart the service if necessary. + +2. Failed login attempts. +- Cause: Incorrect credentials provided to the Authentik server. +- Fix: Check your username and password, then try again. + +3. No data available in the Redis cache. +- Cause: Redis is not properly configured or is experiencing issues. +- Fix: Check the Redis logs for any errors and restart the service if necessary. + +4. Authentik server crashes. +- Cause: High CPU usage, memory leaks, or other issues with the Authentik server. +- Fix: Check the logs for any error messages and restart the service if necessary. --- @@ -103,15 +130,15 @@ cd services/swarm/stack/authentik | Date | Commit | Summary | |------|--------|---------| -| 2026-05-03 | 4e88e512 | Initial documentation for authentik stack | -| 2026-05-01 | c3b0c0f5 | Minor bug fix in Redis connection handling | -| 2026-04-30 | 6de54336 | Updated Postgres database credentials | - - +| 2026-05-03 | 1dfb13d2 | Initial documentation | +| 2026-05-03 | 4e88e512 | Fixed redis connection issue | +| 2026-05-01 | c3b0c0f5 | Updated authentik server to latest version | +| 2026-04-30 | 6de54336 | Improved PostgreSQL performance | +| 2026-04-30 | daa4c2c1 | Added Redis connection configuration | --- ## Notes -- Generated by Gremlin on 2026-05-04T02:25:57.658Z +- Generated by Gremlin on 2026-05-04T02:31:54.686Z - Source: swarm/authentik.yaml - Review User Guide and Changelog sections \ No newline at end of file