NOTE: This document now applies to versions 17 or less of AWX. The process has changed for 18+
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.
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 22.214.171.124 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.
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.
Next check that Docker Desktop has correctly setup Docker within your Ubuntu App
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
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.
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