🐳 Docker

This page documents containerized application deployment using Docker and Ansible in the homelab. It covers architecture, deployment workflow, version pinning, and integration with external resources like PostgreSQL or NFS.

Think of this as a generic framework for all containerized services in the homelab.

To understand how Docker service deployment evolved in this homelab — including the challenges, patterns, and decisions that led to the creation of the shared docker_service_deploy role,

👉 see the Evolution of Docker Service Deployment page.

🏗 Architecture Overview

                  ┌───────────────────────────┐
                  │ Host / Docker Environment │
                  │                           │
                  │ ┌───────────────────────┐ │
                  │ │ App Container 1       │ │
                  │ │ - Pinned Image        │ │
                  │ │ - Config & Backup     │ │
                  │ └───────────────────────┘ │
                  │ ┌───────────────────────┐ │
                  │ │ App Container 2       │ │
                  │ │ - Pinned Image        │ │
                  │ │ - Config & Backup     │ │
                  │ └───────────────────────┘ │
                  │                           │
                  └─────────────▲─────────────┘
                                │ Access
                  ┌─────────────┴─────────────┐
                  │ Users / Clients           │
                  │ Web Browser / API         │
                  └─────────────▲─────────────┘
                                │ Database or Shared Storage
                  ┌─────────────┴─────────────┐
                  │ External Services         │
                  │ - PostgreSQL              │
                  │ - NFS / Network Storage   │
                  └───────────────────────────┘

Key Notes:

• Each app runs in an isolated container
• Configs and backups stored in persistent volumes
• Containers can connect to external resources like PostgreSQL or NFS

📐 Architecture & Deployment Approach

• Docker-Compose Templates: Use a template docker-compose.yml as the primary definition for container services, volumes, ports, and environment variables.
• Application Configuration Files: Applications may provide their own configuration files (e.g., config.xml, app.cfg) that should be mounted into the container.
• Volumes & Backups: Persist data via host-mounted volumes or NFS shares for configuration and data storage.

• Service Lifecycle Tasks: Typical Ansible tasks include:

  1. Creating configuration directories
  2. Copying template files
  3. Starting, stopping, and updating containers
  4. Cleaning up unused images and networks

Example Directory Layout:

/config/
   ├── app1/
   │    ├── docker-compose.yml
   │    └── app1.cfg
   └── app2/
        ├── docker-compose.yml
        └── app2.cfg
/nfs/backups/
   ├── app1/
   └── app2/

⚙️ Docker Deployment

1. Stop & remove existing container

docker stop <container>
docker rm <container>
docker network prune -f

2. Ensure persistent directories exist

mkdir -p /config/appname
mkdir -p /nfs/backups/appname
chown <user>:<group> /config/appname

3. Deploy templated configuration files

• docker-compose.yml
• App-specific configuration (e.g., config.xml, sabnzbd.ini)

4. Prune unused Docker images (optional)

docker image prune -f

5. Pull pinned Docker image

docker-compose -f /config/appname/docker-compose.yml pull

6. Start container

docker-compose -f /config/appname/docker-compose.yml up -d

The Docker Deployment Example Commands vs Ansible Tasks page provides a side-by-side equivalence between manual Docker deployment commands and the automated Ansible tasks.

🔒 Version Pinning & Best Practices

• Always pin Docker images to a specific version:

app_setup_version: "1.2.3"
app_setup_docker_image_name: "appname:{{ app_setup_version }}"

• Avoid latest for reproducibility
• Use templated Docker Compose files
• Keep config & data volumes separate
• Store logs/backups on persistent network storage

🌐 Integrating External Resources

• Databases: e.g., Radarr, Sonarr, Lidarr use external PostgreSQL

app_setup_pg_host: "{{ global_ip_addresses[groups['pgdb'][0]] }}"
app_setup_pg_port: 5432

• Network Storage: Configs, downloads, backups mounted from NFS or Ceph
• Containers connect via environment variables and mounted volumes

🎯 Key Features

• Fully automated container deployment via Ansible
• Persistent configuration & backup volumes
• Pinned Docker images for reproducibility
• Template-driven, scalable deployments
• Integration with external databases and network storage
• Reusable workflow for all homelab apps

📚 Related Pages

• Docker Deployment Example Commands vs Ansible Tasks - Illustrates the equivalence between manual Docker commands and the automated Ansible tasks
• Docker Command Cheat Sheet - A list of commonly used Docker commands
• Calibre Deployment - Role Overview - An overview of the Calibre role
• Calibre-Web Deployment - Role Overview - An overview of the Calibre-Web role
• Lazy Librarian Deployment - Role Overview - An overview of the Lazy Librarian roe
• Lidarr Deployment - Role Overview - An overview of the Lidarr role
• Radarr Deployment - Role Overview - An overview of the Radarr role
• SABnzbd Deployment - Role Overview - An overview of the SaBnzbd role
• Sonarr Deployment - Role Overview - An overview of the Sonarr role
• Template New Docker Service Role — Starter template for new service roles
• Contributor Guide Adding a Docker Service Role — Contributor Guide: Adding a Docker Service Role
• Evolution of Docker Service Deployment — Historical context and reasoning behind the shared role