geerlingguy.docker

This role installs and configures Docker on Linux hosts using Ansible. It is a practical choice for Semaphore users who want a repeatable way to prepare servers for container workloads without manually handling package repositories, service setup, daemon configuration, and user permissions on each machine.

In a Semaphore workflow, this role is useful when you want a job template that can bring a fresh server to a working Docker state with one run. It works well for application servers, CI runners, internal tools, self-hosted services, and homelab machines.

What This Role Does

When executed from Semaphore, the role can:

• install Docker Engine and common companion packages
• remove older or conflicting Docker-related packages
• configure the Docker package repository
• install the Docker Compose plugin
• manage the Docker service state and boot behavior
• apply Docker daemon settings
• add selected users to the docker group

This makes it a strong baseline role for teams that want a standard Docker setup across multiple hosts.

Typical Use Cases

You can use this role in Semaphore for:

• preparing new Linux servers for container deployments
• standardizing Docker installation across staging and production
• setting up hosts that will run docker compose applications
• provisioning build or automation runners that require Docker
• managing a small fleet of VMs with consistent Docker settings

Why It Works Well in Semaphore

Semaphore is often used to run the same playbook repeatedly across different environments. This role fits that model well because most of its behavior is controlled through variables. That means you can keep one task template and adjust the behavior with inventory variables, environment-specific overrides, or template arguments.

For example, one environment might use the default Docker packages, while another may pin versions or provide custom daemon settings.

Basic Example

A minimal playbook for Semaphore looks like this:

- hosts: docker_hosts
  become: true
  roles:
    - geerlingguy.docker

This is a good default for a template that provisions standard Docker hosts.

Example With Common Overrides

The following example is more typical for real usage in Semaphore:

- hosts: app_servers
  become: true
  vars:
    docker_users:
      - deploy

    docker_daemon_options:
      live-restore: true
      log-driver: json-file
      log-opts:
        max-size: "100m"
        max-file: "3"

  roles:
    - geerlingguy.docker

This version installs Docker, ensures a deployment user can run Docker commands, and applies safer daemon defaults for long-running servers.

Important Variables

These are the options Semaphore users are most likely to adjust:

• docker_users Add one or more Linux users to the docker group.

• docker_daemon_options Define Docker daemon settings such as logging, storage driver, registry mirrors, or networking options.

• docker_add_repo Control whether the role should configure the Docker package repository.

• docker_install_compose_plugin Enable installation of the Docker Compose plugin.

• docker_install_compose Install the standalone docker-compose binary instead of relying only on the plugin.

• docker_packages Override the package list if you need a custom or pinned Docker version.

• docker_service_state Control whether Docker should be started.

• docker_service_enabled Control whether Docker should start automatically on boot.

Example: Pinned Docker Version

If you want Semaphore to install a specific Docker version for repeatable builds or controlled upgrades, you can override the package list:

- hosts: ci_runners
  become: true
  vars:
    docker_packages:
      - "docker-ce=5:29.1.3-1~ubuntu.22.04~jammy"
      - "docker-ce-cli=5:29.1.3-1~ubuntu.22.04~jammy"
      - "docker-ce-rootless-extras=5:29.1.3-1~ubuntu.22.04~jammy"
      - "containerd.io=2.2.0-2~ubuntu.22.04~jammy"
      - "docker-buildx-plugin=0.30.1-1~ubuntu.22.04~jammy"
  roles:
    - geerlingguy.docker

This is useful in Semaphore jobs where stability matters more than always pulling the newest available package.

Example: Use Existing Repository Management

If your organization manages repositories separately, disable repo setup in the role:

- hosts: restricted_hosts
  become: true
  vars:
    docker_add_repo: false
  roles:
    - geerlingguy.docker

This is a common pattern in environments with internal mirrors or compliance rules.

Semaphore UI Guidance

When using this role in Semaphore, the usual setup is:

1. Create an inventory with the target hosts.
2. Create a project environment with any shared variables.
3. Add a task template that runs the playbook using privilege escalation.
4. Pass environment-specific Docker settings through variables.

Good candidates for Semaphore environment variables or inventory vars include:

• docker_users
• docker_daemon_options
• docker_add_repo
• docker_install_compose_plugin
• docker_packages

This lets you reuse the same playbook across multiple environments while keeping the behavior controlled from Semaphore.

Operational Notes

There are a few practical details Semaphore users should keep in mind:

• If the role adds users to the docker group, it may reset the SSH connection so new group membership takes effect.
• If you pin exact Docker package versions, upstream repository changes can break future installs.
• If your environment uses custom package mirrors, private repos, or strict firewall settings, you may need to override the default repository-related variables.
• If you need very specific first-start daemon behavior, review your daemon settings carefully before relying on the defaults.

Recommended Fit

This role is a strong choice in Semaphore when your goal is:

• reliable Docker installation
• repeatable infrastructure setup
• fewer manual host changes
• one reusable template for many servers

It is best used as a standard Docker baseline. If your environment is more specialized, the role still provides a solid starting point and can be adapted with variable overrides.

Summary

For Semaphore users, this role is best thought of as a reusable Docker host bootstrap. It takes the common installation and configuration steps that are easy to repeat incorrectly by hand and turns them into a single, consistent automation unit. That makes it especially valuable in environments where the same Docker setup needs to be applied more than once.