ansible-collection-docker-apps/README.md

Ansible Collection - patrickj.docker_apps

A comprehensive Ansible collection for deploying and managing Docker Compose applications with enterprise-grade features including backup/restore, health checks, and automated updates.

Overview

A curated collection of Docker Compose roles for self-hosted applications. Each role leverages the docker_compose_app base to provide standardized deployment, configuration management, backup procedures, and lifecycle operations across diverse containerized services.

Consult the role development documentation for guidance on creating custom roles, variable conventions, and integration patterns.

Features

• 🏗️ Template-based deployment with Jinja2 templating
• 🔄 Backup & restore system (store backups on the Ansible controller + remote host)
• 🏥 Health checks and deployment verification
• 🏷️ Tag-based execution for selective operations
• 📦 Multiple deployment modes (template, file, or inline content)
• 🔧 Flexible directory management
• ⚙️ Configurable retention policies
• 🔄 Container update automation

Installation

From Git Repository

ansible-galaxy collection install https://git.jaroszew.ski/ansible/ansible-collection-docker-apps.git

From Local Development

# From the collection directory
ansible-galaxy collection install .

# Or specify path
ansible-galaxy collection install /path/to/patrickj/docker_apps

Quick Start

1. Basic Deployment

Create a playbook using the collection roles:

---
- name: Deploy media server applications
  hosts: localhost
  become: yes
  vars:
    host_root_path: /opt/docker
    app_timezone: "America/New_York"
  roles:
    - patrickj.docker_apps.open-webui
    - patrickj.docker_apps.audiobookshelf
    - patrickj.docker_apps.paperless-ngx

2. Run the Deployment

# Full deployment
ansible-playbook deploy.yml

# Setup only (directories, templates - no containers)
ansible-playbook --tags setup deploy.yml

# Deploy specific apps
ansible-playbook deploy.yml --limit jellyfin

Available Roles

Media Applications

• jellyfin - Media server for movies, TV shows, music
• audiobookshelf - Audiobook and podcast server
• navidrome - Music streaming server

Utilities & Monitoring

• uptime-kuma - Uptime monitoring
• speedtest-tracker - Internet speed monitoring
• glance - Dashboard
• grafana - Data visualization
• influxdb - Time series database

Productivity

• paperless-ngx - Document management
• mealie - Recipe manager
• linkwarden - Bookmark manager
• immich - Photo management
• gitea - Git repository server

Web Services

• open-webui - Web interface for LLMs
• redlib - Alternative Reddit frontend
• calibre-web - eBook server

I'll be adding more roles as I incorporate them into my homelab.

Usage Examples

Tag-Based Operations

# Setup applications (do not start containers)
ansible-playbook --tags setup playbook.yml

# Full deployment (setup + start containers)
ansible-playbook --tags deploy playbook.yml

# Backup applications
ansible-playbook --tags backup playbook.yml

# Restore from backup then deploy
ansible-playbook --tags restore,deploy playbook.yml

# Update container images
ansible-playbook --tags update playbook.yml

# Backup and update
ansible-playbook --tags backup,update playbook.yml

# Health check only
ansible-playbook --tags healthcheck playbook.yml

Configuration

Global Variables

Set these variables in your playbook or inventory:

# Required
host_root_path: /opt/docker              # Base directory for all apps

# Optional  
app_timezone: "UTC"                      # Container timezone
app_restart_policy: unless-stopped       # Docker restart policy
backup_path: /opt/backups               # Backup storage location

Per-Application Variables

Each application role accepts specific configuration. See individual role documentation in roles/<app_name>/README.md.

Common patterns:

app_name: custom-instance-name          # Override default name
{app}_http_port: 8080                  # Custom port
{app}_config_path: /custom/path        # Override paths

Backup & Restore

Automated Backups

# Create backups for all deployed applications
ansible-playbook --tags backup site.yml

# Schedule daily backups (cron)
0 2 * * * ansible-playbook --tags backup /path/to/playbook.yml

Restore Operations

# Restore latest backup
ansible-playbook --tags restore playbook.yml

# Full restore workflow (setup + restore + deploy)
ansible-playbook --tags setup,restore,deploy playbook.yml

# Restore specific archive
ansible-playbook --tags restore playbook.yml \
  -e app_restore_archive=/path/to/backup.tar.gz

Requirements

• Ansible: >= 2.14
• Docker: >= 20.10
• Docker Compose: >= 2.0
• Python: >= 3.8

Dependencies

The collection automatically handles dependencies:

collections:
  - community.docker  # For Docker Compose operations

Development

Adding New Applications

1. Create role directory: roles/new-app/
2. Follow the template structure from existing roles
3. Configure meta dependency on docker_compose_app
4. Add to documentation

Testing

# Test role syntax
ansible-playbook --syntax-check playbook.yml

# Test specific role
ansible-playbook --tags setup --check playbook.yml

License

MIT

Author

Patrick Jaroszewski