# Ansible Semaphore

> Modern UI for Ansible automation.

- Category: DevOps & CI/CD
- Difficulty: intermediate
- Components: semaphore, postgres
- Tags: ansible, semaphore, automation, ui
- Source: https://docker.recipes/devops/ansible-semaphore

## Overview

Ansible Semaphore is a modern web-based UI that transforms how teams interact with Ansible automation. Originally created to address the complexity of managing Ansible playbooks, inventories, and execution logs across distributed teams, Semaphore provides a centralized interface that makes infrastructure automation accessible to both seasoned DevOps engineers and team members who prefer graphical interfaces over command-line tools. The platform offers role-based access control, scheduled task execution, and comprehensive audit trails that enterprise environments demand.

This stack combines Semaphore with PostgreSQL to create a robust automation management platform. PostgreSQL serves as the persistent data store for all Semaphore configurations, user accounts, execution histories, and audit logs. The relational database's ACID compliance ensures that critical automation data remains consistent, while its advanced querying capabilities enable Semaphore to efficiently retrieve execution statistics and generate detailed reports. PostgreSQL's proven reliability makes it ideal for production environments where automation failures could have significant business impact.

Development teams managing complex infrastructure, IT operations groups coordinating across multiple environments, and growing organizations transitioning from ad-hoc scripting to structured automation will benefit most from this deployment. The combination provides enterprise-grade features like user authentication, execution scheduling, and detailed logging while maintaining the flexibility to integrate with existing CI/CD pipelines and configuration management workflows.

## Features

- Web-based playbook execution with real-time output streaming and color-coded status indicators
- Git repository integration for automatic playbook synchronization and version control
- Role-based access control with team management and permission granularity per project
- Scheduled task execution with cron-style scheduling and recurring job management
- Comprehensive audit logging stored in PostgreSQL with execution history and change tracking
- SSH key and credential management with encrypted storage in the database
- Multi-project workspace organization with isolated inventories and playbook collections
- RESTful API for integration with external systems and custom automation workflows

## Use cases

- DevOps teams managing application deployments across multiple environments with approval workflows
- System administrators coordinating server maintenance tasks and configuration updates
- Cloud infrastructure teams provisioning and decommissioning resources through standardized playbooks
- Development teams running automated testing and deployment pipelines triggered by code commits
- IT operations managing compliance auditing and reporting through scheduled configuration checks
- Managed service providers offering infrastructure automation services to multiple clients
- Educational institutions teaching infrastructure automation with a user-friendly interface

## Prerequisites

- Minimum 2GB RAM for combined Semaphore and PostgreSQL operations with moderate playbook complexity
- Docker and Docker Compose installed with user permissions for container management
- Port 3000 available for Semaphore web interface access
- SSH key pairs generated for target host authentication in Ansible operations
- Basic understanding of Ansible playbook structure and inventory file formats
- Git repository access if using remote playbook sources for automation content

## docker-compose.yml

```yaml
services:
  semaphore:
    image: semaphoreui/semaphore:latest
    container_name: semaphore
    restart: unless-stopped
    environment:
      SEMAPHORE_DB_USER: ${DB_USER}
      SEMAPHORE_DB_PASS: ${DB_PASSWORD}
      SEMAPHORE_DB_HOST: postgres
      SEMAPHORE_DB_PORT: 5432
      SEMAPHORE_DB_DIALECT: postgres
      SEMAPHORE_DB: ${DB_NAME}
      SEMAPHORE_PLAYBOOK_PATH: /tmp/semaphore
      SEMAPHORE_ADMIN_PASSWORD: ${ADMIN_PASSWORD}
      SEMAPHORE_ADMIN_EMAIL: ${ADMIN_EMAIL}
      SEMAPHORE_ADMIN: admin
    ports:
      - "3000:3000"
    depends_on:
      - postgres
    networks:
      - semaphore

  postgres:
    image: postgres:16-alpine
    container_name: semaphore-postgres
    environment:
      POSTGRES_DB: ${DB_NAME}
      POSTGRES_USER: ${DB_USER}
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    networks:
      - semaphore

volumes:
  postgres_data:

networks:
  semaphore:
    driver: bridge
```

## .env

```bash
DB_NAME=semaphore
DB_USER=semaphore
DB_PASSWORD=changeme
ADMIN_EMAIL=admin@example.com
ADMIN_PASSWORD=changeme
```

## Usage notes

- Docs: https://docs.ansible-semaphore.com/
- Access at http://localhost:3000 - login with ADMIN_EMAIL/ADMIN_PASSWORD
- Add Key Store for SSH keys, passwords, and secrets
- Create Inventory files for target hosts
- Add playbooks from Git repository or upload
- Schedule tasks and view execution history

## Troubleshooting

- Database connection failed: Verify postgres container is running and SEMAPHORE_DB_HOST matches service name
- Semaphore admin login rejected: Check ADMIN_EMAIL and ADMIN_PASSWORD environment variables match login credentials
- Playbook execution fails with permission denied: Ensure SSH keys are properly added to Key Store and target hosts
- PostgreSQL container crashes on startup: Check available disk space and verify DB_PASSWORD meets complexity requirements
- Semaphore UI shows 'Database migration failed': Remove postgres_data volume and restart stack to reinitialize database
- Task execution hangs indefinitely: Verify target hosts are reachable and SSH keys have appropriate permissions

