phil/ansible
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
ansible/roles/docker/README.md
Phil 7fdb52e91b 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>
2025-06-06 10:51:39 -06:00

7.2 KiB
Raw Blame History

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

ansible-playbook site.yml -i hosts.yml --tags docker

Deploy Specific Services

# 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

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