The deployment of AWX, the open-source upstream project for Ansible Automation Platform, represents a critical juncture for organizations seeking to centralize their automation, manage inventories, and schedule complex playbooks. While the architectural evolution of AWX has shifted toward a Kubernetes-native model via the AWX Operator, the use of Docker Compose remains a vital alternative. This methodology provides a streamlined path for developers, small teams, and environments where the overhead of a full Kubernetes cluster is not warranted. By utilizing containerized services, users can rapidly instantiate the AWX ecosystem, which comprises a web interface, a task engine, a PostgreSQL database, and a Redis cache, all managed through a single orchestration file.
Understanding the dichotomy between Docker and Kubernetes is essential for any infrastructure engineer. The official stance from the AWX project is that the AWX Operator on Kubernetes is the only recommended method for production environments due to its scalability and high-availability features. However, the reality of the landscape shows that Docker Compose is an exceptionally viable option for development and test-oriented deployments. Even in some production contexts, such as certain third-party offerings found in the Azure Marketplace, Docker is utilized to host AWX instances. While the AWX developers do not officially support these marketplace versions, they acknowledge that the software can be run in any environment permitted by the license.
Hardware and Software Prerequisites
Before initiating the installation of AWX via Docker Compose, the host environment must meet specific technical thresholds to ensure stability and performance. Failure to meet these requirements often results in database timeouts or container crashes during the bootstrapping phase.
The recommended host operating system is Ubuntu 22.04, though other Linux distributions are compatible. The system must have the following components installed and configured:
- Docker Engine 24+
- Docker Compose V2 (This must be the plugin version, integrated into the docker command, rather than the legacy standalone binary)
- Git
From a resource perspective, the minimum requirements are strict because AWX runs multiple heavy-duty services simultaneously.
- CPU: At least 2 CPU cores. This is necessary to handle the simultaneous operation of the web service, the task manager, and the database engine.
- RAM: Minimum 4GB. The task engine and the Django-based web interface are memory-intensive.
- Disk Space: 20GB of free space to accommodate the container images, the PostgreSQL data volume, and the project files.
To verify that the environment is correctly prepared, the following commands should be executed in the terminal:
docker version
docker compose version
free -h
nproc
The free -h command allows the administrator to confirm that the available RAM meets the 4GB threshold, while nproc ensures the CPU core count is sufficient.
The Installation Process: From Cloning to Deployment
The installation of AWX via Docker Compose is a multi-stage process that begins with the acquisition of the official source code and ends with the orchestration of several interconnected containers.
Step 1: Cloning the AWX Repository
The first step involves cloning the specific version of the AWX repository from GitHub. For a stable deployment, using a tagged release is recommended over the develop branch.
git clone -b 24.2.0 https://github.com/ansible/awx.git
cd awx
Cloning the repository provides the necessary Docker Compose files and the administrative scripts required to manage the environment. By specifying the -b 24.2.0 flag, the user ensures that they are working with a known stable release rather than a volatile development version.
Step 2: Configuring the Inventory and Environment
The deployment relies on an inventory file for configuration. This file serves as the source of truth for environment variables that the containers will ingest at runtime. Key variables include database credentials, administrative passwords, and the secret key used for cryptographic signing in the Django application.
The core of the deployment is the docker-compose.yml file. This file defines the architecture of the AWX stack.
Detailed Analysis of the Docker Compose Architecture
The AWX stack is composed of four primary services. Each service plays a distinct role in the automation lifecycle.
The PostgreSQL Database
The postgres service utilizes the postgres:15 image. It acts as the persistent storage layer for all AWX data, including users, inventories, projects, and job histories.
- Image:
postgres:15 - Container Name:
awx-postgres - Environment Variables:
POSTGRES_DB(set toawx),POSTGRES_USER(set toawx), andPOSTGRES_PASSWORD(which can be customized via the${PG_PASSWORD}variable, defaulting toawxpassword). - Persistence: The database uses a volume named
postgres_datamapped to/var/lib/postgresql/datato ensure data survives container restarts. - Health Check: The system uses
pg_isready -U awxto ensure the database is fully operational before dependent services start.
The Redis Cache
The redis service utilizes the redis:7-alpine image. Redis is used as the message broker and cache, which is critical for the task manager to queue and distribute jobs.
- Image:
redis:7-alpine - Container Name:
awx-redis - Persistence: Data is stored in the
redis_datavolume. - Health Check: The container runs
redis-cli pingto verify connectivity.
The AWX Web Interface
The awx-web service is the primary entry point for users. It provides the GUI and the REST API.
- Image:
quay.io/ansible/awx:24.2.0 - Container Name:
awx-web - Port Mapping:
8080:8052(The host port 8080 is mapped to the container port 8052). - Command:
/usr/bin/launch_awx.sh - Dependencies: This service depends on both
postgresandredisbeing healthy before it can start. - Volumes: It utilizes
awx_projectsfor project storage andawx_receptorfor communication.
The AWX Task Engine
The awx-task service is responsible for the actual execution of Ansible playbooks. It processes the jobs queued by the web interface.
- Image:
quay.io/ansible/awx:24.2.0 - Container Name:
awx-task - Command:
/usr/bin/launch_awx_task.sh - Connection: It connects to the same PostgreSQL and Redis instances as the web service to synchronize job states.
Post-Deployment Configuration and User Management
Once the containers are running, the system is not yet accessible until an administrative account is created. The AWX web interface is reachable at https://localhost:8043/, and the API is available at https://localhost:8043/api/v2.
To create the initial administrator account, the user must execute a command inside the running container:
docker exec -ti tools_awx_1 awx-manage createsuperuser
This command initiates an interactive shell where the user defines the username and password. This account is the primary authority used to configure the rest of the server and create additional users.
For those who wish to test the system without manually creating projects, AWX provides a utility to load sample data:
docker exec tools_awx_1 awx-manage create_preload_data
This action populates the database with a demo project, a sample inventory, and a job template, allowing users to verify that the task engine is communicating correctly with the web interface.
Administrative Operations and Maintenance
Managing an AWX Docker deployment requires a set of specialized commands for debugging, updating, and modifying the internal state of the containers.
Shell Access
To perform administrative tasks or modify configurations within the container, a bash session can be started:
docker exec -it tools_awx_1 bash
This session behaves like an SSH connection, granting full access to the container's filesystem and binary tools.
Development Mode and Bootstrapping
For developers who need to start the environment without immediately launching all services, the make docker-compose-test target can be used. This places the user directly into a shell. Once inside, the environment must be bootstrapped to run database migrations and initial setup:
/usr/bin/bootstrap_development.sh
This process may take several minutes as it prepares the database schema for the current version of AWX.
Updating the Deployment
Upgrading AWX involves a transition to a newer release from the official GitHub releases page. The process follows these steps:
- Check out the new source code.
- Update the inventory file with customized variables.
- Run the make target from the root of the clone:
make docker-compose
Health Monitoring and Troubleshooting
Maintaining a healthy AWX instance requires consistent monitoring of the container logs and resource consumption.
Verification Commands
The following commands are used to verify the operational status of the deployment:
- Check container status:
docker compose ps - View web logs:
docker compose logs -f awx-web - View task logs:
docker compose logs -f awx-task - Monitor resource usage:
docker stats awx-web awx-task awx-postgres awx-redis - Verify AWX version:
docker exec awx-web awx-manage version
Troubleshooting Common Failures
In the event of a system failure, the following diagnostic steps should be taken based on the symptoms:
Database Connection Errors
If the web or task containers cannot connect to the database, check the PostgreSQL health:
docker compose logs postgres
docker exec awx-postgres pg_isready -U awx
Web UI Unresponsiveness
If the interface is not loading, inspect the tail of the web logs:
docker compose logs awx-web --tail=50
Job Execution Failures
If playbooks are stuck in a "pending" state, the issue usually lies with the task container:
docker compose logs awx-task --tail=50
Administrative Recovery
If the admin password is lost or needs to be reset:
docker exec -it awx-web awx-manage update_password --username admin --password 'new_password'
To clear stuck jobs that may be clogging the task queue:
docker exec -it awx-web awx-manage cleanup_jobs --days 0
Comparison of Deployment Methodologies
The choice between Docker Compose and Kubernetes is often a point of contention for engineers. The following table summarizes the technical trade-offs.
| Feature | Docker Compose | Kubernetes (AWX Operator) |
|---|---|---|
| Primary Use Case | Development, Small Teams, Testing | Production, Enterprise Scale |
| Setup Complexity | Low (Single YAML file) | High (Cluster, Operator, CRDs) |
| Scalability | Limited to single host | Highly Scalable (Multi-node) |
| High Availability | Not natively supported | Built-in via K8s orchestration |
| Recommended by Devs | No (Dev/Test only) | Yes (Preferred method) |
| Resource Overhead | Low | High (K8s control plane) |
Conclusion
The deployment of AWX via Docker Compose provides an efficient, low-friction entry point into the world of Ansible automation. By leveraging a structured set of containers—PostgreSQL for data, Redis for caching, and dedicated images for the web and task layers—users can establish a fully functional automation hub without the steep learning curve of Kubernetes. However, the technical reality remains that for any environment where uptime is critical and scaling is required, the transition to the AWX Operator on Kubernetes is the only path that ensures long-term stability and official support. For developers and small-scale operations, the Docker Compose path remains a powerful tool, provided the hardware prerequisites are strictly adhered to and the administrative lifecycle is managed through the provided awx-manage utilities.