Ansible Role: Docker

An Ansible Role that installs Docker on Linux.

Requirements

None needed.

Role Variables

Here are the available variables with their default values (check defaults/main.yml):

# Choose either 'ce' for Community Edition or 'ee' for Enterprise Edition.
docker_edition: 'ce'
docker_packages:
    - "docker-{{ docker_edition }}"
    - "docker-{{ docker_edition }}-cli"
    - "docker-{{ docker_edition }}-rootless-extras"
docker_packages_state: present

The docker_edition can be ce (Community Edition) or ee (Enterprise Edition). You can set a specific Docker version to install using format for your distribution: For Red Hat/CentOS: docker-{{ docker_edition }}-<VERSION> (Note: apply to all packages); For Debian/Ubuntu: docker-{{ docker_edition }}=<VERSION> (Note: apply to all packages).

You can decide if the package is installed, removed, or updated to the latest version by setting docker_packages_state to present, absent, or latest, respectively. The Docker service will restart automatically if the Docker package is updated.

docker_obsolete_packages:
  - docker
  - docker.io
  - docker-engine
  - podman-docker
  - containerd
  - runc

This lists packages to be removed before running this role. Check Docker's installation instructions for a current list of old packages to uninstall.

docker_service_manage: true
docker_service_state: started
docker_service_enabled: true
docker_restart_handler_state: restarted

These variables control the Docker service's state and whether it starts on boot. If installing Docker inside a container without systemd or sysvinit, set docker_service_manage to false.

docker_install_compose_plugin: true
docker_compose_package: docker-compose-plugin
docker_compose_package_state: present

Options for installing the Docker Compose Plugin, which is different from below as it installs as a Docker plugin (to be used with docker compose) instead of a standalone application.

docker_install_compose: false
docker_compose_version: "2.11.1"
docker_compose_arch: "{{ ansible_architecture }}"
docker_compose_url: "https://github.com/docker/compose/releases/download/{{ docker_compose_version }}/docker-compose-linux-{{ docker_compose_arch }}"
docker_compose_path: /usr/local/bin/docker-compose

Options for installing Docker Compose.

docker_add_repo: true

This controls if the official Docker repository will be added. Set to false if you want to stick with the default Docker packages for your system or manage the repository yourself.

docker_repo_url: https://download.docker.com/linux

The main Docker repository URL, common for Debian and RHEL systems.

docker_apt_release_channel: stable
docker_apt_arch: "{{ 'arm64' if ansible_architecture == 'aarch64' else 'amd64' }}"
docker_apt_repository: "deb [arch={{ docker_apt_arch }}] {{ docker_repo_url }}/{{ ansible_distribution | lower }} {{ ansible_distribution_release }} {{ docker_apt_release_channel }}"
docker_apt_ignore_key_error: True
docker_apt_gpg_key: "{{ docker_repo_url }}/{{ ansible_distribution | lower }}/gpg"
docker_apt_filename: "docker"

(For Debian/Ubuntu only.) You can switch to nightly channel for Nightly releases.

Change docker_apt_gpg_key if behind a firewall or to a valid mirror. Ensure to update docker_apt_repository accordingly. docker_apt_filename controls the source list filename created in sources.list.d. If upgrading from an older version, this should match the existing file name to avoid conflicts.

docker_yum_repo_url: "{{ docker_repo_url }}/{{ (ansible_distribution == 'Fedora') | ternary('fedora','centos') }}/docker-{{ docker_edition }}.repo"
docker_yum_repo_enable_nightly: '0'
docker_yum_repo_enable_test: '0'
docker_yum_gpg_key: "{{ docker_repo_url }}/centos/gpg"

(For RedHat/CentOS only.) Enable the Nightly or Test repository by setting the respective variables to 1.

You can also change docker_yum_gpg_key for a different URL if needed.

docker_users:
  - user1
  - user2

A list of users to add to the docker group so they can use Docker on the server.

docker_daemon_options:
  storage-driver: "devicemapper"
  log-opts:
    max-size: "100m"

Custom options for dockerd can be set here, affecting the file /etc/docker/daemon.json.

Use with Ansible (and docker Python library)

If you want to use Ansible to build Docker images and manage containers on the server, you can easily include the docker Python library using the geerlingguy.pip role:

- hosts: all

  vars:
    pip_install_packages:
      - name: docker

  roles:
    - geerlingguy.pip
    - geerlingguy.docker

Dependencies

None.

Example Playbook

- hosts: all
  roles:
    - geerlingguy.docker

License

MIT / BSD

Sponsors

• We Manage: Helping start-ups and established businesses to scale their infrastructure sustainably.

The above sponsors support Jeff Geerling on GitHub Sponsors. You can support Jeff's work too, to help improve these Ansible open-source projects!

Author Information

This role was created in 2017 by Jeff Geerling, author of Ansible for DevOps.