AnsibleByExample

Run and Stop Ansible AWX in Docker

Beginneransibleawxwebapi

2024-01-015By Luca Berton

Lesson 1 of 14 in AAP and AWX

Ansible Automation Platform and AWX — full curriculum

View path overview →

Introduction

After building AWX from source, you need to know how to start, stop, and manage the Docker containers. This guide covers all the commands and troubleshooting you need for day-to-day AWX Docker operations.

Note: Docker-based AWX is recommended for development and testing. For production, use the AWX Operator on Kubernetes.

Start AWX

cd /path/to/awx
make docker-compose

Your terminal attaches to the AWX container and streams logs in real time. The first startup runs database migrations to initialize the PostgreSQL schema.

Container Architecture

AWX runs six containers by default:

Container	Image	Purpose
`tools_awx_1`	`ghcr.io/ansible/awx_devel:HEAD`	Main AWX application (Web UI + API)
`tools_postgres_1`	`postgres:12`	PostgreSQL database
`tools_redis_1`	`redis:latest`	Redis cache and message broker
`tools_receptor_hop`	`quay.io/ansible/receptor:devel`	Receptor mesh hop node
`tools_receptor_1`	`ghcr.io/ansible/awx_devel:HEAD`	Receptor worker node 1
`tools_receptor_2`	`ghcr.io/ansible/awx_devel:HEAD`	Receptor worker node 2

Verify all containers are running:

docker ps

CONTAINER ID   IMAGE                            NAMES               PORTS
bce34be76a94   ghcr.io/ansible/awx_devel:HEAD   tools_receptor_2    22/tcp, 8013/tcp
c11c7c1114f1   ghcr.io/ansible/awx_devel:HEAD   tools_receptor_1    22/tcp, 8013/tcp
05589a6b6185   quay.io/ansible/receptor:devel   tools_receptor_hop  0.0.0.0:5555->5555/tcp
d9570e9d9027   ghcr.io/ansible/awx_devel:HEAD   tools_awx_1         0.0.0.0:8043->8043/tcp, ...
c39fe279ecb2   postgres:12                      tools_postgres_1    5432/tcp
820ebdc15a10   redis:latest                     tools_redis_1       6379/tcp

Access the Web UI

Navigate to https://awx.example.com/ in your browser.

Run Ansible AWX UI in Docker containers

Default credentials:

Username: admin
Password: password

Create a proper superuser with awx-manage createsuperuser — see Create AWX Superuser

Access the API

The REST API is available at https://awx.example.com/api/.

Access the Ansible AWX API in Docker containers

# Test API connectivity
curl -k -u admin:password https://awx.example.com/api/v2/ping/

# List job templates
curl -k -u admin:password https://awx.example.com/api/v2/job_templates/

# Get API version info
curl -k https://awx.example.com/api/

Stop AWX

Stop All Containers

# From the AWX repo directory
make docker-compose-down

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

Stop Individual Containers

docker stop tools_awx_1
docker stop tools_postgres_1
docker stop tools_redis_1

Stop Without Removing

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

This preserves container state so you can restart quickly.

Restart AWX

Restart All

# Stop and start fresh
make docker-compose-down
make docker-compose

# Or restart without rebuilding
docker compose -f tools/docker-compose/_sources/docker-compose.yml restart

Restart Single Container

docker restart tools_awx_1

Run in Background (Detached)

# Start detached
make docker-compose COMPOSE_UP_OPTS=-d

# View logs afterward
docker logs -f tools_awx_1

Common Docker Commands

Command	Purpose
`docker ps`	List running containers
`docker logs tools_awx_1`	View AWX logs
`docker logs -f tools_awx_1`	Follow AWX logs (live)
`docker exec -it tools_awx_1 bash`	Shell into AWX container
`docker exec -it tools_awx_1 awx-manage`	Run AWX management commands
`docker stats`	Monitor resource usage
`docker compose down -v`	Stop and remove volumes (full reset)

Shell Into the Container

# Access AWX shell
docker exec -it tools_awx_1 bash

# Run management commands
docker exec -it tools_awx_1 awx-manage --help
docker exec -it tools_awx_1 awx-manage inventory_import --help
docker exec -it tools_awx_1 awx-manage dbshell

Troubleshooting

Containers Won't Start

# Check for port conflicts
sudo lsof -i :8043
sudo lsof -i :5432

# Check Docker resources
docker system df
docker system prune -f  # Clean up unused resources

Database Migration Errors

# Reset database (WARNING: deletes all data)
make docker-compose-down
docker volume rm tools_postgres_data
make docker-compose

AWX Unresponsive

# Check container health
docker inspect tools_awx_1 --format='{{.State.Health.Status}}'

# View recent logs
docker logs --tail 100 tools_awx_1

# Restart just AWX
docker restart tools_awx_1

High Memory Usage

AWX development containers use significant memory. Ensure Docker has at least 8 GB RAM allocated:

# Check memory usage
docker stats --no-stream

SSL Certificate Warning

The development environment uses a self-signed certificate. This is expected — accept the warning in your browser or use curl -k.

Data Persistence

Data	Storage	Persists Across Restarts?
Database	Docker volume (`tools_postgres_data`)	Yes
Redis cache	Container memory	No
Job output	Docker volume	Yes
Custom venvs	Container filesystem	No (rebuild required)

Conclusion

make docker-compose starts AWX with all dependencies (PostgreSQL, Redis, Receptor). Access the Web UI at https://awx.example.com/ and the API at https://awx.example.com/api/. Use make docker-compose-down to stop everything, or add COMPOSE_UP_OPTS=-d to run in the background. For production deployments, switch to the AWX Operator on Kubernetes.