As a system administrator, chances are that there are some tasks that you do repetitively every single day that takes up a lot of your time that could have been invested elsewhere. What if you could solve problems once and then automate your solutions going forward? That is what Ansible is good at and once you get to see its benefits, you will never look back again. Ansible is a simple, yet powerful IT automation engine that thousands of companies are using to drive complexity out of their environments and accelerate DevOps initiatives.

Be it the deployment of applications, routine maintenance of your servers, Configuration Management, Continuous Delivery, Orchestration or any repetitive work that you can describe, Ansible can handle it for you. To add beauty to this beast, AWX (Ansible Web eXecutable) provides a web-based user interface, REST API, and task engine built on top of Ansible. The AWX Project is an open source community project, sponsored by Red Hat, that enables users to better control their use of Ansible project in IT environments. AWX is the upstream project from which the Red Hat Ansible Tower offering is ultimately derived.

“Don’t wait. The time will never be just right.”
–Napoleon Hill


Before you can run a deployment, you’ll need the following installed in your local environment

  • Ansible Version 2.8+
  • A recent version of Docker
  • docker Python module
  • GNU Make
  • Git Version 1.8.4+
  • Python 3.6+
  • Node 10.x LTS version

We should be now ready to roll up our sleeves, put on our boots and get to work.

Step 1: Install Epel Release Repo and Dependencies

We need packages from Epel repository, so let us install it as follows:

sudo dnf -y install epel-release
sudo dnf -y install dnf-plugins-core
sudo dnf -y install
sudo dnf config-manager --set-enabled PowerTools

AWX has some packages required as dependencies. We can have all of them installed by running the command below.

sudo dnf install -y git python3-pip curl ansible gcc nodejs gcc-c++  gettext lvm2 device-mapper-persistent-data pwgen bzip2

Disable SELinux

This is optional if you can handle SELinux with ease. To disable it, run the command below and reboot your server.

sudo sed -i 's/^SELINUX=.*/SELINUX=permissive/g' /etc/selinux/config
sudo setenforce 0

Step 2: Install Docker and Docker Compose

AWX is supported and can only be run as a containerized application using Docker images deployed to either an OpenShift cluster, a Kubernetes cluster, or docker-compose. We shall use Docker in this guide to get us AWX up and running.

First, download Docker repository file to /etc/yum.repos.d/docker-ce.repo and update RPM index cache before installing Docker.

sudo curl -o /etc/yum.repos.d/docker-ce.repo
sudo yum makecache 
sudo dnf -y  install docker-ce --nobest

Start and enable Docker Service to start at boot and check if it is running

$ sudo systemctl enable --now docker
$ systemctl status  docker

● docker.service - Docker Application Container Engine
   Loaded: loaded (/usr/lib/systemd/system/docker.service; enabled; vendor preset: disabled)
   Active: active (running) since Mon 2020-07-27 20:21:51 UTC; 5s ago
 Main PID: 52836 (dockerd)
    Tasks: 22
   Memory: 49.8M
   CGroup: /system.slice/docker.service
           ├─52836 /usr/bin/dockerd -H fd://
           └─52843 containerd --config /var/run/docker/containerd/containerd.toml --log-level info

The docker group is created, but no users are added to the group. Add your user to this group to run docker commands without sudo.

sudo usermod -aG docker $USER

Find out more about Installing Docker and Docker Compose on CentOS 8 guide to get both Docker and docker-compose installed on your Cent0S 8 server.

Next, we shall use pip3 command to get docker-compose and docker python module installed as shown below.

sudo pip3 install -U docker docker-compose

Confirm installed version.

$ docker-compose version
 docker-compose version 1.26.2, build unknown     
 docker-py version: 4.2.2
 CPython version: 3.6.8
 OpenSSL version: OpenSSL 1.1.1c FIPS  28 May 2019

Step 3: Clone AWX from git

So far, we have covered all the prerequisites that AWX needs to breath. We can finally safely clone and install Ansible AWX. Let us get AWX’s files from Git using the command below.

cd ~
git clone --depth 50

Change to installer directory

The installer directory has a config file we need to modify and execute, therefore, navigate into the directory.

cd ~/awx/installer/

Before we edit the inventory file, generate a secret encryption key we shall use by running the command below.

$ pwgen -N 1 -s 30

Edit the inventory file and customize it to suit the needs of your environment.

$ vim inventory

project_data_dir=/var/lib/awx/projects  ##Directory For playbooks inside the server 

Alter Firewall Rules

In case you have Firewalld running, add-masquerade and allow http and https services. This is very important, do not skip it. In case you changed the port in the previous inventory file, allow it in your firewall as well.

