add comprehensive documentation for all Ansible roles

- Add main README with infrastructure overview and usage instructions
- Document bootstrap role for server initialization and security hardening
- Document common role for shared server configuration
- Document cron role for scheduled tasks and automation
- Document docker role with detailed service descriptions and deployment patterns
- Include MMDL service documentation with setup requirements
- Add troubleshooting guides and security considerations

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

README.md

@@ -0,0 +1,131 @@
+# Personal Infrastructure Ansible Playbook
+
+This Ansible playbook automates the setup and management of a personal self-hosted infrastructure running Docker containers for various services.
+
+## Overview
+
+The playbook manages two main environments:
+- **Bootstrap server** (`netcup`): Initial server setup with Tailscale VPN
+- **Docker server** (`docker-01`): Main application server running containerized services
+
+## Services Deployed
+
+The Docker role deploys and manages the following self-hosted services:
+
+- **Authentication**: Authentik (SSO/Identity Provider)
+- **Media**: Audiobookshelf, Calibre, Pinchflat
+- **Productivity**: Ghost blog, Gitea, Code Server, Grist, TasksMD, Stirling PDF, MMDL (Task Management)
+- **Communication**: GoToSocial, Matrix (Conduit)
+- **File Management**: Hoarder, Paperless-NGX, Syncthing, Manyfold
+- **Monitoring**: Changedetection, Glance dashboard, Dawarich location tracking
+- **Utilities**: Baikal (CalDAV/CardDAV), HeyForm, Pingvin Share, Pinry
+- **Notifications**: Apprise API
+- **Reverse Proxy**: Caddy
+
+## Structure
+
+```
+├── site.yml           # Main playbook
+├── bootstrap.yml      # Server bootstrap playbook
+├── dns.yml           # AWS Route53 DNS management
+├── hosts.yml         # Inventory file
+├── requirements.yml  # External role dependencies
+└── roles/
+    ├── bootstrap/    # Initial server setup
+    ├── common/       # Common server configuration
+    ├── cron/         # Scheduled tasks
+    └── docker/       # Docker services deployment
+```
+
+## Roles Documentation
+
+Each role has detailed documentation in its respective directory:
+
+### [Bootstrap Role](roles/bootstrap/README.md)
+Performs initial server setup and hardening:
+- Creates user accounts with SSH key authentication
+- Configures passwordless sudo and security hardening
+- Installs essential packages and configures UFW firewall
+- Sets up Tailscale VPN for secure network access
+
+### [Common Role](roles/common/README.md)
+Provides shared configuration for all servers:
+- Installs common packages (aptitude)
+- Enables UFW firewall with default deny policy
+- Ensures consistent base configuration across infrastructure
+
+### [Cron Role](roles/cron/README.md)
+Manages scheduled tasks and automation:
+- **Warhammer RSS Feed Updater**: Daily job that generates and updates RSS feeds
+- Integrates with Docker services for content generation
+- Supports easy addition of new scheduled tasks
+
+### [Docker Role](roles/docker/README.md)
+The most comprehensive role, deploying 25+ containerized services:
+- **Core Infrastructure**: Caddy reverse proxy, Authentik SSO, Dockge management
+- **Development Tools**: Gitea, Code Server, Matrix communication
+- **Media Management**: Audiobookshelf, Calibre, Ghost blog
+- **Productivity**: Paperless-NGX, Baikal calendar, Glance dashboard
+- **Security Features**: Centralized authentication, network isolation, container hardening
+- **Monitoring**: Comprehensive service health monitoring and alerting
+
+## Usage
+
+### Prerequisites
+
+1. Install Ansible and required collections:
+   ```bash
+   ansible-galaxy install -r requirements.yml
+   ```
+
+2. Configure your inventory in `hosts.yml` with your server details
+
+### Bootstrap a New Server
+
+```bash
+ansible-playbook bootstrap.yml -i hosts.yml
+```
+
+This will:
+- Create a user account
+- Install and configure Tailscale VPN
+- Set up basic security
+
+### Deploy Docker Services
+
+```bash
+ansible-playbook site.yml -i hosts.yml
+```
+
+Or deploy specific services using tags:
+```bash
+# Deploy only Caddy reverse proxy
+ansible-playbook site.yml -i hosts.yml --tags caddy
+
+# Deploy authentication services
+ansible-playbook site.yml -i hosts.yml --tags authentik
+
+# Deploy task management
+ansible-playbook site.yml -i hosts.yml --tags mmdl
+```
+
+### Manage DNS Records
+
+```bash
+ansible-playbook dns.yml -i hosts.yml
+```
+
+Updates AWS Route53 DNS records for configured domains (`thesatelliteoflove.com` and `nerder.land`).
+
+## Configuration
+
+- Service configurations are templated in `roles/docker/templates/`
+- Environment variables and secrets should be managed through Ansible Vault
+- Docker Compose files are generated from Jinja2 templates
+
+## Security Notes
+
+- Uses Tailscale for secure network access
+- Caddy provides automatic HTTPS with Let's Encrypt
+- Services are containerized for isolation
+- UFW firewall rules are managed via Docker integration

