init

2026-03-14 05:38:45 +01:00 · 2026-03-14 05:38:45 +01:00 · 883f31932e
commit 883f31932e
169 changed files with 5676 additions and 0 deletions
--- a/README.md
+++ b/README.md
@ -0,0 +1,107 @@
+# servers
+
+Homelab infrastructure managed with Ansible and tested against local QEMU VMs.
+Two production VPS hosts (proxy and IDP) are connected via WireGuard and run
+everything behind Apache reverse proxies with Let's Encrypt TLS.
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────┐
+│  Proxy (10.0.0.1)                               │
+│  ┌───────────┐ ┌──────────┐ ┌────────────────┐  │
+│  │  Apache    │ │ Prosody  │ │ Docker Registry│  │
+│  │  (reverse  │ │ (XMPP)  │ │ (pull-through) │  │
+│  │   proxy)   │ │          │ │                │  │
+│  ├───────────┤ ├──────────┤ ├────────────────┤  │
+│  │ ConverseJS│ │ Bugzilla │ │  Comentario    │  │
+│  │ Kellnr    │ │ DevPI    │ │  dnsmasq       │  │
+│  └───────────┘ └──────────┘ └────────────────┘  │
+│  WireGuard ─────────────────────────┐            │
+└─────────────────────────────────────┼────────────┘
+                                      │
+┌─────────────────────────────────────┼────────────┐
+│  IDP (10.0.0.2)                     │            │
+│  ┌──────────────────────────────────┘            │
+│  │  Authentik (identity provider)                │
+│  │  PostgreSQL + Redis                           │
+│  └───────────────────────────────────────────────┘
+└──────────────────────────────────────────────────┘
+```
+
+Clients (phone, workstation) connect over WireGuard and resolve names via
+dnsmasq on the proxy.
+
+## Quick start
+
+```bash
+# Install Python dependencies
+pipenv install
+
+# Install Ansible collection dependencies
+pipenv run ansible-galaxy collection install -r ansible/requirements.yml
+
+# Deploy to production
+pipenv run ansible-playbook -i ansible/inventories/prod/hosts.ini ansible/playbooks/setup.yml
+
+# Deploy a single service (e.g. bugzilla)
+pipenv run ansible-playbook -i ansible/inventories/prod/hosts.ini ansible/playbooks/setup.yml --tags bugzilla
+
+# Deploy a service without its dependencies
+pipenv run ansible-playbook -i ansible/inventories/prod/hosts.ini ansible/playbooks/setup.yml --tags bugzilla --skip-tags docker,apache
+```
+
+See [DEVELOPMENT.md](DEVELOPMENT.md) for the full local development workflow.
+
+## Available tags
+
+| Tag | What it deploys | Host |
+|-----|----------------|------|
+| `host` | Base host config (SSH keys, users, swap) | all |
+| `docker` | Docker engine + registry mirrors | docker_hosts |
+| `wireguard` | WireGuard tunnels | proxy, idp |
+| `apache` | Apache + Let's Encrypt certs | proxy |
+| `dnsmasq` | DNS resolver | proxy |
+| `docker-registry` | Pull-through registry mirrors | proxy |
+| `restic` | Backup infrastructure | proxy, idp |
+| `prosody` | XMPP server + upload proxy | proxy |
+| `conversejs` | Web XMPP client | proxy |
+| `kellnr` | Rust crate registry | proxy |
+| `devpi` | Python package index | proxy |
+| `comentario` | Comment system | proxy |
+| `bugzilla` | Bug tracker | proxy |
+| `authentik` | Identity provider + reverse proxy | idp, proxy |
+| `blog` | Static blog site | proxy |
+| `spec` | Static spec site | proxy |
+
+## Backups
+
+```bash
+# Run backup
+pipenv run ansible-playbook -i ansible/inventories/prod/hosts.ini ansible/playbooks/backup.yml
+
+# Restore
+pipenv run ansible-playbook -i ansible/inventories/prod/hosts.ini ansible/playbooks/restore.yml
+```
+
+Automated backups run via systemd timer (bi-weekly by default).
+
+## Vault
+
+Sensitive variables live in `ansible/inventories/prod/group_vars/all/vault.yml`,
+encrypted with `ansible-vault`. The vault password file is `.vault-pass`
+(not committed).
+
+```bash
+# Edit vault
+pipenv run ansible-vault edit ansible/inventories/prod/group_vars/all/vault.yml
+```
+
+## Authentik notes
+
+App passwords with more than 30 minutes expiration require a user or group
+attribute:
+
+```
+goauthentik.io/user/token-maximum-lifetime: days=365
+```