# Ansible AWX Tower

> Open-source web interface and automation engine for Ansible.

- Category: DevOps & CI/CD
- Difficulty: advanced
- Components: awx-web, awx-task, postgresql, redis, receptor
- Tags: ansible, awx, automation, tower, configuration-management
- Source: https://docker.recipes/devops/ansible-awx

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

## 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

## Use cases

- Enterprise configuration management centralizing Ansible playbooks across multiple teams and environments
- Self-service infrastructure provisioning allowing developers to deploy staging environments through web forms
- Compliance automation with scheduled scans and remediation playbooks for security baselines
- Network device management for automating router, switch, and firewall configurations at scale
- Application deployment pipelines integrating with GitLab CI or Jenkins for automated releases
- Disaster recovery orchestration with workflow templates for systematic service restoration procedures
- Cloud 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

## docker-compose.yml

```yaml
services:
  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:
    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:
    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:
    image: redis:7-alpine
    container_name: awx-redis
    volumes:
      - redis-data:/data
    networks:
      - awx-network
    restart: unless-stopped

volumes:
  awx-projects:
  awx-receptor:
  postgres-data:
  redis-data:

networks:
  awx-network:
    driver: bridge
```

## .env

```bash
# Ansible AWX
ADMIN_PASSWORD=secure_admin_password
DB_PASSWORD=secure_awx_password

# Generate with: openssl rand -hex 32
SECRET_KEY=your_secret_key_here
```

## Usage notes

- Web UI at http://localhost:8052
- Login: admin / (ADMIN_PASSWORD)
- Create projects from Git repos
- Define inventories and templates
- Schedule playbook runs

## 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