dns.yml

@@ -41,6 +41,8 @@
             ip: "152.53.36.98"
           - name: models
             ip: "152.53.36.98"
+          - name: tasks
+            ip: "152.53.36.98"
       - name: nerder.land
         dns_records:
           - name: "forms"

roles/bootstrap/README.md

@@ -0,0 +1,41 @@
+# Bootstrap Role
+
+## Purpose
+Performs initial server setup and hardening for new Ubuntu/Debian servers.
+
+## What It Does
+
+### User Management
+- Creates a new user account with sudo privileges (specified by `created_username` variable)
+- Configures passwordless sudo for the sudo group
+- Sets up SSH key authentication using your local `~/.ssh/id_ed25519.pub` key
+- Disables root password authentication
+
+### System Packages
+- Installs `aptitude` for better package management
+- Installs essential packages:
+  - `curl` - HTTP client
+  - `vim` - Text editor
+  - `git` - Version control
+  - `ufw` - Uncomplicated Firewall
+
+### Security Configuration
+- Configures UFW firewall to:
+  - Allow SSH connections
+  - Enable firewall with default deny policy
+- Hardens SSH configuration
+
+## Variables Required
+- `created_username`: The username to create (typically set in bootstrap.yml)
+- `tailscale_key`: Tailscale authentication key (prompted during playbook run)
+
+## Dependencies
+- Requires the `artis3n.tailscale` role for VPN setup
+- Requires your SSH public key at `~/.ssh/id_ed25519.pub`
+
+## Usage
+```bash
+ansible-playbook bootstrap.yml -i hosts.yml
+```
+
+This role is designed to be run once on a fresh server before deploying other services.

roles/common/README.md

@@ -0,0 +1,23 @@
+# Common Role
+
+## Purpose
+Provides shared configuration and security setup that applies to all servers in the infrastructure.
+
+## What It Does
+
+### System Packages
+- Installs `aptitude` for better package management and dependency resolution
+- Updates package cache to ensure latest package information
+
+### Security Configuration
+- Enables UFW (Uncomplicated Firewall) with default deny policy
+- Provides baseline firewall protection for all managed servers
+
+## Usage
+This role is automatically applied to all servers in the infrastructure as part of the main site.yml playbook. It ensures consistent base configuration across all managed systems.
+
+## Dependencies
+None - this is a foundational role that other roles can depend on.
+
+## Notes
+This role is designed to be lightweight and provide only the most essential common functionality. Server-specific configurations should be handled by dedicated roles like `docker` or `bootstrap`.

roles/cron/README.md

@@ -0,0 +1,37 @@
+# Cron Role
+
+## Purpose
+Manages scheduled tasks and automated maintenance jobs for the infrastructure.
+
+## What It Does
+
+### Warhammer RSS Feed Updater
+- Copies `update_warhammer_feed.sh` script to `/usr/local/bin/` with executable permissions
+- Creates a daily cron job that runs at 09:10 AM
+- The script performs these actions:
+  1. Creates a temporary directory `/tmp/warhammer_feed`
+  2. Runs a custom Docker container (`git.thesatelliteoflove.com/phil/rss-warhammer`) to generate RSS feed
+  3. Copies the generated `warhammer_rss_feed.xml` to `/opt/stacks/caddy/site/tsol/feeds/`
+  4. Restarts the Glance dashboard stack to reflect the updated feed
+
+## Files Managed
+- `/usr/local/bin/update_warhammer_feed.sh` - RSS feed update script
+- Cron job: "Update Warhammer RSS Feed" (daily at 09:10)
+
+## Dependencies
+- Requires Docker to be installed and running
+- Depends on the following Docker stacks being deployed:
+  - Custom RSS generator container at `git.thesatelliteoflove.com/phil/rss-warhammer`
+  - Caddy web server stack at `/opt/stacks/caddy/`
+  - Glance dashboard stack at `/opt/stacks/glance/`
+
+## Usage
+This role is automatically applied as part of the main site.yml playbook with the `cron` tag.
+
+```bash
+# Deploy only cron jobs
+ansible-playbook site.yml -i hosts.yml --tags cron
+```
+
+## Customization
+To add additional cron jobs, create new tasks in the main.yml file following the same pattern as the Warhammer feed updater.

