Installing Ansible AWX on Windows Using WSL 2 & Docker Desktop

Last Updated on 26/09/2021 by Grant Little

NOTE: This document now applies to versions 17 or less of AWX. The process has changed for 18+

Overview

Ansible is an IT Automation tool. I like it because of the power it offers, but with a simple approach and a low learning curve.

As I’ve been migrating from Mac to Windows I’ve needed to find ways to still work with Ansible from Windows. Testing things out in AWX was the next logical step.

I have already written a blog post on how you can install the base Ansible command line tools using WSL. I use that to generally test my playbooks.

Ansible AWX is the open source version of Ansible Tower. So as much as you generally wouldn’t want to run it on a Windows machine for production use cases. It is handy from a development and proof of concept point of view.

Prerequisites

AWX actually runs as a number of Linux Docker containers. Integration between WSL and Docker has been substantially improved with WSL 2 and the latest version of Docker Desktop for Windows. Therefore this post assumes a few prerequisites:-

• Windows 10 version 2014 or later
• Docker Desktop Stable 2.3.0.2 or later (running Linux containers)
• Port 80 available on your Windows machine

We will be installing AWX using local Docker. AWX is installed via Ansible itself. Therefore I suggest you follow my previous article on setting up Ansible on WSL.

This “Docker Desktop WSL 2 backend” article should be followed to get the correct environment setup and to ensure your Ubuntu apps have access to WSL 2.

Instructions

Based on my previous article you should have a Python virtualenv for the Ansible command line. You should source this virtualenv to make sure any commands you use don’t interfere with other applications.

source ~/virtualenvs/ansible/bin/activate

Next check that Docker Desktop has correctly setup Docker within your Ubuntu App

docker ps

If this doesn’t work please see the troubleshooting section below

Next you will need to

pip3 install docker docker-compose

Now you can clone the actual AWX Git repository

git clone https://github.com/ansible/awx.git
cd awx

Checkout the latest tagged version

tag=$(git describe --tags `git rev-list --tags --max-count=1`)
git checkout tags/$tag -b $tag-branch

Next we run the actual install playbook

cd installer
ansible-playbook -i inventory install.yml

This will take some time to complete.

Once the Ansible play completes. You can access the AWX UI via http://localhost on your Windows Desktop

You will like see the following on the first startup:-

This is AWX pre-loading the demo data into its database. It can take 5-10 times for this to complete. However, you can also check the docker logs to see if everything is working. Run the following command:-

docker logs -f awx_task

If you continually see lots of errors like the following appearing then something has gone wrong. Please see the trouble shooting section that follows below.

If everything works as expected, after some time you should get the login prompt in your web browser. You can then use the default username of admin and the password of password to login.

This will then bring you into the default Dashboard page of AWX.

You should also see that your containers are running within Docker Desktop

Trouble Shooting

Docker is not available

After running docker ps you get the following:-

Then open your Docker Desktop settings and ensure your Ubuntu distro is enabled within WSL Integration

Restart your Ubuntu distro application, remembering to source the ansible virtualenv again.

AWX Task Shows Errors

On occasions I have seen an issue where the “awx_task” container fails to initialise correctly. Under the hood the Ansible playbook is creating a local docker compose configuration (within your Ubuntu application). This is typically installed in your home directory. You can manually run this docker-compose configuration to manually start the application again.

cd ~/.awx/awxcompose
docker-compose down
docker-compose up -d

You can then check the docker logs for the awx_task.

docker logs -f awx_task

Generally I find this solves most startup issues.

Conclusion

You should now have Ansible AWX installed and running on your Windows machine (via Docker Desktop).

This means you can now use this to develop and test concepts for ultimate deployment across your environment