CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Sovereign is an Ansible project that deploys a complete self-hosted infrastructure stack for small businesses using Docker and Docker Compose on a single Linux host.

Architecture

Services

Role	Tool	Subdomain
common	Traefik (reverse proxy + TLS)	`traefik.<domain>`
graylog	Graylog + OpenSearch + MongoDB	`logs.<domain>`
authentik	Authentik (identity provider)	`auth.<domain>`
minio	MinIO (object storage)	`s3.<domain>`, `minio.<domain>`
nextcloud	Nextcloud + MariaDB + Redis	`cloud.<domain>`
stalwart	Stalwart Mail (SMTP/IMAP)	`mail.<domain>`
roundcube	Roundcube (webmail)	`webmail.<domain>`
matrix	Synapse + Element	`matrix.<domain>`, `chat.<domain>`
jitsi	Jitsi Meet	`meet.<domain>`
headscale	Headscale (WireGuard mesh VPN)	`headscale.<domain>`
wazuh	Wazuh Manager + Indexer + Dashboard	`wazuh.<domain>`
vaultwarden	Vaultwarden + PostgreSQL	`vault.<domain>`
forgejo	Forgejo + PostgreSQL	`git.<domain>`
uptimekuma	Uptime Kuma (uptime monitoring)	`status.<domain>`
automatisch	Automatisch (workflow automation)	`automate.<domain>`
twenty	Twenty CRM + PostgreSQL + Redis	`crm.<domain>`

Design Principles

Single authentication: All services authenticate via Authentik OIDC/OAuth2
Single config per deployment: All variables live in inventories/production/group_vars/all.yml
Centralized logging: Every container ships logs via GELF UDP to Graylog (graylog_host:12201)
Networking: All services share an external Docker network named sovereign for Traefik routing; each service has its own internal network for db/cache isolation
Deployment order: site.yml deploys Graylog first (logging), then Authentik (auth), then all other services

Tenant Configuration

All deployment variables are in one place: inventories/production/group_vars/all.yml. For a new tenant/deployment, copy this file and update base_domain, passwords, and secrets. All service subdomains derive from base_domain.

Project Structure

sovereign/
├── ansible.cfg
├── requirements.yml              # Ansible Galaxy collections
├── inventories/
│   └── production/
│       ├── hosts.yml
│       └── group_vars/
│           └── all.yml           # ← single tenant config file
├── playbooks/
│   └── site.yml
└── roles/
    └── <service>/
        ├── defaults/main.yml
        ├── handlers/main.yml
        ├── tasks/main.yml
        └── templates/
            ├── docker-compose.yml.j2
            └── ...               # service-specific configs

Each role deploys its Docker Compose stack to /opt/sovereign/<service>/ on the target host.

Common Commands

# Install required Ansible collections
ansible-galaxy collection install -r requirements.yml

# Run a full deployment
ansible-playbook playbooks/site.yml

# Deploy a single service
ansible-playbook playbooks/site.yml --tags authentik

# Dry run
ansible-playbook playbooks/site.yml --check --diff

# Syntax check
ansible-playbook playbooks/site.yml --syntax-check

# Lint
ansible-lint

Environment variables for inventory

export SOVEREIGN_HOST=your-server-ip
export SOVEREIGN_USER=ubuntu
export SOVEREIGN_SSH_KEY=~/.ssh/id_rsa

Initial Setup Notes

Before first deployment, update inventories/production/group_vars/all.yml:

Set base_domain
Replace all changeme_* passwords and secrets with secure values
Generate graylog_root_password_sha2: echo -n yourpassword | sha256sum
Create Authentik OIDC applications for each service that uses SSO (MinIO, Headscale, Vaultwarden, Forgejo) and fill in the changeme_*_oidc_secret placeholders in the respective compose templates
Wazuh requires TLS certificates — see Wazuh Docker documentation for generating certs before first run

4.1 KiB Raw Blame History