roles/docker/README.md

@@ -0,0 +1,202 @@
+# Docker Role
+
+## Purpose
+Deploys and manages a comprehensive self-hosted infrastructure with 25+ containerized services, transforming a server into a personal cloud platform with authentication, media management, productivity tools, and development services.
+
+## Architecture Overview
+
+### Network Configuration
+- **External Network**: All services connect to shared `lava` network (172.20.0.0/24)
+- **Reverse Proxy**: Caddy handles all ingress traffic with automatic HTTPS
+- **Service Discovery**: Container-to-container communication using service names
+- **Firewall Integration**: UFW-Docker script properly configures firewall rules
+
+### Security Features
+- **Centralized SSO**: Authentik provides OIDC authentication for most services
+- **Network Isolation**: Services restricted to appropriate network segments
+- **Container Hardening**: Non-root users, capability dropping, security options
+- **Secret Management**: Ansible vault for sensitive configuration
+
+## Services Deployed
+
+### Core Infrastructure
+- **Caddy** - Reverse proxy with automatic HTTPS (static IP: 172.20.0.5)
+- **Dockge** - Docker compose stack management UI
+- **Authentik** - Enterprise authentication server (OIDC/SAML SSO)
+
+### Development & Code Management
+- **Gitea** - Self-hosted Git with CI/CD runners
+- **Code Server** - VS Code in the browser
+- **Conduit** - Matrix homeserver for communication
+
+### Media & Content Management
+- **Audiobookshelf** - Audiobook and podcast server
+- **Calibre** - E-book management and conversion
+- **Ghost** - Modern blogging platform
+- **Hoarder** - Bookmark management with AI tagging
+- **Pinry** - Pinterest-like image board
+- **Pingvin Share** - File sharing service
+- **Syncthing** - Decentralized file sync
+
+### Productivity & Organization
+- **Paperless-ngx** - Document management with OCR
+- **Baikal** - CalDAV/CardDAV server
+- **Glance** - Customizable dashboard with monitoring
+- **Heyform** - Form builder and surveys
+- **Postiz** - Social media management
+- **Dawarich** - Location tracking
+- **Change Detection** - Website monitoring
+- **Manyfold** - 3D model file organization
+- **MMDL** - Task and calendar management with CalDAV integration
+
+### Utilities & Tools
+- **Stirling PDF** - PDF manipulation (internal network only)
+- **Pinchflat** - YouTube video archiving
+- **Apprise API** - Unified notifications
+- **GoToSocial** - Lightweight ActivityPub server
+
+## Deployment Patterns
+
+### Standardized Service Deployment
+Each service follows a consistent pattern:
+1. Creates `/opt/stacks/[service-name]` directory structure
+2. Generates Docker Compose file from Jinja2 template
+3. Deploys using `community.docker.docker_compose_v2`
+4. Configures environment variables from vault secrets
+
+### Template System
+- **Compose Templates**: `.j2` files in `templates/` for dynamic configuration
+- **Environment Templates**: Separate `.env.j2` files for services requiring environment variables
+- **Variable Substitution**: Uses Ansible vault variables for secrets and configuration
+
+## Shell Environment Setup
+The role also configures the shell environment:
+- **Zsh Installation**: Sets zsh as default shell
+- **Atuin**: Command history sync and search
+- **Bat**: Enhanced `cat` command with syntax highlighting
+
+## File Organization
+```
+roles/docker/
+├── tasks/
+│   ├── main.yml              # Orchestrates all deployments
+│   ├── shell.yml             # Shell environment setup
+│   ├── caddy.yml             # Reverse proxy
+│   ├── authentik.yml         # Authentication
+│   ├── mmdl.yml              # Task management
+│   └── [25+ service files]   # Individual service deployments
+├── templates/
+│   ├── [service]-compose.yml.j2  # Docker Compose templates
+│   ├── [service]-env.j2          # Environment variable templates
+│   └── mmdl-*.j2                 # MMDL-specific templates
+├── files/
+│   ├── Caddyfile             # Caddy configuration
+│   ├── ufw-docker.sh         # Firewall integration script
+│   └── [various configs]     # Static configuration files
+└── handlers/
+    └── main.yml              # Service restart handlers
+```
+
+## Usage
+
+### Deploy All Services
+```bash
+ansible-playbook site.yml -i hosts.yml --tags docker
+```
+
+### Deploy Specific Services
+```bash
+# Deploy only authentication stack
+ansible-playbook site.yml -i hosts.yml --tags authentik
+
+# Deploy media services
+ansible-playbook site.yml -i hosts.yml --tags audiobookshelf,calibre
+
+# Deploy development tools
+ansible-playbook site.yml -i hosts.yml --tags gitea,codeserver
+
+# Deploy task management
+ansible-playbook site.yml -i hosts.yml --tags mmdl
+```
+
+### Deploy Core Infrastructure Only
+```bash
+ansible-playbook site.yml -i hosts.yml --tags caddy,authentik,glance
+```
+
+## Service-Specific Notes
+
+### MMDL (Task Management)
+- **URL**: https://tasks.thesatelliteoflove.com
+- **Initial Setup**: Visit `/install` endpoint first to run database migrations
+- **Authentication**: Integrates with Authentik OIDC provider
+- **Database**: Uses MySQL 8.0 with automatic schema migration
+- **Features**: CalDAV integration, multiple account support, task management
+
+## Dependencies
+
+### System Requirements
+- Docker CE installed and running
+- UFW firewall configured
+- DNS records pointing to the server
+- Valid SSL certificates (handled automatically by Caddy)
+
+### External Services
+- **DNS**: Requires subdomains configured for each service
+- **Email**: Gitea uses Resend for notifications
+- **Storage**: All services persist data to `/opt/stacks/[service]/`
+
+## Configuration
+
+### Required Variables (in vault)
+- Authentication credentials for various services
+- API keys for external integrations
+- OAuth client secrets for SSO integration
+- Database passwords and connection strings
+
+### Network Configuration
+Services expect to be accessible via subdomains of configured domains:
+- `auth.thesatelliteoflove.com` - Authentik
+- `git.thesatelliteoflove.com` - Gitea
+- `books.thesatelliteoflove.com` - Calibre
+- `tasks.thesatelliteoflove.com` - MMDL
+- (and many more...)
+
+## Monitoring & Management
+
+### Glance Dashboard Integration
+All services include Glance labels for dashboard monitoring:
+- Service health status
+- Container resource usage
+- Parent-child relationships for multi-container services
+
+### Operational Features
+- Automatic container restart policies
+- Health checks for database services
+- Centralized logging and monitoring
+- Backup-ready data structure in `/opt/stacks/`
+
+## Security Considerations
+
+### Network Security
+- UFW-Docker integration for proper firewall rules
+- Services isolated to appropriate network segments
+- Restricted access for sensitive tools (Stirling PDF)
+
+### Authentication
+- Centralized SSO through Authentik for most services
+- OAuth integration where supported
+- Secure secret management through Ansible vault
+
+### Container Security
+- Non-root container execution (UID/GID 1000:1000)
+- Security options: `no-new-privileges: true`
+- Capability dropping and minimal permissions
+
+## Troubleshooting
+
+### Common Issues
+- **Database Connection**: Ensure MySQL containers use proper authentication plugins
+- **OAuth Discovery**: Check issuer URLs don't have trailing slashes
+- **Migration Failures**: Visit service `/install` endpoints for database setup
+- **Network Issues**: Verify containers are on the same Docker network

