(Last Updated On: March 1, 2018)

Welcome to our guide on How to Install Ansible AWX on CentOS 7 / Fedora with Nginx Reverse Proxy and Letsencrypt SSL Certificate. This installation will have http to https redirection configured on Nginx.

What is AWX?

AWX is the upstream project from which the Red Hat Ansible Tower which provides a web-based user interface, REST API, and task engine built on top of Ansible. It is the upstream project for Tower, a commercial derivative of AWX. This is an open source community project, sponsored by Red Hat, that enables users to better control their Ansible project use in IT environments.  The AWX source code is available under the Apache License 2.0.

Install Ansible AWX on CentOS 7 / Fedora with Nginx Reverse Proxy and Letsencrypt

Now that you have the basics, let’s dive into the installation steps for AWX on CentOS 7 and Fedora operating systems.  I assume you already have an installed and updated CentOS or Fedora Server. Note that epel is necessary for this installation, you can install epel by running:

# yum -y install epel-release

Install basic dependencies:

Some packages are required ad dependencies by AWX. These can be installed by running the following command on your terminal.

# yum -y install git gcc gcc-c++ lvm2 bzip2 gettext nodejs \
yum-utils device-mapper-persistent-data  ansible python-pip

Install Docker CE:

We had earlier covered the installation of Docker community edition on various Linux distributions. This guide is available at the link: How to install Docker CE on Ubuntu / Debian / Fedora / Arch / CentOS

Install docker python module:

AWX require docker python module. This is installed using pip,

# pip install -U docker-py
# pip show docker-py
Name: docker-py
Version: 1.10.6
Summary: Python client for Docker.
Home-page: https://github.com/docker/docker-py/
Author: Joffrey F
Author-email: joffrey@docker.com
License: UNKNOWN
Location: /usr/lib/python2.7/site-packages
Requires: requests, backports.ssl-match-hostname, docker-pycreds, ipaddress, websocket-client, six

Clone AWX from git

The next step is to clone AWX from git.

# git clone --depth 50 https://github.com/ansible/awx.git
Cloning into 'awx'...
remote: Counting objects: 8886, done.
remote: Compressing objects: 100% (4351/4351), done.
remote: Total 8886 (delta 5573), reused 6866 (delta 4368), pack-reused 0
Receiving objects: 100% (8886/8886), 9.24 MiB | 871.00 KiB/s, done.
Resolving deltas: 100% (5573/5573), done.

Change to installer directory

Since you need to execute ansible playbooks under installer directory, first navigate to this directory.

# cd awx/installer/

Check the inventory file, you can customize as you want:

# cat inventory

Generate admin password

# pwgen 15

Generate AWX secret key

# pwgen -N 1 -s 30
pXc5pYYCECKK5dHEXqV5jawgvkZToK

Modify inventory file with obtained values above. My file looks like this:

# grep -v '^ *#' inventory 
localhost ansible_connection=local ansible_python_interpreter="/usr/bin/env python"

[all:vars]
dockerhub_base=ansible
dockerhub_version=latest
default_admin_user=admin
default_admin_password=ERg0ELvWh5Ia
awx_secret_key=pXc5pYYCECKK5dHEXqE5KawgvkZToK
postgres_data_dir=/var/lib/pgdocker
host_port=8000
docker_compose_dir=/var/lib/awx
pg_username=awx
pg_password=eoco3EeHWeRohwe
pg_database=awx
pg_port=5432
awx_official=true

Execute playbook

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.

# ansible-playbook -i inventory install.yml

If you get an error ImportError: “No module named ‘requests.packages.urllib3’, run:

# pip install requests urllib3 pyOpenSSL --force --upgrade

After some time, the deployment should be complete. You can then check created docker containers and their status using docker ps command.

# docker ps
IMAGE                     COMMAND                  PORTS                                NAMES
ansible/awx_task:latest   "/tini -- /bin/sh ..."   8052/tcp                             awx_task
ansible/awx_web:latest    "/tini -- /bin/sh ..."   0.0.0.0:8000->8052/tcp               awx_web
memcached:alpine          "docker-entrypoint..."   11211/tcp                            memcached
rabbitmq:3                "docker-entrypoint..."   4369/tcp, 5671-5672/tcp, 25672/tcp   rabbitmq
postgres:9.6              "docker-entrypoint..."   5432/tcp                             postgres

5 containers have been created specifically for AWX. These are

  • Memcached container
  • AWX_task container
  • AWS web container
  • Rabbitmq container
  • PostgreSQL container

To manage these containers, use either docker-compose or use docker native commands. The web portal is accessible via host-ip:8000 or port 80 if you didn’t change it. You will get a welcome dashboard similar to one below.

Enter the username and password that you specified in the inventory file. Once you authenticate, you’ll get to AWX administration dashboard,

Configure Nginx Reverse proxy

If you would like to configure Nginx reverse proxy for AWX with http to https redirection, follow next steps. The first thing you have to do is generate SSL certificate for AWX using certbot-auto tool.

Generate Letsencrypt SSL certificate

# wget https://dl.eff.org/certbot-auto -P /usr/local/bin
# chmod a+x /usr/local/bin/certbot-auto
# /usr/local/bin/certbot-auto certonly --standalone -d awx.example.com -d www.awx.example.com\
--preferred-challenges http --agree-tos -n -m emailaddress@domain.com --keep-until-expiring

Once you get ssl certificate, modify below configuration snippet to use with nginx.

# cat /etc/nginx/conf.d/awx.conf 
server
{
 listen 443 ssl http2;
 server_name awx.example.com www.awx.example.com;

location /
 {
   proxy_http_version 1.1;
   proxy_set_header Host $host;
   proxy_set_header X-Real-IP $remote_addr;
   proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
   proxy_set_header X-Forwarded-Proto $scheme;
   proxy_set_header Upgrade $http_upgrade;
   proxy_set_header Connection "upgrade";
   proxy_pass http://192.168.x.x:8000/;
 }

ssl on;
ssl_certificate /etc/letsencrypt/live/awx.example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/awx.example.com/privkey.pem;
ssl_session_timeout 5m;
ssl_ciphers EECDH+CHACHA20:EECDH+AES128:RSA+AES128:EECDH+AES256:RSA+AES256:EECDH+3DES:RSA+3DES:!MD5;
ssl_protocols TLSv1.2;
ssl_prefer_server_ciphers on;

access_log /var/log/nginx/awx.access.log;
error_log /var/log/nginx/awx.error.log;
}

server {
   listen 80;
   server_name awx.example.com www.awx.example.com;
   add_header Strict-Transport-Security max-age=2592000;
   rewrite ^ https://$server_name$request_uri? permanent;
}

Replace example.com with your real domain or subdomain name and put the correct location of SSL certificate. Then finally confirm that nginx configuration is Ok and restart nginx.

# nginx -t
# systemctl restart nginx

Wrapping Up.

You now have a running AWX which you use to administer network devices with Ansible. Hope this guide on Install Ansible AWX on CentOS 7 / Fedora with Nginx Reverse Proxy and Letsencrypt was helpful. The next steps are exploring how AWX dashboard is organized and the basics of using it.