Ansible Semaphore

intermediate

Modern UI for Ansible automation.

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.

Key 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

Common Use Cases

1DevOps teams managing application deployments across multiple environments with approval workflows
2System administrators coordinating server maintenance tasks and configuration updates
3Cloud infrastructure teams provisioning and decommissioning resources through standardized playbooks
4Development teams running automated testing and deployment pipelines triggered by code commits
5IT operations managing compliance auditing and reporting through scheduled configuration checks
6Managed service providers offering infrastructure automation services to multiple clients
7Educational 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

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

docker-compose.yml

1services: 
2  semaphore: 
3    image: semaphoreui/semaphore:latest
4    container_name: semaphore
5    restart: unless-stopped
6    environment: 
7      SEMAPHORE_DB_USER: ${DB_USER}
8      SEMAPHORE_DB_PASS: ${DB_PASSWORD}
9      SEMAPHORE_DB_HOST: postgres
10      SEMAPHORE_DB_PORT: 5432
11      SEMAPHORE_DB_DIALECT: postgres
12      SEMAPHORE_DB: ${DB_NAME}
13      SEMAPHORE_PLAYBOOK_PATH: /tmp/semaphore
14      SEMAPHORE_ADMIN_PASSWORD: ${ADMIN_PASSWORD}
15      SEMAPHORE_ADMIN_EMAIL: ${ADMIN_EMAIL}
16      SEMAPHORE_ADMIN: admin
17    ports: 
18      - "3000:3000"
19    depends_on: 
20      - postgres
21    networks: 
22      - semaphore
23
24  postgres: 
25    image: postgres:16-alpine
26    container_name: semaphore-postgres
27    environment: 
28      POSTGRES_DB: ${DB_NAME}
29      POSTGRES_USER: ${DB_USER}
30      POSTGRES_PASSWORD: ${DB_PASSWORD}
31    volumes: 
32      - postgres_data:/var/lib/postgresql/data
33    networks: 
34      - semaphore
35
36volumes: 
37  postgres_data: 
38
39networks: 
40  semaphore: 
41    driver: bridge

.env Template

.env

1DB_NAME=semaphore
2DB_USER=semaphore
3DB_PASSWORD=changeme
4ADMIN_EMAIL=admin@example.com
5ADMIN_PASSWORD=changeme

Usage Notes

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

Individual Services(2 services)

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

semaphore

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

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

Quick Start

terminal

1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  semaphore:
5    image: semaphoreui/semaphore:latest
6    container_name: semaphore
7    restart: unless-stopped
8    environment:
9      SEMAPHORE_DB_USER: ${DB_USER}
10      SEMAPHORE_DB_PASS: ${DB_PASSWORD}
11      SEMAPHORE_DB_HOST: postgres
12      SEMAPHORE_DB_PORT: 5432
13      SEMAPHORE_DB_DIALECT: postgres
14      SEMAPHORE_DB: ${DB_NAME}
15      SEMAPHORE_PLAYBOOK_PATH: /tmp/semaphore
16      SEMAPHORE_ADMIN_PASSWORD: ${ADMIN_PASSWORD}
17      SEMAPHORE_ADMIN_EMAIL: ${ADMIN_EMAIL}
18      SEMAPHORE_ADMIN: admin
19    ports:
20      - "3000:3000"
21    depends_on:
22      - postgres
23    networks:
24      - semaphore
25
26  postgres:
27    image: postgres:16-alpine
28    container_name: semaphore-postgres
29    environment:
30      POSTGRES_DB: ${DB_NAME}
31      POSTGRES_USER: ${DB_USER}
32      POSTGRES_PASSWORD: ${DB_PASSWORD}
33    volumes:
34      - postgres_data:/var/lib/postgresql/data
35    networks:
36      - semaphore
37
38volumes:
39  postgres_data:
40
41networks:
42  semaphore:
43    driver: bridge
44EOF
45
46# 2. Create the .env file
47cat > .env << 'EOF'
48DB_NAME=semaphore
49DB_USER=semaphore
50DB_PASSWORD=changeme
51ADMIN_EMAIL=admin@example.com
52ADMIN_PASSWORD=changeme
53EOF
54
55# 3. Start the services
56docker compose up -d
57
58# 4. View logs
59docker 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-semaphore/run | bash

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

Community Notes

Loading notes...

Download Recipe Kit

Get all files in a ready-to-deploy package

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

Components

semaphorepostgres

Related Recipes

Ad Space

Shortcuts: C CopyF FavoriteD Download