nickjj.docker

What is ansible-docker?

This is an Ansible role that helps you:

• Install Docker (you can choose different versions and channels)
• Install Docker Compose v2 and/or v1 (you can choose specific versions)
• Install the docker package for Python, which allows the use of Ansible's docker_* modules
• Manage login credentials for Docker registries
• Set up users to run Docker without needing root access
• Adjust the configuration of the Docker daemon
• Create a scheduled task to clean up Docker resources

Why would you want to use this role?

If you like Docker, this role makes it easy to set up a Docker host that's ready for production.

If you're unfamiliar with Docker or want to learn more, check out Dive into Docker: The Complete Docker Course for Developers.

Supported platforms

• Ubuntu 20.04 LTS (Focal Fossa)
• Ubuntu 22.04 LTS (Jammy Jellyfish)
• Debian 11 (Bullseye)
• Debian 12 (Bookworm)

Older versions might work, but they aren't officially supported.

You are viewing documentation for the master branch, which may be ahead of the latest release. Switch to the latest release.

Quick start

I aim to make my roles user-friendly while allowing customization.

What's included by default?

The latest stable version of Docker CE and Docker Compose v2 will be installed, Docker will clean up unnecessary files once a week, and Docker container logs will be managed by journald.

Example playbook

---

# docker.yml

- name: Example
  hosts: "all"
  become: true

  roles:
    - role: "nickjj.docker"
      tags: ["docker"]

Usage: ansible-playbook docker.yml

Installation

$ ansible-galaxy install nickjj.docker

Default role variables

Installing Docker

Channel

Choose "stable" or "test." You can specify multiple channels.

docker__channel: ["stable"]

Version

• If set to "", the latest Docker version will be installed.
• If specified, that version will be installed.

docker__version: ""

# For example, pin it to version 25.0.
docker__version: "25.0"

Upgrade strategy

• Set to "present" to prevent automatic upgrades in the future.
• Set to "latest" to allow automatic upgrades.

docker__state: "present"

Downgrade strategy

To downgrade, manually uninstall Docker and then run this role to install the desired version.

# An Ansible command to stop and remove Docker on all hosts.
ansible all -m systemd -a "name=docker-ce state=stopped" \
  -m apt -a "name=docker-ce autoremove=true purge=true state=absent" -b

Installing Docker Compose v2

Docker Compose v2 will be installed via the official docker-compose-plugin managed by Docker.

Version

• If set to "", the latest version of Docker Compose v2 will be installed.
• Specify a version to pin it.

docker__compose_v2_version: ""

Upgrade strategy

It follows the same rules as Docker's upgrade strategy.

Downgrade strategy

Manually uninstall Docker Compose v2, then specify the version you want to install.

# An Ansible command to remove Docker Compose Plugin from all hosts.
ansible all -m apt -a "name=docker-compose-plugin autoremove=true purge=true state=absent" -b

Installing Docker Compose v1

This role does not install Docker Compose v1 by default since it is deprecated. However, you can install it by setting docker__pip_docker_compose_state: "present".

You can install both versions together because v1 uses docker-compose and v2 uses docker compose.

Version

docker__compose_version: ""

Configuring users for Docker access

List users to be added to the docker group for access without root permissions.

docker__users: ["{{ ansible_env.SUDO_USER | d('root') }}"]

Docker registry logins

Configure login credentials for one or more Docker registries.

docker__login_become_user: "{{ docker__users | first | d('root') }}"

docker__registries:
  - username: "your_docker_hub_username"
    password: "your_docker_hub_password"
docker__registries: []

Docker daemon options (JSON)

Set Docker daemon options in /etc/docker/daemon.json.

docker__default_daemon_json: |
  "log-driver": "journald",
  "features": {
    "buildkit": true
  }

Advanced systemd directives

Modify or add to Docker's systemd configuration using this variable.

docker__systemd_override: ""

Cron jobs for Docker

By default, this will clean up Docker resources weekly.

docker__cron_jobs_prune_flags: "af"
docker__cron_jobs_prune_schedule: ["0", "0", "*", "*", "0"]

APT package manager settings

Docker needs several dependencies installed. You usually don't need to change these.

docker__package_dependencies:
  - "apt-transport-https"
  - "ca-certificates"
  - "cron"
  - "gnupg2"
  - "software-properties-common"

Working with Python packages

Configure Virtualenv

Install Python packages into a Virtualenv:

docker__pip_virtualenv: "/usr/local/lib/docker/virtualenv"

PIP package installation

docker__default_pip_packages:
  - name: "docker"
    state: "{{ docker__pip_docker_state }}"

Using Ansible's docker_* modules

Configure the Python interpreter to use Virtualenv for the docker_* modules in your Ansible tasks.

License

MIT