Skip to main content

docker-host role

The docker-host Ansible role is run against any host that should be a Docker host — a NAS, a utility VM, an ARM SBC, etc. It is intentionally narrow: install the engine + CLI, set sane daemon defaults, expose the docker group, and stop.

Source: ansible/roles/docker-host.

What it does​

  1. Installs the docker-ce engine + CLI from the upstream Docker repository (not the distro-packaged one — the distro-packaged version lags badly on most LTS releases).
  2. Drops a /etc/docker/daemon.json with:
    • log-driver: json-file + size + count (no unbounded log growth)
    • storage-driver: overlay2
    • live-restore: true so daemon restarts don't kill containers
  3. Creates the docker group and adds a configurable list of users.
  4. Enables and starts the daemon.
  5. Optionally pre-pulls a baseline of images (off by default).

What it does not do​

  • Pull or run any specific containers (that's the host's own role/playbook).
  • Set up Docker Compose stacks (separate role per appliance).
  • Configure firewall — the engine's iptables rules are left alone.

Variables​

docker_users: []                  # list of user names to add to the docker group
docker_baseline_images: []        # optional list of images to pre-pull
docker_daemon_extra: {}           # optional dict merged into daemon.json

Example play​

- hosts: docker_hosts
  roles:
    - role: docker-host
      vars:
        docker_users:
          - johnny
        docker_baseline_images:
          - lscr.io/linuxserver/syncthing

That's the play used against the Synology Docker host (with the OS-equivalent group / install path adapted).

Conventions​

  • Idempotent. A second run is a no-op.
  • OS-aware. Branches on ansible_os_family for package install paths; everything else is OS-neutral.
  • No host-specific config. Anything host-specific belongs in the host's group_vars or play, not in the role.

Where to look next​