Semaphore UI: Web Interface for Ansible Playbook Management

Why Semaphore?

Running Ansible from the terminal works, but Semaphore adds:

Visual dashboard — See all playbook runs, their status, and logs.
One-click execution — No need to SSH into a server and type commands.
Scheduling — Cron-like scheduling for recurring playbooks.
RBAC — Give team members access without sharing SSH keys.
Audit trail — Full execution history with timestamps and output.

Prerequisites

Docker or a Go binary + database (PostgreSQL/MySQL/SQLite).
An existing Ansible playbook in a Git repository.
SSH access from the Semaphore server to managed hosts.

Step 1: Deploy with Docker Compose

# docker-compose.yml
version: "3"
services:
  semaphore:
    image: semaphoreui/semaphore:latest
    container_name: semaphore
    environment:
      SEMAPHORE_DB_DIALECT: bolt
      SEMAPHORE_ADMIN_PASSWORD: admin123
      SEMAPHORE_ADMIN_NAME: admin
      SEMAPHORE_ADMIN_EMAIL: admin@example.com
      SEMAPHORE_ADMIN: admin
    ports:
      - "3000:3000"
    volumes:
      - ./semaphore-data:/etc/semaphore
    restart: always

docker compose up -d

Access at http://your-server:3000. Log in with the admin credentials.

Step 2: Configure Key Store

Go to Key Store → New Key.
Add your SSH private key (for connecting to managed hosts).
Add any sudo/become passwords as “Login with password” type keys.
These credentials are stored encrypted and referenced by task templates.

Step 3: Add a Git Repository

Go to Repositories → New Repository.
Name: e.g., “Infrastructure Playbooks”
URL: git@github.com:your-org/ansible-playbooks.git
Branch: main
SSH Key: Select the key from your Key Store.

Step 4: Create an Inventory

Go to Inventory → New Inventory.
Choose Static or File (from the Git repo).
For Static, paste your inventory in INI or YAML format:

[webservers]
web1.example.com
web2.example.com

[databases]
db1.example.com

Step 5: Create and Run a Task Template

Go to Task Templates → New Template.
Playbook Filename: site.yml (path relative to the repository root).
Repository: Select your repository.
Inventory: Select your inventory.
Environment: Add any extra variables (JSON format).
Schedule: (Optional) Set a cron expression for automatic runs.
Click Run to execute immediately.

Troubleshooting

Problem	Solution
Playbook fails but works from CLI	Add SSH keys and sudo passwords in Key Store; check environment variables
”Repository not accessible”	Verify Git URL and SSH key; test `git clone` manually from the Semaphore server
Task stuck in “waiting”	Check that the Semaphore worker is running; restart the container
Permission denied on managed hosts	Ensure the SSH key in Key Store matches the authorized_keys on target hosts
Schedule not triggering	Verify cron expression syntax; check Semaphore logs for scheduler errors

Summary

Semaphore is a lightweight AWX alternative — single binary, 256 MB RAM.
Use the Key Store for SSH keys and passwords.
Schedule playbooks with cron expressions for automated infrastructure management.
Check execution logs in the Semaphore UI for debugging failed runs.

Frequently Asked Questions

What is Semaphore and why use it with Ansible?

Semaphore is an open-source web UI for Ansible that replaces the command line with a visual dashboard. It provides one-click playbook execution, task scheduling (like cron for Ansible), execution history with logs, role-based access control, and integration with Git repositories. It's the open-source alternative to Ansible AWX/Tower.

How is Semaphore different from AWX or Ansible Tower?

Semaphore is much lighter than AWX (which requires Kubernetes or Docker with 4+ GB RAM). Semaphore runs as a single binary with a PostgreSQL/SQLite backend, needing only 256 MB RAM. It covers 90% of what AWX does (run playbooks, manage inventory, schedule jobs) without the complexity.

Can Semaphore schedule Ansible playbooks to run automatically?

Yes. Each task template in Semaphore can have a cron schedule. For example, you can schedule a 'security-updates' playbook to run every night at 2 AM, and Semaphore will execute it and store the output logs.

Why does my playbook fail in Semaphore but works from the command line?

Common causes: Semaphore runs as its own user (not your user), so SSH keys and sudo passwords must be configured in Semaphore's Key Store. Also, environment variables available in your shell may not be available to Semaphore. Add them in the Environment section of the task template.