Ansible Pilot

Run the latest Ansible AWX in Docker containers

Ansible AWX is the upstream project of Ansible Automation Controller (fromelly Ansible Tower) providing a modern web-ui and API interface to manage Ansible Playbooks, inventories, Credentials, Valts between your team in your organization.

September 1, 2022
Access the Complete Video Course and Learn Quick Ansible by 200+ Practical Lessons

How to run the latest AWX in Docker containers?

Running AWX in local Docker containers allows you to test the AWX web-UI and API to easily manage Ansible Playbook execution. AWX run on Docker is considered for Testing or Development only, the preferred way is via the AWX Operator since version 18.0. This initial configuration sometimes is a roadblock for some Ansible AWX users. I’m Luca Berton and welcome to today’s episode of Ansible Pilot.

Ansible AWX

AWX is a very modern web UI and API that allows you to manage Ansible Playbooks, Inventories, Credentials, and Vaults between your team in your organization. Running AWX is a convenient way to centralize the storing and execution of all your Ansible resources and grant the relevant permissions only to selected users across your organization. Ansible AWX is the upstream project of Ansible Automation Controller (formerly Ansible Tower). The Ansible Automation Controller is part of the Red Hat Ansible Automation Platform (AAP). Red Hat released the AWX project under the Apache 2.0 Open Source license. Under the hood, it relies on cutting-edge Open Source technologies such as Redis, PostgreSQL, Django, and Python.

demo

How to run AWX in a Docker container. I’m going to show you how to get started on the latest AWX stable version (21.5.0 at the moment). I tested the following procedure on a Fedora 36 workstation. A step-by-step guide on how to build and run the latest Ansible AWX Base Container Image and Ansible Receptor Image and run the UI, crfeate an admin example user.

Prerequisites

Ansible AWX support only x86_64 operating system:

The additional software must be installed:

Please note that the latest Docker technology should be installed in the target system, the Docker service must be started and the current user added in the docker group.

Build Ansible AWX

How to build the Ansible AWX Base Container Image and download the latest Ansible Receptor Image.

  1. Clone the latest stable tag Ansible AWX repository

git clone -b x.y.z https://github.com/ansible/awx.git

Substitute x.y.z with the latest release version number (for example 21.5.0).

  1. Configure the inventory (optional)

You can customize the inventory parameters pg_password, broadcast_websocket_secret, secret_key, and any other settings you need for your deployment.

  1. The Ansible AWX Base Container Image
$ make docker-compose-build

This command builds the AWX base container image (it takes a while and connects to the internet to download dependencies, packages, and libraries).

After a successful execution the docker images command show you a new ansible/awx_devel image:

[[email protected] awx]$ docker images
REPOSITORY                  TAG       IMAGE ID       CREATED         SIZE
ghcr.io/ansible/awx_devel   HEAD      4d593fc25fc2   21 hours ago    1.8GB
  1. The Ansible Receptor Image

The development environment will download the latest devel image from receptor. Verify that the receptor image was successfully downloaded using the docker images command:

[[email protected] awx]$ docker images
REPOSITORY                  TAG       IMAGE ID       CREATED         SIZE
quay.io/ansible/receptor    devel     981db0fc0f90   7 days ago      233MB

Run Ansible in Docker Containers

How to start the Ansible AWX, Ansible Receptor, PostgreSQL and Redis containers.

  1. run the Ansible AWX Base Container Image

The Ansible AWX Base Container Image (previously build) automatically start all required services (PostgreSQL and Redis) and dependent containers.

$ make docker-compose

Your session will be attached to the awx container and start watching for log messages and events in real time when the container was launched.

The first time you start the environment, database migrations runs in order to build the PostgreSQL initial database schema and data.

By default six Docker containers are running on your machine: tools_awx_1, tools_postgres_1, tools_redis_1, tools_receptor_hop, tools_receptor_1, tools_receptor_2.

You can verify the containers running in your system using the docker ps command:

[[email protected] awx]$ docker ps 
CONTAINER ID   IMAGE                            COMMAND                  CREATED        STATUS         PORTS                                                                                                                                                                                                                                                                                                                                                                                NAMES
bce34be76a94   ghcr.io/ansible/awx_devel:HEAD   "/entrypoint.sh rece…"   14 hours ago   Up 2 minutes   22/tcp, 8013/tcp, 8043/tcp, 8080/tcp                                                                                                                                                                                                                                                                                                                                                 tools_receptor_2
c11c7c1114f1   ghcr.io/ansible/awx_devel:HEAD   "/entrypoint.sh rece…"   14 hours ago   Up 2 minutes   22/tcp, 8013/tcp, 8043/tcp, 8080/tcp                                                                                                                                                                                                                                                                                                                                                 tools_receptor_1
05589a6b6185   quay.io/ansible/receptor:devel   "/usr/local/bin/dumb…"   14 hours ago   Up 3 minutes   0.0.0.0:5555->5555/tcp, :::5555->5555/tcp, 7323/tcp                                                                                                                                                                                                                                                                                                                                  tools_receptor_hop
d9570e9d9027   ghcr.io/ansible/awx_devel:HEAD   "/entrypoint.sh laun…"   14 hours ago   Up 3 minutes   0.0.0.0:2222->2222/tcp, :::2222->2222/tcp, 0.0.0.0:6899->6899/tcp, :::6899->6899/tcp, 0.0.0.0:7899-7999->7899-7999/tcp, :::7899-7999->7899-7999/tcp, 0.0.0.0:8013->8013/tcp, :::8013->8013/tcp, 0.0.0.0:8043->8043/tcp, :::8043->8043/tcp, 0.0.0.0:8080->8080/tcp, :::8080->8080/tcp, 22/tcp, 0.0.0.0:8888->8888/tcp, :::8888->8888/tcp, 0.0.0.0:3000->3001/tcp, :::3000->3001/tcp   tools_awx_1
c39fe279ecb2   postgres:12                      "docker-entrypoint.s…"   14 hours ago   Up 3 minutes   5432/tcp                                                                                                                                                                                                                                                                                                                                                                             tools_postgres_1
820ebdc15a10   redis:latest                     "redis-server /usr/l…"   14 hours ago   Up 3 minutes   6379/tcp                                                                                                                                                                                                                                                                                                                                                                             tools_redis_1
[[email protected] awx]$

Run Ansible AWX in Docker containers

Access the Ansible AWX Web UI

The Ansible AWX Web-UI is available at the URL https://localhost:8043/.

A succesful connection with your browser is going to show you the following login screen (https://localhost:8043/#/login).

Run Ansible AWX UI in Docker containers

Access the Ansible AWX Web API

The Ansible AWX API is available at the URL https://localhost:8043/api/.

A succesful connection with your browser is going to show you the following API endpoint (https://localhost:8043/api/). The Ansible AWX API is a Browsable API so easy to navigate via browser. Please note that some API endpoints requires authentication.

Access the Ansible AWX API in Docker containers

Create an Ansible AWX Admin User

Ansible AWX admin user enables you to access the Ansible AWX Web-UI and the Ansible AWX API endpoints that require authentication. The user creation is performed using the docker exec command using the awx-manage utility:

$ docker exec -ti tools_awx_1 awx-manage createsuperuser

A successful execution to create the example user is follows:

[[email protected] awx]$ docker exec -ti tools_awx_1 awx-manage createsuperuser
Username: example
Email address: [email protected]
Password: 
Password (again): 
Superuser created successfully.
[[email protected] awx]$

Once a superuser is successfully created you can access the Ansible AWX Web-UI and Ansible API autenticated endopoints.

Login in the Ansible AWX Web UI

The Ansible AWX Web UI Dashboard

The direct API endpoint is https://localhost:8043/api/login/.

Login in the Ansible AWX API

The current authenticated user is shown in the top Logged in as example.

The Ansible AWX API Authenticated

Stop the Ansible AWX Docker containers

You can use the docker stop command when you want to stop the six Docker containers of Ansible AWS on your machine: tools_awx_1, tools_postgres_1, tools_redis_1, tools_receptor_hop, tools_receptor_1, tools_receptor_2.

[[email protected] awx]$ docker stop tools_awx_1 tools_receptor_2 tools_receptor_1 tools_receptor_hop tools_redis_1 tools_postgres_1
tools_awx_1
tools_receptor_2
tools_receptor_1
tools_receptor_hop
tools_redis_1
tools_postgres_1
[[email protected] awx]$

An empty list provided by docker ps command should confirm the succesful Docker containers shutdown:

[[email protected] awx]$ docker ps
CONTAINER ID   IMAGE     COMMAND   CREATED   STATUS    PORTS     NAMES
[[email protected] awx]$ 

Recap

Now you know how to Build, Run and Stop the latest Ansible AWX web-ui and API in Docker containers. Included code how to create a superuser account.

Subscribe to the YouTube channel, Medium, Website, Twitter, and Substack to not miss the next episode of the Ansible Pilot.

Academy

Learn the Ansible automation technology with some real-life examples in my

My book Ansible By Examples: 200+ Automation Examples For Linux and Windows System Administrator and DevOps

BUY the Complete PDF BOOK to easily Copy and Paste the 200+ Ansible code

Want to keep this project going? Please donate

Access the Complete Video Course and Learn Quick Ansible by 200+ Practical Lessons
Trustpilot
Follow me

Subscribe not to miss any new releases

FREE Top 10 Best Practices

Top 10 Best Practices of Ansible Automation: save time, reduce errors and stress