Getting started

Initial configuration

Docker is available in two editions. Community Edition (CE) and Enterprise Edition (EE). Docker EE is not supported on Debian distributions. See also: Docker variants.

The Docker package from distribution repositories will be installed by default (on Jessie it means that the jessie-backports repository needs to be available, which is the default in DebOps). You can install the upstream version of Docker by setting the docker_server__upstream: True variable in Ansible’s inventory. Upstream Docker is installed on Debian Stretch by default, since this release does not provide included Docker packages.

A Docker server managed by DebOps does not listen on any TCP ports by default. You can set docker_server__tcp to True if you need remote access to the Docker server. You will also need to tweak your firewall in this case, which is easily done with docker_server__tcp_allow. It is recommended to use the debops.pki role to secure the connection between the client and the Docker server.

On hosts with ferm firewall support enabled, a special post-hook script will be installed that restarts the Docker daemon after ferm is restarted.

The docker-compose script will be installed on hosts with upstream Docker, in a Python virtualenv. It will be automatically available system-wide via a symlink in /usr/local/bin/ directory.

To let the docker daemon trust a private registry with self-signed certificates, add the root CA used to sign the registry's certificate through the debops.pki role.

This role does not support switching from Docker CE to Docker EE on an already installed machine. It does support switching from distribution repository to upstream. However, it is recommended to start with a clean machine if possible.

The debops.docker_server role relies on configuration managed by debops.core, debops.ferm, and debops.pki Ansible roles.

Useful variables

This is a list of role variables which you most likely want to define in Ansible inventory to customize Docker:

docker_server__tcp
Enable or disable listening for TLS connections on the Docker TCP port.
docker_server__tcp_allow
List of IP addresses or subnets that can connect to Docker daemon remotely over TLS.
docker_server__admins
List of UNIX accounts that have access to Docker daemon socket.

Example inventory

To configure Docker on a given remote host, it needs to be added to the [debops_service_docker_server] Ansible inventory group:

[debops_service_docker_server]
hostname

Example playbook

Here's an example playbook that can be used to manage Docker:

---

- name: Manage Docker server
  collections: [ 'debops.debops' ]
  hosts: [ 'debops_service_docker_server' ]
  become: True

  environment: '{{ inventory__environment | d({})
                   | combine(inventory__group_environment | d({}))
                   | combine(inventory__host_environment  | d({})) }}'

  roles:

    - role: resolvconf
      tags: [ 'role::resolvconf', 'skip::resolvconf' ]
      resolvconf__enabled: True

    - role: keyring
      tags: [ 'role::keyring', 'skip::keyring', 'role::docker_server' ]
      keyring__dependent_apt_keys:
        - '{{ docker_server__keyring__dependent_apt_keys }}'

    - role: etc_services
      tags: [ 'role::etc_services', 'skip::etc_services' ]
      etc_services__dependent_list:
        - '{{ docker_server__etc_services__dependent_list }}'

    - role: ferm
      tags: [ 'role::ferm', 'skip::ferm' ]
      ferm__dependent_rules:
        - '{{ docker_server__ferm__dependent_rules }}'

    - role: python
      tags: [ 'role::python', 'skip::python', 'role::docker_server' ]
      python__dependent_packages3:
        - '{{ docker_server__python__dependent_packages3 }}'
      python__dependent_packages2:
        - '{{ docker_server__python__dependent_packages2 }}'

    - role: docker_server
      tags: [ 'role::docker_server', 'skip::docker_server' ]

Ansible tags

You can use Ansible --tags or --skip-tags parameters to limit what tasks are performed during Ansible run. This can be used after a host was first configured to speed up playbook execution, when you are sure that most of the configuration is already in the desired state.

Available role tags:

role::docker_server
Main role tag, should be used in the playbook to execute all of the role tasks as well as role dependencies.
role::docker_server:config
Run tasks related to Docker configuration.
role::docker_server:admins
Manage access to Docker daemon by UNIX accounts.

Other resources

List of other useful resources related to the debops.docker_server Ansible role: