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', '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: 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:
- Manual pages: docker(1), docker-run(1), Dockerfile(5), docker-compose(1)
- Docker page on Debian Wiki
- Docker page on Arch Linux Wiki
- Docker documentation page
- Docker guide for Ansible
- Official DebOps image in the Docker Hub: debops/debops (see also Quick start with Docker)