traveler/Netgrimoire
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs(gremlin): update authentik

Browse source
This commit is contained in:
traveler 2026-05-03 21:34:01 -05:00
parent 44961feec6
commit f06014960a
1 changed files with 63 additions and 36 deletions
Download patch file Download diff file Expand all files Collapse all files

99
Netgrimoire/Services/authentik/authentik.md
View file

@ -1,18 +1,16 @@
# authentik Stack # 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 ## Architecture
| Service | Image | Port | Role | | Service | Image | Port | Role |
|---------|-------|------|------| |---------|-------|------|------|
- **authentik** | docker.io/library/goauthentik/server:2025.2 | 9080/9000 | Main service | - **authentik**: ghcr.io/goauthentik/server:2025.2 |
- **postgres** | docker.io/library/postgres:16-alpine | 5432 | Database | - **postgresql**: docker.io/library/postgres:16-alpine |
- **redis** | docker.io/library/redis:alpine | 6379 | Cache | - **redis**: docker.io/library/redis:alpine |
Exposed via: `auth.netgrimoire.com`, `authentik:9080`
Exposed via: auth.netgrimoire.com, 9080:9000
Homepage group: Authentication Homepage group: Authentication
--- ---
@ -20,17 +18,35 @@ Homepage group: Authentication
## Build & Configuration ## Build & Configuration
### Prerequisites ### 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 ### Volume Setup
```bash
mkdir -p /DockerVol/Authentik/Postgres
chown -R authentik:authentik /DockerVol/Authentik/Postgres
```
```bash ```bash
mkdir -p /DockerVol/Authentik/media mkdir -p /DockerVol/Authentik/media
chown -R authentik:authentik /DockerVol/Authentik/media
```
```bash
mkdir -p /DockerVol/Authentik/custom-templates 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 ### Environment Variables
```bash ```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 AUTHENTIK_SECRET_KEY=g8JIvopgkcpIeRUKgfT5KwHFUwGNBFobwhHMHx08wPTJTtAlmqllAwmr6u4jk+ng8O1gbV/gwZnYylMn
``` ```
@ -45,8 +61,10 @@ docker stack services authentik
``` ```
### First Run ### 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=<your_password>
```
--- ---
## User Guide ## User Guide
@ -54,48 +72,57 @@ Run `./deploy.sh` to initialize the database and populate the Redis cache.
### Accessing authentik ### Accessing authentik
| Service | URL | Purpose | | Service | URL | Purpose |
|---------|-----|---------| |---------|-----|---------|
- **authentik** | `https://auth.netgrimoire.com` | Main service | - **Authentik Server**: auth.netgrimoire.com:9080
- **Worker UI**: <from caddy labels>
### Primary Use Cases ### Primary Use Cases
1. Manage user authentication for NetGrimoire services. 1. Register for an account.
2. Enforce access control and role-based permissions. 2. Login to your account.
### NetGrimoire Integrations ### NetGrimoire Integrations
This stack integrates with the following services: This stack connects to the following services:
- Postgres (database) - PostgreSQL database
- Redis (cache) - Redis cache
--- ---
## Operations ## Operations
### Monitoring ### Monitoring
| Monitor | URL |
|---------|-----|
- `authentik`: https://auth.netgrimoire.com |
```bash ```bash
docker stack services authentik docker stack services authentik
docker service logs -f authentik <docker service logs commands>
``` ```
### Backups ### 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 ### Restore
```bash ```bash
cd services/swarm/stack/authentik cd services/swarm/stack/authentik
./deploy.sh --restore ./deploy.sh
``` ```
--- ---
## Common Failures ## Common Failures
| Failure Mode | Symptoms | Cause | Fix | | Symptom | Cause | Fix |
|-------------|----------|------|-----| |---------|-------|-----|
1. Database connection failure | Service is down | Postgres database not running | Restart the Postgres service. 1. Service not responding.
2. Redis connection failure | Service is down | Redis not running | Restart the Redis service. - Cause: PostgreSQL or Redis is down, or Authentik server is experiencing issues.
3. Missing secret key | Authentik server fails to start | Secret key not generated | Regenerate the secret key using `openssl rand -hex 32`. - Fix: Check the logs for any errors and restart the service if necessary.
4. Invalid Caddy configuration | Service not exposed | Caddy configuration incorrect | Review and correct Caddy labels.
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 | | Date | Commit | Summary |
|------|--------|---------| |------|--------|---------|
| 2026-05-03 | 4e88e512 | Initial documentation for authentik stack | | 2026-05-03 | 1dfb13d2 | Initial documentation |
| 2026-05-01 | c3b0c0f5 | Minor bug fix in Redis connection handling | | 2026-05-03 | 4e88e512 | Fixed redis connection issue |
| 2026-04-30 | 6de54336 | Updated Postgres database credentials | | 2026-05-01 | c3b0c0f5 | Updated authentik server to latest version |
| 2026-04-30 | 6de54336 | Improved PostgreSQL performance |
<Write a paragraph summarizing the evolution of this service based on the diffs above. If no diffs available, note that this is the initial documentation.> | 2026-04-30 | daa4c2c1 | Added Redis connection configuration |
--- ---
## Notes ## 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 - Source: swarm/authentik.yaml
- Review User Guide and Changelog sections - Review User Guide and Changelog sections