Docker Compose Installation

The Docker Compose installation method provides a complete AWX development environment that runs locally on your machine. This method is designed exclusively for development, testing, and demonstration purposes.

The Docker Compose installation path is only recommended for development/test-oriented deployments and has no official published release. Never use this method for production environments.

For production deployments, use the AWX Operator installation method.

Overview

The Docker Compose development environment:

Runs AWX and all dependencies (PostgreSQL, Redis) in containers
Bind-mounts your local source code for real-time development
Provides hot-reloading for code changes
Includes development tools and debugging capabilities
Supports multi-node cluster configurations for testing
Integrates with external services (Splunk, Vault, Prometheus, etc.) for testing

Prerequisites

Before setting up the development environment, ensure you have the following installed:

Docker

Docker Engine must be installed and running on your host machine.

Linux
macOS
Windows

Install Docker CE for your distribution:

After installation, start the Docker service and add your user to the docker group:

sudo systemctl start docker
sudo systemctl enable docker
sudo usermod -aG docker $USER

Log out and back in for group changes to take effect.

Verify Docker installation:

docker --version
docker ps

Docker Compose

Docker Compose is required to orchestrate multiple containers.Docker Desktop users: Docker Compose is included.Linux users: Install the docker-compose plugin or standalone binary:

# Using pip
pip3 install docker-compose

# Or using your package manager
sudo apt-get install docker-compose  # Debian/Ubuntu
sudo dnf install docker-compose      # Fedora

Verify installation:

docker compose version

Ansible

Ansible is used to template configuration files for docker-compose.

# Using pip
pip3 install ansible

# Or using your package manager
sudo apt-get install ansible  # Debian/Ubuntu
sudo dnf install ansible      # Fedora

Verify installation:

ansible --version

OpenSSL

OpenSSL is required for generating SSL certificates.Most systems have OpenSSL pre-installed. Verify:

openssl version

System Resources

Ensure your system has adequate resources:

CPU: 4+ cores recommended
RAM: 8GB minimum, 16GB recommended
Disk: 20GB+ free space
OS: Tested on Fedora, Ubuntu LTS (18, 20), RHEL 8, CentOS Stream 8, macOS 11

Getting Started

Clone the AWX repository

Clone the AWX repository from GitHub. It’s recommended to clone a stable release tag rather than the latest commit:

# View available releases
# https://github.com/ansible/awx/releases/latest

# Clone a specific release (replace x.y.z with the version)
git clone -b x.y.z https://github.com/ansible/awx.git
cd awx

Deploying from HEAD (or the latest commit) is not stable. Proceed at your own risk if you choose to use the development branch.

For development work, clone the devel branch:

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

Build the development image

Build the AWX development Docker image:

make docker-compose-build

This builds the ansible/awx_devel image containing:

Operating system dependencies
Python environment with AWX requirements
Development tools
Symbolic links to your local source code

The build process may take 10-20 minutes depending on your internet connection and system performance.

Skip building: To use the latest pre-built image from GitHub Container Registry instead of building locally:

# Pull the latest devel image
docker pull ghcr.io/ansible/awx_devel:devel

Then proceed directly to starting the containers.

Customize configuration (optional)

Edit the inventory file to customize your development environment:

vim tools/docker-compose/inventory

tools/docker-compose/inventory

localhost ansible_connection=local ansible_python_interpreter="/usr/bin/env python3"

[all:vars]

# AWX-Managed Database Settings
# If left blank, these will be generated upon install.
# Values are written out to tools/docker-compose/_sources/secrets/
# pg_password=""
# broadcast_websocket_secret=""
# secret_key=""

# External Database Settings
# pg_host=""
# pg_password=""
# pg_username=""
# pg_hostname=""

# awx_image="ghcr.io/ansible/awx_devel"
# migrate_local_docker=false

Most users can use the default configuration. Custom settings are only needed for external databases or specific development scenarios.

Start the development environment

Start all AWX containers and services:

make docker-compose

This command:

Creates and starts the AWX, PostgreSQL, and Redis containers
Runs database migrations
Builds the UI (if not already built)
Attaches your terminal to the AWX container logs

You’ll see output from Django and the frontend build process. Wait for migrations to complete:

awx_1        | Operations to perform:
awx_1        |   Synchronize unmigrated apps: solo, api, staticfiles, messages...
awx_1        |   Apply all migrations: sso, taggit, sessions, sites, main...
awx_1        | Running migrations:
awx_1        |   Applying contenttypes.0001_initial... OK
awx_1        |   Applying auth.0001_initial... OK
awx_1        |   ...

The first startup takes several minutes as the database is initialized and migrations run.

Building the UI

The AWX web interface must be built separately. This requires Node.js and npm on your local machine (not inside the container).

