docker.recipes

Ansible AWX Tower

advanced

Open-source web interface and automation engine for Ansible.

Overview

Ansible AWX is the open-source upstream project for Red Hat Ansible Tower, providing a web-based user interface, REST API, and task engine built on top of Ansible. Originally developed by Ansible Inc. (now part of Red Hat), AWX transforms command-line Ansible playbooks into a centralized automation platform with role-based access control, job scheduling, and comprehensive logging. The platform consists of awx-web for the Django-based web interface and API, awx-task for executing playbook jobs, and receptor for mesh networking between execution nodes. This stack combines AWX's automation capabilities with PostgreSQL for robust data persistence of job histories, inventories, and credentials, while Redis provides high-speed caching and task queue management for job execution coordination. The architecture enables organizations to scale their infrastructure automation beyond individual administrators running ad-hoc playbooks to enterprise-wide automation workflows. Operations teams, DevOps engineers, and platform administrators benefit from this combination when they need centralized control over Ansible automation, audit trails for compliance, and the ability to delegate specific automation tasks to team members without exposing underlying infrastructure credentials.

Key Features

  • Web-based playbook editor with syntax highlighting and Git integration for version-controlled automation
  • Role-based access control with team permissions and credential isolation for secure automation delegation
  • Job templates with survey prompts allowing end-users to run parameterized playbooks without Ansible knowledge
  • Real-time job output streaming with color-coded status indicators and detailed execution logs
  • Inventory management with dynamic inventory sources from cloud providers, LDAP, and custom scripts
  • Workflow visualizer for chaining multiple job templates with conditional logic and approval gates
  • REST API with token authentication enabling integration with CI/CD pipelines and external tools
  • Receptor mesh networking for executing jobs across distributed execution nodes and isolated networks

Common Use Cases

  • 1Enterprise configuration management centralizing Ansible playbooks across multiple teams and environments
  • 2Self-service infrastructure provisioning allowing developers to deploy staging environments through web forms
  • 3Compliance automation with scheduled scans and remediation playbooks for security baselines
  • 4Network device management for automating router, switch, and firewall configurations at scale
  • 5Application deployment pipelines integrating with GitLab CI or Jenkins for automated releases
  • 6Disaster recovery orchestration with workflow templates for systematic service restoration procedures
  • 7Cloud resource management automating AWS, Azure, or GCP infrastructure provisioning and decommissioning

Prerequisites

  • Minimum 4GB RAM and 2 CPU cores for AWX components plus database overhead
  • Docker host with at least 20GB available storage for PostgreSQL data and project repositories
  • Network access to target systems on SSH (port 22) and WinRM (ports 5985/5986) for managed hosts
  • Understanding of Ansible playbook structure, YAML syntax, and inventory management concepts
  • Git repository access for storing and versioning Ansible project files and playbooks
  • SSL certificates for production deployments requiring encrypted web interface access

For development & testing. Review security settings, change default credentials, and test thoroughly before production use. See Terms

docker-compose.yml

