Getting started

Initial configuration

By default Docker is installed from Debian repositories. Users can enable upstream Docker APT repositories using the docker_server__upstream boolean variable. When it's set to True, the debops.extrepo Ansible role will be used to configure the repository. Upstream and Debian versions can be downgraded and upgraded as needed, but the role doesn't remove packages that are no longer needed by either version.

The docker-compose command doesn't exist when upstream Docker is installed. Users can use the docker compose subcommand instead, since Compose is implemented as a Go plugin.

The role can configure systemd-resolved service on the host to listen for DNS queries on the docker0 interface. This way, Docker containers can utilize the host's DNS resolver to resolve hostnames and FQDNs. This works with the default network configuration used by Docker.

The role can configure the firewall (via the debops.ferm role) to allow connections to ports used in Docker Swarm mode; this is disabled by default. Currently, Swarm setup is not implemented and needs to be performed manually.

Docker and systemd integration

Some of the Docker configuration options need to be configured via systemd units, to override command line arguments (for example the -H or --host option cannot be modified using the daemon configuration file) or define environment variables for the daemon (for example HTTP/HTTPS proxy which should be used to access external sites). This can be done using the debops.systemd Ansible role, which is included in the service/docker_server.yml playbook.

The docker_server__systemd__dependent_units variable can be used to add systemd configuration which will be applied to the host when the Docker service is configured. For example, to add HTTP proxy configuration, define this in the Ansible inventory:

docker_server__systemd__dependent_units:

  - name: 'docker.service.d/proxy.conf'
    comment: 'Proxy configuration for Docker'
    raw: |
      [Service]
      Environment="http_proxy=http://proxy.example.com:3128"
      Environment="https_proxy=http://proxy.example.com:3128"
      Environment="no_proxy=localhost,127.0.0.1,docker-registry.example.com,.corp"
    state: 'present'
    restart: 'docker.service'

This will add the /etc/systemd/system/docker.service.d/proxy.conf unit on the host and restart the docker.service unit after the playbook is finished.

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', 'debops.roles01',
                 'debops.roles02', 'debops.roles03' ]
  hosts: [ 'debops_service_docker_server' ]
  become: True

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

  roles:

    - role: extrepo
      tags: [ 'role::extrepo', 'skip::extrepo' ]
      extrepo__dependent_sources:
        - '{{ docker_server__extrepo__dependent_sources }}'

    - role: etc_services
      tags: [ 'role::etc_services', 'skip::etc_services', 'role::ferm' ]
      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: docker_server
      tags: [ 'role::docker_server', 'skip::docker_server' ]

    - role: systemd
      tags: [ 'role::systemd', 'skip::systemd' ]
      systemd__dependent_units:
        - '{{ docker_server__systemd__dependent_units }}'

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: