# Ansible AWX

## Setup Ansible AWX on fresh Kali Host

1. Install prerequisites. If you're unable to install `docker-compose-plugin`, please see "[Unknown shorthand flag..](#id-1.-unknown-shorthand-flag-f-in-f)" for installation help.

```bash
sudo apt install docker.io docker-compose docker-compose-plugin ansible npm -y
```

2. Create a new user, or add current user to the Docker group. You might need to reload your shell or even restart the host in order to make the changes take effect.

```bash
utv-kali :: ~/ ‹24.3.1*› » sudo usermod -aG docker $USER
or
utv-kali :: ~/ ‹24.3.1*› » sudo useradd awx && sudo passwd awx && sudo usermod -aG docker awx && id awx
```

3. Find latest version and clone it.

```bash
utv-kali :: ~/ » curl -s https://api.github.com/repos/ansible/awx/releases/latest | grep "zipball_url"
utv-kali :: ~/ » git clone -b 24.3.1 https://github.com/ansible/awx.git
```

4. Generate keys for `pg_password`, `broadcast_websocket_secret` and `secret_key`. This is optional, if blank it will be generated upon install.

```bash
utv-kali :: ~/awx » openssl rand -base64 30
NOfNJdZ+Qg04CQmTfJzXrT0gHdDHj5MTALGtRi5H
utv-kali :: ~/awx ‹24.3.1*› » vim tools/docker-compose/inventory
```

5. Build the AWX base image.

```bash
utv-kali :: ~/awx ‹24.3.1*› » make docker-compose-build
utv-kali :: ~/awx ‹24.3.1*› » docker images                                                                                                      1 ↵
REPOSITORY                  TAG       IMAGE ID       CREATED              SIZE
ghcr.io/ansible/awx_devel   HEAD      a70774a6fa8d   About a minute ago   1.95GB
```

6. Start the containers (`COMPOSE_UP_OPTS=-d` to detach). If you encounter error "[Unknown shorthand flag: 'f' in -f](#id-1.-unknown-shorthand-flag-f-in-f)" please see below troubleshooting tips.

```bash
utv-kali :: ~/awx ‹24.3.1*› » make docker-compose COMPOSE_UP_OPTS=-d
utv-kali :: ~/awx » docker container ls
```

7. Clean and build the UI. This may freeze the host for a few minutes depending on your hardware. If you have 4GB RAM or below <mark style="color:red;">**OOM Killer**</mark> will surely kill your process.

```bash
utv-kali :: ~/awx ‹24.3.1*› » docker exec tools_awx_1 make clean-ui ui-devel
```

Wait a few minutes and you should be able to reach the AWX web UI on `https://localhost:8043/#/home`.

8. Lastly create a new superuser, or use the default admin account, to login to the application.

```bash
utv-kali :: ~ » docker container logs 0e2c2dd78493 | grep -i "admin password"
Admin password: eOHr................

utv-kali :: ~/awx ‹24.3.1*› » docker exec -ti tools_awx_1 awx-manage createsuperuser
Username (leave blank to use 'awx'): 
Email address: 
Password: 
Password (again): 
Superuser created successfully.
```

***

## **Troubleshooting:**

### 1. Unknown shorthand flag: 'f' in -f

If you get the error <mark style="color:red;">`unknown shorthand flag: 'f' in -f`</mark> it's probably because you've only installed `docker-compose` (version 1) and not `docker-compose-plugin` (version 2). Verify this by running `docker compose version` and `docker-compose version`.

```bash
utv-kali :: ~/awx ‹24.3.1*› » docker compose version
docker: 'compose' is not a docker command.
utv-kali :: ~/awx ‹24.3.1*› » docker-compose version
docker-compose version 1.29.2, build unknown
```

According to [Kali Documentation](https://www.kali.org/docs/containers/installing-docker-on-kali/), to install `docker-compose-plugin` we need to update `sources.list`, import gpg key and run `apt update`.&#x20;

```bash
utv-kali :: ~/awx ‹24.3.1*› » echo "deb [arch=amd64 signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/debian bookworm stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list 

utv-kali :: ~/awx ‹24.3.1*› » curl -fsSL https://download.docker.com/linux/debian/gpg |
  sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

utv-kali :: ~/awx ‹24.3.1*› » sudo apt update
utv-kali :: ~/awx ‹24.3.1*› » sudo apt install docker-compose-plugin
utv-kali :: ~/awx ‹24.3.1*› » docker compose version
Docker Compose version v2.27.0
```

### 2. Connection refused to web interface

'<mark style="color:red;">Connection refused</mark>' from host machine to the AWX web interface, even though all containers are up and running, and being able to reach the web interface from the container itself. Restarting the containers did not solve the issue, however doing a full reboot of the host system and then start the containers solved the issue for me.

<pre class="language-bash"><code class="lang-bash">utv-kali :: ~/awx ‹24.3.1*› » reboot
<strong>utv-kali :: ~/awx ‹24.3.1*› » docker compose -f tools/docker-compose/_sources/docker-
</strong></code></pre>

***

## Container management:

<mark style="color:green;">Start</mark> / <mark style="color:red;">Stop</mark> / <mark style="color:orange;">Restart</mark> all AWX containers:

```bash
utv-kali :: ~/awx ‹24.3.1*› » docker compose -f tools/docker-compose/_sources/docker-compose.yml start
utv-kali :: ~/awx ‹24.3.1*› » docker compose -f tools/docker-compose/_sources/docker-compose.yml stop
utv-kali :: ~/awx ‹24.3.1*› » docker compose -f tools/docker-compose/_sources/docker-compose.yml restart
```