docker-compose.yml
1services: 
2  awx-web: 
3    image: ghcr.io/ansible/awx:latest
4    container_name: awx-web
5    hostname: awx-web
6    environment: 
7      - DATABASE_HOST=db
8      - DATABASE_NAME=awx
9      - DATABASE_USER=awx
10      - DATABASE_PASSWORD=${DB_PASSWORD}
11      - REDIS_HOST=redis
12      - SECRET_KEY=${SECRET_KEY}
13      - AWX_ADMIN_USER=admin
14      - AWX_ADMIN_PASSWORD=${ADMIN_PASSWORD}
15    volumes: 
16      - awx-projects:/var/lib/awx/projects
17      - awx-receptor:/var/run/receptor
18    ports: 
19      - "8052:8052"
20    depends_on: 
21      - db
22      - redis
23    networks: 
24      - awx-network
25    restart: unless-stopped
26
27  awx-task: 
28    image: ghcr.io/ansible/awx:latest
29    container_name: awx-task
30    command: launch_awx_task.sh
31    environment: 
32      - DATABASE_HOST=db
33      - DATABASE_NAME=awx
34      - DATABASE_USER=awx
35      - DATABASE_PASSWORD=${DB_PASSWORD}
36      - REDIS_HOST=redis
37      - SECRET_KEY=${SECRET_KEY}
38      - SUPERVISOR_WEB_CONFIG_PATH=/etc/supervisor/conf.d/
39    volumes: 
40      - awx-projects:/var/lib/awx/projects
41      - awx-receptor:/var/run/receptor
42    depends_on: 
43      - awx-web
44    networks: 
45      - awx-network
46    restart: unless-stopped
47
48  db: 
49    image: postgres:15-alpine
50    container_name: awx-db
51    environment: 
52      - POSTGRES_USER=awx
53      - POSTGRES_PASSWORD=${DB_PASSWORD}
54      - POSTGRES_DB=awx
55    volumes: 
56      - postgres-data:/var/lib/postgresql/data
57    networks: 
58      - awx-network
59    restart: unless-stopped
60
61  redis: 
62    image: redis:7-alpine
63    container_name: awx-redis
64    volumes: 
65      - redis-data:/data
66    networks: 
67      - awx-network
68    restart: unless-stopped
69
70volumes: 
71  awx-projects: 
72  awx-receptor: 
73  postgres-data: 
74  redis-data: 
75
76networks: 
77  awx-network: 
78    driver: bridge

.env Template

.env
1# Ansible AWX
2ADMIN_PASSWORD=secure_admin_password
3DB_PASSWORD=secure_awx_password
4
5# Generate with: openssl rand -hex 32
6SECRET_KEY=your_secret_key_here

Usage Notes

  1. 1Web UI at http://localhost:8052
  2. 2Login: admin / (ADMIN_PASSWORD)
  3. 3Create projects from Git repos
  4. 4Define inventories and templates
  5. 5Schedule playbook runs

Individual Services(4 services)

Copy individual services to mix and match with your existing compose files.

awx-web
awx-web:
  image: ghcr.io/ansible/awx:latest
  container_name: awx-web
  hostname: awx-web
  environment:
    - DATABASE_HOST=db
    - DATABASE_NAME=awx
    - DATABASE_USER=awx
    - DATABASE_PASSWORD=${DB_PASSWORD}
    - REDIS_HOST=redis
    - SECRET_KEY=${SECRET_KEY}
    - AWX_ADMIN_USER=admin
    - AWX_ADMIN_PASSWORD=${ADMIN_PASSWORD}
  volumes:
    - awx-projects:/var/lib/awx/projects
    - awx-receptor:/var/run/receptor
  ports:
    - "8052:8052"
  depends_on:
    - db
    - redis
  networks:
    - awx-network
  restart: unless-stopped
awx-task
awx-task:
  image: ghcr.io/ansible/awx:latest
  container_name: awx-task
  command: launch_awx_task.sh
  environment:
    - DATABASE_HOST=db
    - DATABASE_NAME=awx
    - DATABASE_USER=awx
    - DATABASE_PASSWORD=${DB_PASSWORD}
    - REDIS_HOST=redis
    - SECRET_KEY=${SECRET_KEY}
    - SUPERVISOR_WEB_CONFIG_PATH=/etc/supervisor/conf.d/
  volumes:
    - awx-projects:/var/lib/awx/projects
    - awx-receptor:/var/run/receptor
  depends_on:
    - awx-web
  networks:
    - awx-network
  restart: unless-stopped
db
db:
  image: postgres:15-alpine
  container_name: awx-db
  environment:
    - POSTGRES_USER=awx
    - POSTGRES_PASSWORD=${DB_PASSWORD}
    - POSTGRES_DB=awx
  volumes:
    - postgres-data:/var/lib/postgresql/data
  networks:
    - awx-network
  restart: unless-stopped
redis
redis:
  image: redis:7-alpine
  container_name: awx-redis
  volumes:
    - redis-data:/data
  networks:
    - awx-network
  restart: unless-stopped

Quick Start

