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](https://git.jaroszew.ski/ansible/ansible-role-docker-compose-app/src/branch/main/README.md) 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

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

### From Local Development

```bash
# 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:

```yaml
---
- 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

```bash
# 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

```bash
# 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:

```yaml
# 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:
```yaml
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

```bash
# 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

```bash
# 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:

```yaml
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

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

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

## License

MIT

## Author

Patrick Jaroszewski