sudo firewall-cmd --zone=public --add-masquerade --permanent
sudo firewall-cmd --permanent --add-service={http,https}
sudo firewall-cmd --reload

Add AWX project data folder

If you need access to the location where AWX stores the projects (/var/lib/awx/projects in this case) it manages from the docker host, you can set this to turn it into a volume for the container. Since we added the directory in the inventory file to keep playbooks you want to load from the server, let us create the directory as shown below. Please note that it is inside the directory that you will create other directories to hold your playbooks.

sudo mkdir -p /var/lib/awx/projects

If you would wish to create a new project, you simply create a directory inside there. For example, to create a playbook to install Nginx, I would name my directory named say, Nginx, then create a playbook inside it.

cd /var/lib/awx/projects
sudo mkdir Nginx

Execute playbook

After all settings are good, run the install Ansible Playbook to deploy the AWX docker containers. Run ansible-playbook command followed by option -i which tells it the inventory file to use. The name of the playbook file is install.yml.

sudo ansible-playbook -i inventory install.yml
Awx ansible output

The above command will take some time to complete. After it is done you can then check created docker containers and their status using the docker ps command.

$ docker ps

CONTAINER ID        IMAGE                COMMAND                  CREATED             STATUS              PORTS                  NAMES       
feb21b5e6c62        ansible/awx:13.0.0   "tini -- /usr/bin/la…"   3 minutes ago       Up 24 seconds       8052/tcp               awx_task    
423d8c6e4550        ansible/awx:13.0.0   "tini -- /bin/sh -c …"   3 minutes ago       Up 22 seconds>8052/tcp   awx_web     
11d2953d4f67        postgres:10          "docker-entrypoint.s…"   3 minutes ago       Up 22 seconds       5432/tcp               awx_postgres
724d5c4f8162        redis                "docker-entrypoint.s…"   3 minutes ago       Up 25 seconds       6379/tcp               awx_redis   

Step 4: Access AWX Web Interface

To have access to AWX web console, point your browser to your Ansible’s AWX server IP: http://your-server-ip-address. In case you changed the port configuration in the inventory file, then point your browser to http://your-server-ip-address:<port>

You should be welcomed to a Login page well illustrated below.

Awx ansible login page 1

Once open, enter the admin username and admin_password password that you specified in the inventory file. Once the authentication is successful, you’ll get to AWX administration dashboard. Therein, there is a lot of stuff to do and we shall cover just a few. Along the left side of the Dashboard is the navigation menu, where you can quickly navigate to your Projects, Inventories, Job Templates, and Jobs

Awx ansible login dashboard 2

Step 5: Create User and Team

AWX provides a default user called admin that you can use to do your tests. But if you are need a different user, you can create another one.

To add a new user apart from the admin one you find by default, click on Users tab found on the left menu. A new page will be displayed where you can add a new user. Click on the green + icon then fill in the details of the new user to be added.

AWX 1 Create a new user to add to organization 1

After you are done, click “Save“.

AWX Create a new user to add to organization

The same applies for creating a new Team. Click on “Teams” tab found on the left menu. A new page will be displayed where you can add a new team. Click on the green + icon then fill in the details of the new team to be added.

AWX 1 Create a new Team to add to organization

After you are done, click “Save“.

AWX 2 Create a new Team to add to organization

Step 6: Create an Organization

An organization is a logical collection of users, teams, projects, and inventories. It is the highest level object in the AWX object hierarchy. From the left navigation bar, click the Organizations icon. You will find that a default organization has been automatically created and is available to all users of Ansible AWX.

Awx ansible dashboard organization 3

It can be used as is or edited as needed. Let us edit it by changing its name and adding users, permissions and more.

Awx ansible dashboard organization edit 4

Click on the “Users” tab and add a new user. I had not created a new user before, so admin default user appears. But you can create other users as shared in Step 5.

Awx ansible dashboard organization add user 5

If you had other users, they would be populated therein

Awx ansible dashboard organization add user 6 1

Clicking on Users displays all the Users associated with this Organization. A User is someone with access to Ansible AWX with associated roles and Credentials. Adding a user to an organization adds them as a member only, specifying a role for the user can be done in the the Permissions tab, as shown in the example below:

Awx ansible dashboard organization add permissions 7

Step 7: Create credentials

In order for Ansible to log in and execute tasks, it will need credentials to access the remote hosts. AWX provides this feature for us. Click on “Credentials” on the left menu and then click the green + to add a new server credential.

AWX 1 Create a new Credential to add to organization

Fill in the name, description, organization, username, password and the type of credential which is a long list. We shall choose machine since we intend to configure a single host in this example. You can add your ssh keys in case you prefer key-based authentication mechanism. Also add privilege escalation below to sudo.

