From b7fe98414796322fb8af3bc8b05c03a45c85d030 Mon Sep 17 00:00:00 2001 From: Ian Roddis <31021769+iroddis@users.noreply.github.com> Date: Sat, 2 May 2026 09:22:36 -0300 Subject: [PATCH] Updating documentation --- CLAUDE.md | 3 +++ README.md | 55 +++++++++++++++++++++++++++++++++++++++++++++++++++---- 2 files changed, 54 insertions(+), 4 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 4c41e0d..e26782b 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -25,6 +25,9 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co | wazuh | Wazuh Manager + Indexer + Dashboard | `wazuh.` | | vaultwarden | Vaultwarden + PostgreSQL | `vault.` | | forgejo | Forgejo + PostgreSQL | `git.` | +| uptimekuma | Uptime Kuma (uptime monitoring) | `status.` | +| automatisch | Automatisch (workflow automation) | `automate.` | +| twenty | Twenty CRM + PostgreSQL + Redis | `crm.` | ### Design Principles diff --git a/README.md b/README.md index 18efff1..3ce8b08 100644 --- a/README.md +++ b/README.md @@ -34,6 +34,9 @@ Sovereign is an Ansible project that deploys a complete self-hosted infrastructu | `wazuh` | Wazuh Manager + Indexer + Dashboard | `wazuh.` | | `vaultwarden` | Vaultwarden + PostgreSQL | `vault.` | | `forgejo` | Forgejo + PostgreSQL | `git.` | +| `uptimekuma` | Uptime Kuma (uptime monitoring) | `status.` | +| `automatisch` | Automatisch (workflow automation) | `automate.` | +| `twenty` | Twenty CRM + PostgreSQL + Redis | `crm.` | | `website` | Nginx (static website) | `` | --- @@ -186,14 +189,26 @@ Stalwart generates its DKIM signing key on first start. After Stalwart is runnin Log into Authentik at `https://auth.` and create an OAuth2/OIDC provider and application for each service that integrates with SSO. Then fill in the `changeme_*_oidc_secret` placeholders in the relevant compose templates under `roles//templates/`. -Services that require Authentik OIDC configuration: +Services that use native OIDC — create an OAuth2/OIDC provider in Authentik for each, then set the corresponding variable in `all.yml`: -| Service | Template variable | -|---------|------------------| +| Service | `all.yml` variable | +|---------|-------------------| | MinIO | `changeme_minio_oidc_secret` | | Headscale | `changeme_headscale_oidc_secret` | | Vaultwarden | `changeme_vaultwarden_oidc_secret` | | Forgejo | `changeme_forgejo_oidc_secret` | +| Twenty CRM | `twenty_oidc_client_secret` | + +For Twenty CRM, after setting the variable and redeploying the role, also configure the provider inside the app: **Settings → Security → SSO → Add provider**, using the discovery URL `https://auth./application/o/twenty/.well-known/openid-configuration`. + +Services that use Authentik **forward auth** (no native OIDC) — create a **Proxy Provider** in Forward Auth mode for each, create an Application bound to it, and add it to the embedded outpost: + +| Service | External host | +|---------|--------------| +| Uptime Kuma | `https://status.` | +| Automatisch | `https://automate.` | + +With the embedded outpost running, Traefik will redirect unauthenticated requests to the Authentik login page automatically — no further role changes are needed. #### Wazuh TLS certificates @@ -404,6 +419,38 @@ The DNS role publishes the following records for ``: | `forgejo_admin_email` | `admin@` | Initial admin email. | | `forgejo_ssh_port` | `2222` | Host port for Forgejo SSH access. Must be open in the firewall. | +### Uptime Kuma + +| Variable | Default | Description | +|----------|---------|-------------| +| `uptimekuma_domain` | `status.` | Uptime Kuma dashboard URL. | +| `uptimekuma_version` | `1` | Uptime Kuma image tag (`1` tracks the latest v1 release). | + +Access is controlled entirely by Authentik forward auth — Uptime Kuma's own account system is not used. After deployment, add monitors for each service subdomain via the web UI. + +### Automatisch + +| Variable | Default | Description | +|----------|---------|-------------| +| `automatisch_domain` | `automate.` | Automatisch URL. | +| `automatisch_version` | `latest` | Automatisch image tag. | +| `automatisch_db_password` | — | PostgreSQL password for Automatisch's database. | +| `automatisch_encryption_key` | — | Encrypts stored integration credentials. Generate with `openssl rand -base64 36`. **Never rotate after first deployment** — doing so breaks all existing connections. | +| `automatisch_webhook_secret_key` | — | Verifies incoming webhook requests. Same rotation warning applies. | +| `automatisch_app_secret_key` | — | Used for user session signing. Same rotation warning applies. | + +Access is controlled by Authentik forward auth. + +### Twenty CRM + +| Variable | Default | Description | +|----------|---------|-------------| +| `twenty_domain` | `crm.` | Twenty CRM URL. | +| `twenty_version` | `latest` | Twenty image tag. | +| `twenty_app_secret` | — | Random secret for JWT signing. Generate with `openssl rand -base64 36`. | +| `twenty_db_password` | — | PostgreSQL password for Twenty's database. | +| `twenty_oidc_client_secret` | — | OIDC client secret from the Authentik OAuth2 application. | + ### Website | Variable | Default | Description | @@ -456,7 +503,7 @@ ansible-playbook playbooks/site.yml --tags nextcloud ansible-playbook playbooks/site.yml --tags website ``` -Available tags: `common`, `dns`, `graylog`, `authentik`, `minio`, `nextcloud`, `stalwart`, `roundcube`, `matrix`, `jitsi`, `headscale`, `wazuh`, `vaultwarden`, `forgejo`, `website`. +Available tags: `common`, `dns`, `graylog`, `authentik`, `minio`, `nextcloud`, `stalwart`, `roundcube`, `matrix`, `jitsi`, `headscale`, `wazuh`, `vaultwarden`, `forgejo`, `uptimekuma`, `automatisch`, `twenty`, `website`. ### Dry run