roles/docker/files/Caddyfile

@@ -37,7 +37,7 @@ watcher.thesatelliteoflove.com {
 }
 
 tasks.thesatelliteoflove.com {
-    reverse_proxy authentik-server-1:9000
+    reverse_proxy mmdl:3000
 }
 
 phlog.thesatelliteoflove.com {

roles/docker/tasks/main.yml

@@ -169,4 +169,8 @@
 
 - name: Install manyfold
   import_tasks: manyfold.yml
-  tags: manyfold
+  tags: manyfold
+
+- name: Install mmdl
+  import_tasks: mmdl.yml
+  tags: mmdl

roles/docker/tasks/mmdl.yml

@@ -0,0 +1,25 @@
+---
+- name: Create mmdl directories
+  ansible.builtin.file:
+    path: "{{ item }}"
+    state: directory
+  loop:
+    - /opt/stacks/mmdl
+    - /opt/stacks/mmdl/data
+    - /opt/stacks/mmdl/mysql
+
+- name: Template mmdl environment file
+  ansible.builtin.template:
+    src: mmdl-env.j2
+    dest: /opt/stacks/mmdl/.env.local
+
+- name: Template mmdl compose file
+  ansible.builtin.template:
+    src: mmdl-compose.yml.j2
+    dest: /opt/stacks/mmdl/compose.yml
+
+- name: Deploy mmdl stack
+  community.docker.docker_compose_v2:
+    project_src: /opt/stacks/mmdl
+    files:
+      - compose.yml

roles/docker/templates/mmdl-compose.yml.j2

@@ -0,0 +1,45 @@
+services:
+  mmdl:
+    image: intriin/mmdl:latest
+    container_name: mmdl
+    restart: unless-stopped
+    depends_on:
+      - mmdl_db
+    env_file:
+      - .env.local
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
+      - "auth.thesatelliteoflove.com:172.20.0.5"
+    labels:
+      glance.name: MMDL
+      glance.icon: si:task
+      glance.url: https://tasks.thesatelliteoflove.com/
+      glance.description: Task and calendar management
+      glance.id: mmdl
+
+  mmdl_db:
+    image: mysql:8.0
+    container_name: mmdl_db
+    restart: unless-stopped
+    command: --default-authentication-plugin=mysql_native_password
+    environment:
+      MYSQL_DATABASE: mmdl
+      MYSQL_USER: mmdl
+      MYSQL_PASSWORD: "{{ vault_mmdl_mysql_password }}"
+      MYSQL_ROOT_PASSWORD: "{{ vault_mmdl_mysql_root_password }}"
+      MYSQL_ALLOW_EMPTY_PASSWORD: "yes"
+      MYSQL_ROOT_HOST: "%"
+    volumes:
+      - mmdl_db:/var/lib/mysql
+    labels:
+      glance.parent: mmdl
+      glance.name: DB
+
+volumes:
+  mmdl_db:
+    driver: local
+
+networks:
+  default:
+    external: true
+    name: lava

roles/docker/templates/mmdl-env.j2

@@ -0,0 +1,41 @@
+# Database Configuration
+DB_HOST=mmdl_db
+DB_USER=mmdl
+DB_PASS={{ vault_mmdl_mysql_password }}
+DB_PORT=3306
+DB_DIALECT=mysql
+DB_CHARSET=utf8mb4
+DB_NAME=mmdl
+
+# Encryption
+AES_PASSWORD={{ vault_mmdl_aes_password }}
+
+# SMTP Settings
+SMTP_HOST=smtp.resend.com
+SMTP_USERNAME=resend
+SMTP_PASSWORD={{ resend_key }}
+SMTP_FROM=tasks@updates.thesatelliteoflove.com
+SMTP_PORT=587
+SMTP_SECURE=true
+
+# Authentication
+USE_NEXT_AUTH=true
+NEXTAUTH_URL=https://tasks.thesatelliteoflove.com
+NEXTAUTH_SECRET={{ vault_mmdl_nextauth_secret }}
+
+# Authentik OIDC Configuration
+AUTHENTIK_ISSUER=https://auth.thesatelliteoflove.com/application/o/mmdl
+AUTHENTIK_CLIENT_ID={{ vault_mmdl_oidc_client_id }}
+AUTHENTIK_CLIENT_SECRET={{ vault_mmdl_oidc_client_secret }}
+
+# User and Session Management
+ALLOW_USER_REGISTRATION=false
+MAX_CONCURRENT_LOGINS=3
+OTP_VALIDITY_PERIOD=300
+SESSION_VALIDITY_PERIOD=30
+
+# Application Settings
+API_URL=https://tasks.thesatelliteoflove.com
+DEBUG_MODE=false
+TEST_MODE=false
+SUBTASK_RECURSION_DEPTH=5