terminal
1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  awx-web:
5    image: ghcr.io/ansible/awx:latest
6    container_name: awx-web
7    hostname: awx-web
8    environment:
9      - DATABASE_HOST=db
10      - DATABASE_NAME=awx
11      - DATABASE_USER=awx
12      - DATABASE_PASSWORD=${DB_PASSWORD}
13      - REDIS_HOST=redis
14      - SECRET_KEY=${SECRET_KEY}
15      - AWX_ADMIN_USER=admin
16      - AWX_ADMIN_PASSWORD=${ADMIN_PASSWORD}
17    volumes:
18      - awx-projects:/var/lib/awx/projects
19      - awx-receptor:/var/run/receptor
20    ports:
21      - "8052:8052"
22    depends_on:
23      - db
24      - redis
25    networks:
26      - awx-network
27    restart: unless-stopped
28
29  awx-task:
30    image: ghcr.io/ansible/awx:latest
31    container_name: awx-task
32    command: launch_awx_task.sh
33    environment:
34      - DATABASE_HOST=db
35      - DATABASE_NAME=awx
36      - DATABASE_USER=awx
37      - DATABASE_PASSWORD=${DB_PASSWORD}
38      - REDIS_HOST=redis
39      - SECRET_KEY=${SECRET_KEY}
40      - SUPERVISOR_WEB_CONFIG_PATH=/etc/supervisor/conf.d/
41    volumes:
42      - awx-projects:/var/lib/awx/projects
43      - awx-receptor:/var/run/receptor
44    depends_on:
45      - awx-web
46    networks:
47      - awx-network
48    restart: unless-stopped
49
50  db:
51    image: postgres:15-alpine
52    container_name: awx-db
53    environment:
54      - POSTGRES_USER=awx
55      - POSTGRES_PASSWORD=${DB_PASSWORD}
56      - POSTGRES_DB=awx
57    volumes:
58      - postgres-data:/var/lib/postgresql/data
59    networks:
60      - awx-network
61    restart: unless-stopped
62
63  redis:
64    image: redis:7-alpine
65    container_name: awx-redis
66    volumes:
67      - redis-data:/data
68    networks:
69      - awx-network
70    restart: unless-stopped
71
72volumes:
73  awx-projects:
74  awx-receptor:
75  postgres-data:
76  redis-data:
77
78networks:
79  awx-network:
80    driver: bridge
81EOF
82
83# 2. Create the .env file
84cat > .env << 'EOF'
85# Ansible AWX
86ADMIN_PASSWORD=secure_admin_password
87DB_PASSWORD=secure_awx_password
88
89# Generate with: openssl rand -hex 32
90SECRET_KEY=your_secret_key_here
91EOF
92
93# 3. Start the services
94docker compose up -d
95
96# 4. View logs
97docker compose logs -f

One-Liner

Run this command to download and set up the recipe in one step:

terminal
1curl -fsSL https://docker.recipes/api/recipes/ansible-awx/run | bash

Troubleshooting

  • awx-web container fails with database connection errors: Verify DB_PASSWORD environment variable matches across awx-web, awx-task, and PostgreSQL containers
  • Job execution fails with 'receptor' connection timeout: Check awx-receptor volume mount permissions and ensure both awx-web and awx-task containers can write to shared socket
  • Playbook tasks hang on 'Gathering Facts': Confirm target hosts are reachable via SSH and AWX execution environment has proper network routing
  • Web interface shows 500 errors after container restart: Run database migrations by executing 'awx-manage migrate' inside awx-web container
  • Redis connection refused errors in job logs: Verify redis container is healthy and awx-network allows inter-service communication on default Redis port 6379
  • Secret key validation errors preventing login: Ensure SECRET_KEY environment variable is consistent across all AWX containers and persists between restarts

Community Notes

Loading...
Loading notes...

Download Recipe Kit

Get all files in a ready-to-deploy package

Includes docker-compose.yml, .env template, README, and license

Components

awx-webawx-taskpostgresqlredisreceptor

Tags

#ansible#awx#automation#tower#configuration-management

Category

DevOps & CI/CD

Related Recipes

Ad Space