Install Node.js and npm

Install the required Node.js version. Check the ansible-ui README for the exact version requirements.

# Using nvm (recommended)
nvm install 18
nvm use 18

# Or using your package manager
# Ubuntu/Debian
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

# Fedora
sudo dnf install nodejs npm

Build the UI

On your local machine (outside the container):

make clean-ui ui

This clones the ansible-ui repository into awx/ui/src and builds the static files. When containers start, awx-manage collectstatic copies these files to the proper location.

Use local UI repo (optional)

To use a locally cloned ansible-ui repository for UI development:

UI_LOCAL=/path/to/ansible-ui make ui

For more information on UI development, see the ansible-ui contributing guide.

Accessing AWX

Once the containers are running and migrations are complete:

Web Interface
API

Access the AWX web interface at:

https://localhost:8043/

You’ll see a browser warning about the self-signed SSL certificate. This is expected in the development environment.

Access the REST API at:

https://localhost:8043/api/v2/

The API is browsable in your web browser and provides a complete interface to AWX functionality.

Create an Admin User

Before logging in, create an admin superuser:

docker exec -ti tools_awx_1 awx-manage createsuperuser

Follow the prompts to set:

Username (e.g., admin)
Email address
Password

Remember these credentials - you’ll use them to log into the web interface.

Load Demo Data (Optional)

For testing, you can load demo projects, inventories, and job templates:

docker exec tools_awx_1 awx-manage create_preload_data

This creates sample data to help you explore AWX features.

Development Workflow

Working with the Source Code

Your local AWX source tree is bind-mounted into the container at /awx_devel. Changes you make to Python code, templates, or other files are immediately available inside the container.

Start a shell in the container

To run commands or explore inside the AWX container:

docker exec -it tools_awx_1 bash

From this shell, you can:

