Run and Stop AWX in Docker Containers: Start, Stop & Manage (Guide)

How to Run and Stop Ansible AWX in Docker container?

I'm going to show you how to start and stop the Ansible AWX in Docker containers. You can take advantage of the AWX modern web-UI and API interface. Running in Docker containers is recommended only for experienced users and developers. I'm Luca Berton and welcome to today's episode of Ansible Pilot.

See also: Build Ansible AWX in Docker Containers Easily

Links

• https://github.com/ansible/awx/blob/devel/tools/docker-compose/README.md#run-awx

Playbook

How to Run and Stop Ansible AWX in Docker containers. This requires Building from scratch Ansible AWX for Docker containers in a previous lesson.

code

Once you have a successful build of Ansible AWX for Docker containers, you can run the AWX container using the following command. The process is also spinning the requirements of PostgreSQL and Redis containers.

$ make docker-compose

Your session will be attached to the AWX container, and start watching for log messages and events in real-time when the container was launched. The first time you start the environment, database migrations run in order to build the PostgreSQL initial database schema and data. By default, six Docker containers are running on your machine: tools_awx_1, tools_postgres_1, tools_redis_1, tools_receptor_hop, tools_receptor_1, tools_receptor_2. You can verify the containers running in your system using the docker ps command:

[lberton@ansible awx]$ docker ps 
CONTAINER ID   IMAGE                            COMMAND                  CREATED        STATUS         PORTS                                                                                                                                                                                                                                                                                                                                                                                NAMES
bce34be76a94   ghcr.io/ansible/awx_devel:HEAD   "/entrypoint.sh rece…"   14 hours ago   Up 2 minutes   22/tcp, 8013/tcp, 8043/tcp, 8080/tcp                                                                                                                                                                                                                                                                                                                                                 tools_receptor_2
c11c7c1114f1   ghcr.io/ansible/awx_devel:HEAD   "/entrypoint.sh rece…"   14 hours ago   Up 2 minutes   22/tcp, 8013/tcp, 8043/tcp, 8080/tcp                                                                                                                                                                                                                                                                                                                                                 tools_receptor_1
05589a6b6185   quay.io/ansible/receptor:devel   "/usr/local/bin/dumb…"   14 hours ago   Up 3 minutes   0.0.0.0:5555->5555/tcp, :::5555->5555/tcp, 7323/tcp                                                                                                                                                                                                                                                                                                                                  tools_receptor_hop
d9570e9d9027   ghcr.io/ansible/awx_devel:HEAD   "/entrypoint.sh laun…"   14 hours ago   Up 3 minutes   0.0.0.0:2222->2222/tcp, :::2222->2222/tcp, 0.0.0.0:6899->6899/tcp, :::6899->6899/tcp, 0.0.0.0:7899-7999->7899-7999/tcp, :::7899-7999->7899-7999/tcp, 0.0.0.0:8013->8013/tcp, :::8013->8013/tcp, 0.0.0.0:8043->8043/tcp, :::8043->8043/tcp, 0.0.0.0:8080->8080/tcp, :::8080->8080/tcp, 22/tcp, 0.0.0.0:8888->8888/tcp, :::8888->8888/tcp, 0.0.0.0:3000->3001/tcp, :::3000->3001/tcp   tools_awx_1
c39fe279ecb2   postgres:12                      "docker-entrypoint.s…"   14 hours ago   Up 3 minutes   5432/tcp                                                                                                                                                                                                                                                                                                                                                                             tools_postgres_1
820ebdc15a10   redis:latest                     "redis-server /usr/l…"   14 hours ago   Up 3 minutes   6379/tcp                                                                                                                                                                                                                                                                                                                                                                             tools_redis_1
[lberton@ansible awx]$

Access the Ansible AWX Web UI

The Ansible AWX Web-UI is available at the URL https://localhost:8043/. A successful connection with your browser is going to show you the following login screen ( https://localhost:8043/#/login ).

Access the Ansible AWX Web API

The Ansible AWX API is available at the URL https://localhost:8043/api/. A successful connection with your browser is going to show you the following API endpoint ( https://localhost:8043/api/ ). The Ansible AWX API is a Browsable API so easy to navigate via the browser. Please note that some API endpoints require authentication.

See also: Create Ansible AWX Superuser in Docker: Admin Account Setup (Guide)

Conclusion

Now you know how to Run and Stop Ansible AWX in Docker containers.

Start AWX

# Docker Compose
cd /path/to/awx
docker-compose up -d
# Verify containers are running
docker-compose ps

See also: Install Ansible AWX Operator for Kubernetes (K8s) and OpenShift (OCP) - Ansible AWX

Stop AWX

# Graceful stop
docker-compose stop
# Stop and remove containers
docker-compose down
# Stop, remove containers AND volumes (data loss!)
docker-compose down -v

Restart AWX

# Restart all services
docker-compose restart
# Restart specific container
docker-compose restart awx_web
docker-compose restart awx_task

AWX Container Architecture

| Container | Purpose | |-----------|---------| | awx_web | Web UI and API (nginx + uwsgi) | | awx_task | Job execution engine | | postgres | Database | | redis | Message broker / cache |

Check Status and Logs

# Container status
docker-compose ps
# Follow logs
docker-compose logs -f awx_web
docker-compose logs -f awx_task
# Last 100 lines
docker logs awx_web --tail 100
# Check resource usage
docker stats awx_web awx_task

Manage with Ansible

---
- name: Manage AWX containers
  hosts: awx_host
  tasks:
    - name: Start AWX
      community.docker.docker_compose_v2:
        project_src: /opt/awx
        state: present
- name: Stop AWX
      community.docker.docker_compose_v2:
        project_src: /opt/awx
        state: absent
- name: Restart AWX web
      community.docker.docker_container:
        name: awx_web
        state: started
        restart: true

Common Operations

Backup database

docker exec postgres pg_dump -U awx awx > awx_backup.sql

Restore database

docker exec -i postgres psql -U awx awx < awx_backup.sql

Create admin user

docker exec -it awx_web awx-manage createsuperuser

Run management commands

docker exec -it awx_web awx-manage inventory_import --source=/tmp/hosts
docker exec -it awx_web awx-manage cleanup_jobs --days=30

Troubleshooting

AWX web not accessible

# Check if port is mapped
docker port awx_web
# Check container logs
docker logs awx_web --tail 50
# Check if migrations ran
docker exec awx_web awx-manage showmigrations | grep "\[ \]"

Task container keeps restarting

docker logs awx_task --tail 100
# Common: Redis connection issue
docker exec awx_task ping redis

AWX Operator (Kubernetes) — Modern Approach

# For production, use AWX Operator instead of Docker Compose
kubectl apply -f awx-operator.yaml
kubectl get pods -n awx
kubectl logs deployment/awx-web -n awx

FAQ

Docker Compose vs AWX Operator?

Docker Compose is for development/small deployments. AWX Operator on Kubernetes is recommended for production.

How do I upgrade AWX?

git pull
docker-compose pull
docker-compose up -d
docker exec awx_web awx-manage migrate

My jobs are stuck in "pending"

Check the task container: docker logs awx_task. Common causes: Redis connection lost, insufficient memory, or task container crashed.

Related Articles

• docker_container module walkthrough • getting started with Ansible AWX