This article will showcase the steps how to deploy docker container using Ansible on a remote Linux machine. This will enable us to automate the process of Docker container deployment, when required, on a multiple remote Linux hosts, with a preset of environment variables and configs for the needed Docker container.


In order to successfully deploy Docker container using Ansible on a remote Linux machine, there are following prerequisites that are required:

  • Docker installed and running on the remote host/target - also can be installed with Ansible or run the official Docker install script.
  • SSH access enabled on the remote hosts with the login parameters preset in the Ansible hosts file
  • Ansible installed on client machine(your machine)
  • Installed Python docker module for Ansible on target machine
  • Installed Python on the target machines and on your local machine

Install Python Docker module for Ansible

Most Linux distros have Python3 preinstalled but for others the Python Docker module that Ansible uses may be missing. You’ll know that it’s if you get an error mentioning that the module is missing or not found. Picture example of the error bellow:

deploy docker container using ansible

The mentioned module is actually the Docker SDK that Python uses to work with Docker. The easiest way to install the Python Docker module is with the “pip” tool. If the “pip” tool is missing, you can easily install and then with it to install the python docker module:


sudo apt install python3-pip


sudo dnf install python3-pip


sudo yum python3-pip

After you installed the pip, then run the command to install docker module:

pip3 install docker

If by any chance, you encounter an error in Ansible that the it cannot find the Python module, add a python interpreter variable in your hosts file. In most cases it’s located either in "/usr/bin/python3" or "/usr/lib/python3".

Error looks something like this:

deploy docker container using ansible

The interpreter variable in the hosts file looks something like this:


Write down the hosts in the hosts file with the login parameters

First step - Adding the necessary parameters in hosts file so that the Ansible can reach, login and interact with our machine:

sudo nano /etc/ansible/hosts

In the hosts file, add the parameters to look something like this:

deploy docker container using ansible

After the necessary parameters for our remote host are added, save the file and exit.

Ansible playbook for Docker container deployment

Next step - Create the playbook which we’ll run to deploy the Docker container. In the following example, we’ll deploy Nginx web server container, so the playbook will look something like this:

- hosts: docker
  - name: deploy nginx docker container
      image: nginx:stable
      name: nginx
      state: started
      auto_remove: true
        - "8080:80"

Playbook file breakdown:

  • “hosts: docker” - host target group, in this case the playbook will only target hosts that belong in the group docker
  • “tasks:”
  • “name: deploy nginx docker container” - Specified a task that needs to be run at the target group and gave it name
  • “docker_container:” - Calling the docker command that manages the docker containers and images
  • “image: nginx:stable” - Specified what docker image to pull from the Docker hub
  • “name: nginx” - Environment variable to specify the docker container name
  • “state: started” - Environment variable to start the docker instantly after the deployment
  • “auto_remove: true” - Environment variable that specified the container will be removed automatically when the container stops
  • “ports: - “8080:80” - Environment variable to expose container ports

deploy docker container using ansible

Run the Ansible docker container playbook:

ansible-playbook deploy-docker-container -l docker

Expected result:

deploy docker container using ansible

deploy docker container using ansible

deploy docker container using ansible

Essentially, format and syntax writing for deploying Docker containers with Ansible is same as you write Docker compose file to deploy containers(since both use .yaml format).

Another example we’ll show how to deploy a Docker container with data persistence. For the example, we used Portainer:

- hosts: docker
  - name: Deploy Portainer
      name: portainer
      image: portainer/portainer-ce
        - "9000:9000"
        - "8000:8000"
        - /var/run/docker.sock:/var/run/docker.sock
        - portainer_data:/data
      restart_policy: always


We have performed the following steps in this post - run the procedure how to deploy Docker container using Ansible on a remote Linux machine which consists of the following steps:

  • Create the hosts file with the remote Linux machines
  • Wrote the Ansible Docker container playbook and specified which container to run
  • Ran the playbook with the successful result of a deployed Docker container

Thank you for your time…