Run management commands: awx-manage <command>
Inspect logs: tail -f /var/log/supervisor/*
Test database queries: awx-manage dbshell
Run Python interactively: awx-manage shell

Run management commands

Execute AWX management commands from your host:

# List all management commands
docker exec tools_awx_1 awx-manage help

# Run migrations
docker exec tools_awx_1 awx-manage migrate

# Create a superuser
docker exec tools_awx_1 awx-manage createsuperuser

# Collect static files
docker exec tools_awx_1 awx-manage collectstatic --noinput

# Open Django shell
docker exec -it tools_awx_1 awx-manage shell

View logs

Monitor AWX logs in real-time:

# Follow all supervisor logs
docker exec tools_awx_1 tail -f /var/log/supervisor/*

# View specific service logs
docker exec tools_awx_1 tail -f /var/log/supervisor/awx-web.log
docker exec tools_awx_1 tail -f /var/log/supervisor/awx-task.log

Restart services

After making code changes, restart AWX services:

docker exec tools_awx_1 supervisorctl restart all

# Or restart specific services
docker exec tools_awx_1 supervisorctl restart awx-web
docker exec tools_awx_1 supervisorctl restart awx-task

Using docker-compose-test

For more control over the development environment, start the containers without automatically launching services:

make docker-compose-test

This drops you into a shell inside the AWX container. Manually bootstrap and start services:

# Inside the container
/usr/bin/bootstrap_development.sh  # Run migrations and setup
/usr/bin/launch_awx.sh             # Start all services

launch_awx.sh automatically calls bootstrap_development.sh, so you can skip the first command if you just want to start services.

Advanced Configuration

Cluster Mode

Test AWX in a multi-node cluster configuration:

# Start a 3-node control plane cluster
CONTROL_PLANE_NODE_COUNT=3 make docker-compose

# Start with control and execution nodes
MAIN_NODE_TYPE=control EXECUTION_NODE_COUNT=2 make docker-compose

# Complex topology
CONTROL_PLANE_NODE_COUNT=2 EXECUTION_NODE_COUNT=3 make docker-compose

This creates a mesh topology with:

Multiple AWX control plane nodes
Execution nodes (receptor containers)
A hop node connecting execution nodes to control plane

Detached Mode

Run containers in the background:

make docker-compose COMPOSE_UP_OPTS=-d

View logs separately:

docker compose -f tools/docker-compose/_sources/docker-compose.yml logs -f

Custom Image Tag

Use a specific image tag or branch:

COMPOSE_TAG=devel make docker-compose

Disable Color Output

Useful for CI environments:

DJANGO_COLORS=nocolor COMPOSE_UP_OPTS="--no-color" SUPERVISOR_ARGS="-n -t" make docker-compose

Integration Testing

The development environment supports integration with external services for testing:

Splunk
HashiCorp Vault
Prometheus & Grafana
OpenTelemetry & Loki
Minikube

Test external logging with Splunk:

SPLUNK=true make docker-compose

After containers start, configure AWX to forward logs:

export CONTROLLER_USERNAME=admin
export CONTROLLER_PASSWORD=<your-password>
ansible-playbook tools/docker-compose/ansible/plumb_splunk.yml

Access Splunk at http://localhost:8000 (credentials: admin/splunk_admin).

Test credential management with Vault:

VAULT=true make docker-compose

Unseal Vault after starting:

ansible-playbook tools/docker-compose/ansible/unseal_vault.yml

Configure AWX to use Vault:

export CONTROLLER_USERNAME=admin
export CONTROLLER_PASSWORD=<your-password>
ansible-playbook tools/docker-compose/ansible/plumb_vault.yml

Test metrics collection:

PROMETHEUS=true GRAFANA=true make docker-compose

Access Grafana at http://localhost:3001 for AWX metrics dashboards.

Test observability stack:

OTEL=true GRAFANA=true LOKI=true PROMETHEUS=true make docker-compose

AWX logs are exported to Loki via OpenTelemetry Collector and can be viewed in Grafana.

Test container groups with Kubernetes:

# Start minikube first
minikube start --cpus=4 --memory=8g --addons=ingress

# Start AWX with minikube integration
make docker-compose-container-group

# Or combine with other options
MINIKUBE_CONTAINER_GROUP=true CONTROL_PLANE_NODE_COUNT=2 make docker-compose

Troubleshooting

Database connection issues

If you see Waiting for postgres to be ready to accept connections indefinitely:

Stop and remove all containers:

docker stop $(docker ps -a -q)
docker system prune -a

Remove volumes and networks:

docker volume prune
docker network prune

Start fresh:

make docker-compose-build
make docker-compose

Port conflicts

If port 8043 is already in use, modify the port mapping in tools/docker-compose/_sources/docker-compose.yml or stop the conflicting service.

Out of disk space

Docker images and volumes can consume significant disk space. Clean up:

# Remove unused images
docker image prune -a

# Remove unused volumes
docker volume prune

# Full cleanup (WARNING: removes all stopped containers, images, volumes)
docker system prune -a --volumes

UI not loading

If the web interface shows errors:

Ensure UI is built:
make clean-ui ui

Collect static files:

docker exec tools_awx_1 awx-manage collectstatic --noinput

Restart the web service:

docker exec tools_awx_1 supervisorctl restart awx-web

Rebuild after schema changes

If database schema changes after pulling new code:

docker exec tools_awx_1 awx-manage migrate
docker exec tools_awx_1 supervisorctl restart all

Stopping and Cleaning Up

Stop containers

make docker-compose-down

# Or manually
docker compose -f tools/docker-compose/_sources/docker-compose.yml down

Remove all AWX data

To completely remove containers, volumes, and networks:

docker compose -f tools/docker-compose/_sources/docker-compose.yml down --volumes

This deletes all database data, settings, and persistent volumes. You’ll need to recreate your admin user and reload any test data.

Purge everything

To remove all Docker containers, images, and volumes (if you only have AWX containers):

docker stop $(docker ps -a -q)
docker system prune -a
docker volume prune
docker network prune

Additional Resources

For questions or issues with the development environment, visit the Ansible Forum with the AWX tag.

Overview

Installation

Core Concepts

User Guide

Advanced Features

Integrations

Administration

Docker Compose Installation

Overview

Prerequisites

Getting Started

Building the UI

Accessing AWX

Create an Admin User

Load Demo Data (Optional)

Development Workflow

Working with the Source Code

Using docker-compose-test

Advanced Configuration

Cluster Mode

Detached Mode

Custom Image Tag

Disable Color Output

Integration Testing

Troubleshooting

Stopping and Cleaning Up

Stop containers

Remove all AWX data

Purge everything

Additional Resources

​Overview

​Prerequisites

​Getting Started

​Building the UI

​Accessing AWX

​Create an Admin User

​Load Demo Data (Optional)

​Development Workflow

​Working with the Source Code

​Using docker-compose-test

​Advanced Configuration

​Cluster Mode

​Detached Mode

​Custom Image Tag

​Disable Color Output

​Integration Testing

​Troubleshooting

​Stopping and Cleaning Up

​Stop containers

​Remove all AWX data

​Purge everything

​Additional Resources

Overview

Prerequisites

Getting Started

Building the UI

Accessing AWX

Create an Admin User

Load Demo Data (Optional)

Development Workflow

Working with the Source Code

Using docker-compose-test

Advanced Configuration

Cluster Mode

Detached Mode

Custom Image Tag

Disable Color Output

Integration Testing

Troubleshooting

Stopping and Cleaning Up

Stop containers

Remove all AWX data

Purge everything

Additional Resources