homelab/ansible/archive/documentation/playbooks/manage_docker_environment.md

Docker Environment Management Playbook

Overview

The manage_docker_environment.yml playbook provides comprehensive Docker management capabilities for your homelab, including installation, configuration, container management, health monitoring, and maintenance tasks.

Target Hosts

• Primary: docker_hosts group (includes docker-01 at 10.0.0.251)
• Can be run against any host in the ubuntu_lab group

Features

1. Docker Installation

• Installs Docker CE with all required components
• Includes Docker Compose plugin
• Installs Docker BuildKit
• Configures Docker service for auto-start

2. Configuration Management

• Configures Docker daemon with logging limits
• Adds specified users to the docker group
• Sets up storage driver (overlay2)
• Creates custom Docker networks

3. Container Management

• Lists all running containers
• Creates standard networks (backend, frontend)
• Provides container inventory

4. Health Monitoring

• Checks Docker disk usage
• Identifies unhealthy containers
• Reports system status

5. Maintenance & Cleanup

• Removes stopped containers
• Prunes unused images
• Cleans up unused volumes
• Removes orphaned networks

6. Configuration Backup

• Backs up docker-compose files
• Creates timestamped copies in /opt/docker-backups

Usage

Basic Execution

# Run all tasks
ansible-playbook -i inventory/hosts.ini playbooks/manage_docker_environment.yml

# Check mode (dry run)
ansible-playbook -i inventory/hosts.ini playbooks/manage_docker_environment.yml --check

# Run with specific tags
ansible-playbook -i inventory/hosts.ini playbooks/manage_docker_environment.yml --tags "health,monitoring"

Available Tags

Tag	Description
install	Docker installation tasks
setup	Installation + configuration
config	Configuration management only
containers	Container management tasks
management	Container inventory and network setup
health	Health checks and monitoring
monitoring	Same as health
maintenance	Cleanup and pruning tasks
cleanup	Same as maintenance
backup	Configuration backup tasks

Tag Combinations

# Install and configure Docker (first run)
ansible-playbook -i inventory/hosts.ini playbooks/manage_docker_environment.yml --tags "install,config"

# Daily health check
ansible-playbook -i inventory/hosts.ini playbooks/manage_docker_environment.yml --tags "health"

# Weekly maintenance
ansible-playbook -i inventory/hosts.ini playbooks/manage_docker_environment.yml --tags "maintenance" \
  -e "docker_cleanup_enabled=true"

# Full system audit
ansible-playbook -i inventory/hosts.ini playbooks/manage_docker_environment.yml --tags "containers,health"

Configuration Variables

Docker Users

docker_users:
  - chester
  - additional_user

Daemon Configuration

docker_daemon_options:
  log-driver: "json-file"
  log-opts:
    max-size: "10m"
    max-file: "3"
  storage-driver: "overlay2"
  insecure-registries:
    - "registry.local:5000"

Cleanup Settings

# Enable cleanup tasks (default: false for safety)
docker_cleanup_enabled: true

# Remove images older than X days
docker_cleanup_older_than_days: 30

Examples

First-Time Setup

# Install Docker on new host
ansible-playbook -i inventory/hosts.ini playbooks/manage_docker_environment.yml \
  --limit docker-01 \
  --tags "install,config"

Regular Maintenance Workflow

# 1. Check health status
ansible-playbook -i inventory/hosts.ini playbooks/manage_docker_environment.yml \
  --tags "health"

# 2. Review disk usage, then run cleanup if needed
ansible-playbook -i inventory/hosts.ini playbooks/manage_docker_environment.yml \
  --tags "maintenance" \
  -e "docker_cleanup_enabled=true"

# 3. Backup configurations
ansible-playbook -i inventory/hosts.ini playbooks/manage_docker_environment.yml \
  --tags "backup"

Add Custom Networks

# In the playbook or as extra vars:
docker_networks:
  - name: web_tier
    driver: bridge
  - name: database_tier
    driver: bridge
    internal: true

Safety Features

• Cleanup Disabled by Default: Cleanup tasks require explicit enabling via docker_cleanup_enabled=true
• Check Mode Compatible: All tasks support --check for dry-run testing
• Idempotent: Can be run multiple times safely
• Non-Destructive Monitoring: Health checks don't modify system state

Prerequisites

• Ubuntu/Debian-based system
• SSH access with sudo privileges
• Python 3 with pip available
• Internet connection for package downloads

Post-Execution

After running the playbook:

1. Verify Docker installation:

   ssh chester@10.0.0.251 "docker --version && docker compose version"
   

2. Test Docker without sudo:

   ssh chester@10.0.0.251 "docker ps"
   

   Note

   Users may need to log out and back in for group membership changes to take effect.

3. Check Docker status:

   ssh chester@10.0.0.251 "sudo systemctl status docker"
   

Troubleshooting

Docker service won't start

# Check Docker daemon logs
ssh chester@10.0.0.251 "sudo journalctl -u docker -n 50"

# Validate daemon.json syntax
ssh chester@10.0.0.251 "sudo cat /etc/docker/daemon.json | jq ."

Permission denied errors

# Verify group membership
ssh chester@10.0.0.251 "groups"

# Force group update (requires re-login)
ssh chester@10.0.0.251 "newgrp docker"

High disk usage

# Run cleanup manually
ansible-playbook -i inventory/hosts.ini playbooks/manage_docker_environment.yml \
  --tags "maintenance" \
  -e "docker_cleanup_enabled=true"

Integration with Other Playbooks

This playbook works alongside:

• init_swarm_cluster.yml - Run Docker setup first
• bootstrap_ai_workstation.yml - Can install Docker as dependency

Next Steps

1. Deploy Applications: Create docker-compose files in /opt/docker/
2. Set Up Monitoring: Integrate with Prometheus/Grafana
3. Automate Backups: Schedule regular configuration backups
4. Container Orchestration: Consider Swarm or K3s for multi-host deployments