AWX 2 Create a new Credential to add to organization

Click “Save” once done.

AWX 3 Create a new Credential to add to organization done

Step 8: Create a new Inventory and add it to the Organization

An inventory is a collection of hosts managed by Ansible. Inventories are assigned to organizations, while permissions to launch playbooks against inventories are controlled at the user and/or team level.

To create and review existing inventories click the Inventories icon from the left navigation bar. To create a new inventory, click the add (+) button and select Inventory from the drop-down menu list.

AWX 1 Create a new Inventory to add to organization

Enter the name and Organization that this Inventory will belong to. Click “Save” so that the other tabs can be activated.

AWX 2 Create a new Inventory to add to organization 1

For this example, we are going to add one host but know that you can create a group that contains one or more hosts you would wish to execute something on them simultaneously. Click on “Hosts” tab and click on + to add a new host.

AWX 3 Create a new Inventory host to add to organization

On the new page loaded, add an IP or resolvable hostname and a description. We are going to install nginx on the given host in this example thus the intuitive name.

AWX 4 Create a new Inventory host to add to organization

Click “Save” once done and the new Inventory should be created.

AWX 5 Click on the new Inventory host

The concept of Groups and Hosts

Note that inventories are divided into groups and hosts. A group might represent a particular environment (e.g. “Datacenter 1” or “Testing Bed”), a server type (e.g. “Web Servers” or “DB Servers”), or any other representation of your environment.

Step 9: Setting up a Project

A Project is a logical collection of Ansible playbooks, represented in Ansible AWX. You can manage playbooks and playbook directories by either placing them manually under the Project Base Path on your Ansible AWX server, or by placing your playbooks into a source code management (SCM) system supported by Ansible AWX, including Git, Subversion, and Mercurial.

To create a new project, follow the same procedure as the rest we have seen thus far. Click on the “Projects” tab on the left menu and then click on add(+) to create a new project.

AWX 1 Create a new project for our organization

Once there, fill the details to suit your needs. On the Source Control Manager (SCM) type, you can create a git repo that has all of your playbooks or create a local folder on your server as advised when you choose manual under SCM type. I preferred adding a git repo in this example. Note that we are still referring to the Organization of your choice in case you have several.

AWX 2 Create a new project for our organization

Enter all the details then click “Save“. The file created on the git repo (nginx.yml) has the following:

- hosts: all
  gather_facts: true
  become: true
  become_user: root
    - apt:
        name: nginx
      when: ansible_os_family == "Debian"

Attached screenshot below:

Nginx Git yaml

Step 10: Setting up a template and launching it

Thus far, we have done a lot and what remains is putting it all together into a template. A job template combines an Ansible playbook from a project and the settings required to launch it. Create a new job template by clicking on “Templates” tab on the left navigation menu. Click on he green add (+) to add a new template just like the others. When the window opens, it is just a matter of picking the Inventory, Project, Credential and Playbook we had already configured in the previous steps. Give your template a name and an optional description as well.

AWX 7 Add a new template details

When done scroll down and hit “Save“. Once you save, you can “Launch” it as a job immediately.

AWX 8 Add a new template details save and launch

Once you hit Launch you will be redirected to the “Jobs” page where you will see it executing live with output being displayed as it happens.

Nginx Playbook running

If everything goes well, the playbook should be run successfully by Ansible behind the scenes. All errors encountered along the way will be displayed on the right side.

Nginx Playbook successful

Login to the server being tested on and check if nginx was installed successfully

Nginx in debian10 running

Amazing stuff, Ansible AWX installation is officially setup and running properly.

More about Ansible Tower | AWX can be found on RedHat’s Ansible Tower Quick Start Guide.

Ansible Learning courses:

To Conclude

Ansible can change the way you handle your day to day administration tasks and it can offload a lot of manual work from your hands and gift you with ample time for other tasks. Leverage this technology as your innovation engine, and deliver your applications faster and win big.

Other electrifying guides you might enjoy include:

Manage Users and Groups on Linux using Ansible

How To Generate Linux User Encrypted Password for Ansible

Install Apache Tomcat 9 on Debian 10 With Ansible

How To Install Ansible AWX on Debian 10 (Buster)

Set up Ansible AWX on Ubuntu Linux

Deploy Kubernetes Cluster with Ansible & Kubespray

Your support is our everlasting motivation,
that cup of coffee is what keeps us going!

As we continue to grow, we would wish to reach and impact more people who visit and take advantage of the guides we have on our blog. This is a big task for us and we are so far extremely grateful for the kind people who have shown amazing support for our work over the time we have been online.

Thank You for your support as we work to give you the best of guides and articles. Click below to buy us a coffee.


Please enter your comment!
Please enter your name here