Semaphore (Ansible UI)

Install Ansible Semaphore, a web interface to manage and run Ansible playbooks from the browser

Semaphore is an open-source web UI for Ansible. It lets you run playbooks, manage inventories, and schedule tasks without using the command line. It's a lighter alternative to AWX/Tower.

Requirements

Ubuntu 22.04 / Debian 12
MySQL or MariaDB (or PostgreSQL)
Ansible installed on the same server
Port 3000 (or behind a reverse proxy)

Install Ansible

If not already installed:

sudo apt update
sudo apt install ansible -y
ansible --version

Install MariaDB

sudo apt install mariadb-server -y
sudo mysql_secure_installation

Create the Semaphore database:

sudo mysql -u root -p

CREATE DATABASE semaphore CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'semaphore'@'localhost' IDENTIFIED BY 'StrongPassword123!';
GRANT ALL PRIVILEGES ON semaphore.* TO 'semaphore'@'localhost';
FLUSH PRIVILEGES;
EXIT;

Install Semaphore

Download the latest release:

# Check latest at https://github.com/semaphoreui/semaphore/releases
SEMAPHORE_VERSION=$(curl -s https://api.github.com/repos/semaphoreui/semaphore/releases/latest | grep tag_name | cut -d '"' -f 4)

wget "https://github.com/semaphoreui/semaphore/releases/download/${SEMAPHORE_VERSION}/semaphore_linux_amd64.deb"
sudo dpkg -i semaphore_linux_amd64.deb

Verify:

semaphore version

Configure Semaphore

Run the interactive setup:

semaphore setup

Answer the prompts:

DB Driver: mysql
DB Host: 127.0.0.1:3306
DB Name: semaphore
DB User: semaphore
DB Password: StrongPassword123!
Playbook path: /tmp/semaphore (or your preferred path)
Web root URL: e.g. https://semaphore.yourdomain.com
Admin username/password: choose your credentials

This creates a config.json (usually in ~/.config/semaphore/ or the current directory).

Run as a systemd service

Create the service file:

sudo nano /etc/systemd/system/semaphore.service

[Unit]
Description=Semaphore Ansible UI
After=network.target mysql.service

[Service]
Type=simple
User=www-data
WorkingDirectory=/opt/semaphore
ExecStart=/usr/bin/semaphore server --config /etc/semaphore/config.json
Restart=on-failure
RestartSec=10s

[Install]
WantedBy=multi-user.target

Move your config:

sudo mkdir -p /etc/semaphore
sudo cp config.json /etc/semaphore/config.json
sudo chown -R www-data:www-data /etc/semaphore

Enable and start:

sudo systemctl daemon-reload
sudo systemctl enable semaphore
sudo systemctl start semaphore
sudo systemctl status semaphore

Nginx reverse proxy

server {
    listen 443 ssl;
    server_name semaphore.yourdomain.com;

    ssl_certificate /etc/letsencrypt/live/semaphore.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/semaphore.yourdomain.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

First steps in the UI

Open https://semaphore.yourdomain.com and log in
Create a Project, logical grouping of inventories, playbooks, and tasks
Add Key Store, SSH keys or passwords used to connect to hosts
Add Inventory, list of hosts (paste directly or upload a file)
Add Repository, Git repo containing your playbooks
Add Task Template, links a playbook from a repo with an inventory and key
Run Task, executes the playbook, with live output in the browser

Schedule tasks

In any Task Template, click Schedule and set a cron expression:

Expression	Meaning
`0 2 * * *`	Every day at 2:00 AM
`0 * * * *`	Every hour
`/30 * * *`	Every 30 minutes

Logs and troubleshooting

journalctl -u semaphore -f

Common issues:

DB connection refused: verify MariaDB is running and credentials match
Playbook not found: check repository path and branch
SSH auth failure: verify the key in Key Store matches the target host's authorized_keys

On this page