ansible/roles/docker/README.md

# 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