initial commit

2026-01-30 15:07:31 -05:00
commit 7844cc4416
83 changed files with 3802 additions and 0 deletions
@@ -0,0 +1,222 @@
+# 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