Skip to main content
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 Engine must be installed and running on your host machine.
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 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 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 is required for generating SSL certificates.Most systems have OpenSSL pre-installed. Verify:
openssl version
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

1

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
2

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.
3

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.
4

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).
1

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
2

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.
3

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:
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.

​
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.
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
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
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
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:
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).

​
Troubleshooting

If you see Waiting for postgres to be ready to accept connections indefinitely:
  1. Stop and remove all containers: 
    docker stop $(docker ps -a -q)
docker system prune -a
  2. Remove volumes and networks: 
    docker volume prune
docker network prune
  3. Start fresh: 
    make docker-compose-build
make docker-compose
If port 8043 is already in use, modify the port mapping in tools/docker-compose/_sources/docker-compose.yml or stop the conflicting service.
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
If the web interface shows errors:
  1. Ensure UI is built: 
    make clean-ui ui
  2. Collect static files: 
    docker exec tools_awx_1 awx-manage collectstatic --noinput
  3. Restart the web service: 
    docker exec tools_awx_1 supervisorctl restart awx-web
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.

Build docs developers (and LLMs) love

Get started for freeTalk to us