Ansible Role Docker

Install Docker Engine, the Docker CLI, rootless extras, containerd, Buildx and the Compose plugin from Docker's official APT repository on Debian and Ubuntu with systemd. Installing rootless extras does not configure or activate a rootless daemon.

Requirements

• Install the required collection on the controller: ansible-galaxy collection install -r requirements.yml.
• ansible-core >= 2.15 and gathered facts.
• Debian or Ubuntu with a Docker-supported release and architecture.
• Become privileges and access to distribution repositories and download.docker.com.
• The role installs ca-certificates and python3-debian on the managed host. The Ansible Python interpreter must be able to import python3-debian for deb822_repository.

Rocky/Red Hat installation is not implemented by this APT-based role.

Example Playbook

---
- name: Install Docker hosts
  hosts: docker_hosts
  become: true
  gather_facts: true
  roles:
    - role: ansible-role-docker
      vars:
        docker_users:
          - administrator

Create selected users first, for example through the baseline role. Docker group membership grants root-equivalent access; new membership requires a fresh login. Set docker_users: [] to leave user access unchanged. By default the role selects ansible_user when it is configured.

Role Variables

See defaults/main.yml. The repository URI/key derive from the detected Debian or Ubuntu distribution, its suite derives from the release codename, and its architecture is mapped from gathered facts. Override docker_repo_suite only with a suite actually published by Docker.

docker_packages controls the installed Engine/plugins, docker_conflicting_packages controls removal of installed distribution packages, and docker_apt_cache_valid_time defaults to 3600 seconds. Existing Docker data directories are not removed by the role. Replacing docker.io stops the socket and daemon and can interrupt containers. Removing conflicting containerd/runc packages can also affect other runtimes; review migrations before execution.

Docker Daemon Configuration

Set docker_daemon_options to manage the complete /etc/docker/daemon.json:

docker_daemon_options:
  log-driver: json-file
  log-opts:
    max-size: 10m
    max-file: '3'

The default {} leaves existing configuration unmanaged. Nonempty options replace the entire file with a backup, explicit root ownership and mode 0600 so only root can read settings that may contain credentials. The candidate is validated with dockerd --validate --config-file before saving. Changed configuration restarts Docker before Watchtower deployment; this can interrupt existing containers. Review options for conflicts with daemon startup flags. Returning to {} does not delete the previously managed file. Check mode on fresh hosts may fail validation if dockerd has not yet been installed.

Watchtower

Watchtower is disabled by default. To deploy it under /opt/watchtower, explicitly enable it and provide a trusted immutable image reference pinned to a SHA-256 digest. The role rejects tags and other mutable image references when Watchtower is enabled. It creates the project directory as root:docker with mode 0775, renders docker-compose.yml with mode 0664, and runs the equivalent of docker compose up -d --pull always through community.docker.docker_compose_v2, reporting actual changes.

docker_watchtower_enabled: true
docker_watchtower_directory: /opt/watchtower
# Replace with a trusted image reference pinned to its verified digest:
docker_watchtower_image: registry.example/watchtower@sha256:<64-lowercase-hex-digest>
docker_watchtower_restart_policy: always
docker_watchtower_command: [--schedule, '0 0 3 * * 1']
docker_watchtower_environment:
  WATCHTOWER_NOTIFICATIONS: email
  WATCHTOWER_NOTIFICATION_EMAIL_TO: ''
  WATCHTOWER_NOTIFICATION_EMAIL_FROM: ''
  WATCHTOWER_NOTIFICATION_EMAIL_SERVER_USER: ''
  WATCHTOWER_NOTIFICATION_EMAIL_SERVER_PASSWORD: ''
  WATCHTOWER_NOTIFICATION_EMAIL_SERVER: ''
  WATCHTOWER_NOTIFICATIONS_LEVEL: error
  WATCHTOWER_CLEANUP: 'true'

Defaults follow the supplied Compose configuration for restart always, Monday 03:00 in the container timezone, cleanup, and email notifications at error level. Supply SMTP values through inventory and keep the password in Ansible Vault. Environment overrides replace the entire mapping. Password-bearing task output and template diffs are suppressed; the file is not world-readable when an SMTP password is configured. Existing backups may contain previous settings. No Compose version field is needed with the installed Compose plugin.

Watchtower mounts the Docker socket and updates containers according to the configured schedule. Choose and verify the image digest using the image publisher's trusted release information; pinning does not itself establish that the image publisher or image is trustworthy. Image availability, Docker API compatibility, and SMTP delivery still need validation on a target host. Set docker_watchtower_enabled: true to deploy/start Watchtower after setting its pinned image, or docker_watchtower_enabled: false to stop and remove its existing managed Compose deployment. Configuration files and volumes are retained. Set this variable per host/group in inventory or with -e docker_watchtower_enabled=false. If no managed Compose file exists, disabling does nothing. Deployment and removal are skipped in check mode. Check mode renders configuration without pulling images or starting containers.

Task Structure

tasks/main.yml imports:

• validate.yml: platform, settings and existing users.
• prerequisites.yml: package prerequisites and conflicting packages.
• repository.yml: signed deb822 repository.
• install.yml: packages, systemd reload and enabled services.
• users.yml: additive Docker group membership.
• daemon.yml: optional validated daemon configuration and restart notification.
• watchtower.yml: Watchtower Compose deployment.

Firewall changes are not managed. Other existing Docker repository definitions must not conflict with the managed docker.sources file.

Validation

Run syntax validation and test on representative VMs before deployment. Check mode on a fresh host may fail when python3-debian or repository/package metadata is not yet available; service startup is skipped in check mode. Full host installation, migration and idempotence have not been tested here.

After deployment, check docker version, docker compose version, docker buildx version and systemctl status docker.service docker.socket. Run the role twice to verify idempotence.

References: Docker on Debian, Docker on Ubuntu, Docker group access.

License

MIT - See LICENSE file for details.

Copyright (c) 2026 SPIE DataSolutions B.V.

Changelog

See CHANGELOG.md for a list of all notable changes to this project.

Security

Please see our Security Policy for reporting security vulnerabilities.

Contributing

Please read our Contributing Guide and Code of Conduct before submitting a Pull Request.

Support

For questions or support, contact: support.ds.nl@spie.com