Getting started

This section introduces the Docker Ansible workflow: choose an image, mount your project, run Ansible commands, and optionally add shell aliases for daily use.

The images are published as willhallonline/ansible and bundle ansible-core, the ansible community package, and ansible-lint. They are designed for local machines and CI/CD systems where you want a consistent Ansible control environment without installing Python or Ansible directly on the host.

What you need

You need Docker and an Ansible project directory. The examples assume commands are run from the root of your Ansible repository or playbook directory.

The basic workflow

A typical run looks like this:

1. Pick an image tag.
2. Mount your current directory into the container.
3. Mount any SSH key needed to reach managed hosts.
4. Run a shell, ansible, ansible-playbook, or ansible-lint inside the container.

docker run --rm -it \
  -v $(pwd):/ansible \
  -v ~/.ssh/id_rsa:/home/ansible/.ssh/id_rsa \
  willhallonline/ansible:latest \
  ansible-playbook playbook.yml

The container gives you the Ansible tools. Your repository, inventory, playbooks, roles, and configuration still live on your host filesystem.

Start here

• Quick start

  ---

  Pull and run the image, mount your project, and execute a playbook directly.

  Read the quick start

• Choosing an image

  ---

  Understand image tags, base OS choices, convenience tags, and version pinning.

  Choose an image

• Shell aliases

  ---

  Add reusable commands for interactive work and one-off Ansible invocations.

  Configure aliases

Which command should I run?

Use the command that matches what you want to do.

Open a shellRun from a projectRun a playbook

docker run --rm -it willhallonline/ansible:latest /bin/sh

This is useful when you want to inspect the image or try commands manually.

docker run --rm -it \
  -v $(pwd):/ansible \
  -v ~/.ssh/id_rsa:/home/ansible/.ssh/id_rsa \
  willhallonline/ansible:latest \
  /bin/sh

This mounts the current directory at /ansible and makes an SSH private key available inside the container.

docker run --rm -it \
  -v $(pwd):/ansible \
  -v ~/.ssh/id_rsa:/home/ansible/.ssh/id_rsa \
  willhallonline/ansible:latest \
  ansible-playbook playbook.yml

This runs ansible-playbook directly instead of starting an interactive shell.

Image naming in one minute

Tags follow this pattern:

<ansible-version>-<os>

Examples:

2.21-alpine-3.24
2.19-debian-bookworm
2.20-ubuntu-24.04
2.18-rockylinux-10
2.19-debian-bookworm-slim
2.21-debian-trixie
2.21-debian-trixie-slim

Convenience tags are also available:

Tag	Meaning
latest	Ansible 2.21 on Alpine 3.24
alpine	Ansible 2.21 on Alpine 3.24
ubuntu	Ansible 2.21 on Ubuntu 24.04

Pin tags for automation

Convenience tags can move when the default image changes. Use fully qualified tags in CI/CD and other repeatable workflows.

Current Ansible versions

The current Ansible core versions available in containers are:

• 2.21.4
• 2.20.9
• 2.19.13
• 2.18.19

Ansible core streams 2.9 through 2.17 are outside the active matrix and unmaintained. If you have a legacy dependency, verify its image availability and review older releases before planning an upgrade.

Choosing a base OS

The base image affects package compatibility, size, and how closely the container matches your target systems.

Base OS	Good for
Alpine	Small images and fast pulls
Debian slim	A balanced default with glibc in a smaller image
Debian	Debian-like environments and broader base utilities
Ubuntu	Matching Ubuntu-based automation or CI expectations
Rocky Linux	Matching Enterprise Linux-style environments

For a guided decision, read choosing an image.

Multi-architecture support

Current tags generally publish AMD64 and ARM64 variants, but manifests are tag-specific. For example, 2.21-ubuntu-24.04 is AMD64-only. No ARMv7/32-bit ARM images are published, so inspect the selected tag before relying on ARM64 in CI.

See architectures for more detail.

Recommended path through the docs

If this is your first visit, use this order:

1. Quick start
2. Choosing an image
3. Shell aliases
4. Running playbooks
5. SSH keys and authentication
6. ansible-lint
7. CI overview

Common questions before you begin

Do I need Ansible installed on the host?

No. The container provides ansible-core, the ansible community package, and ansible-lint. You only need Docker on the host.

Where should my playbooks live?

Keep them in your normal project directory. Mount that directory into the container with -v $(pwd):/ansible.

Should I use latest?

latest is fine for quick experiments. For CI/CD or team documentation, pin a tag such as 2.21-alpine-3.24, 2.21-debian-trixie-slim, or another exact version that matches your project needs.

Where do I go for CI/CD examples?

Start with the CI overview, then choose your platform: GitHub Actions, GitLab CI, Azure Pipelines, or another supported CI provider.