Ian Roddis
109 lines
4.2 KiB
Markdown
109 lines
4.2 KiB
Markdown
# 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 | Service | URL |
|
|
|------|---------|-----|
|
|
| common | Traefik (reverse proxy + TLS) | `traefik.<domain>` |
|
|
| dns | BIND9 (authoritative nameserver) | `ns1.<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>` |
|
|
| website | Nginx (static website) | `<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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
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`:
|
|
1. Set `base_domain`
|
|
2. Replace all `changeme_*` passwords and secrets with secure values
|
|
3. Generate `graylog_root_password_sha2`: `echo -n yourpassword | sha256sum`
|
|
4. 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
|
|
5. Wazuh requires TLS certificates — see Wazuh Docker documentation for generating certs before first run
|