🚦 Semaphore UI

Semaphore UI is a lightweight web interface for managing and executing Ansible playbooks. It provides a user‑friendly dashboard to organize inventories, credentials, and playbook runs—ideal for homelab automation and infrastructure orchestration.

📥 Installation

Semaphore UI is installed on an Ubuntu virtual machine using Ubuntu’s package manager.
During installation:

⚙️ Configuration

Python

Semaphore UI runs inside a Python virtual environment.

Database

PostgreSQL is used as the backend database. It runs on the same host as the Semaphore service.
Data folder: /ansible/pgdata

Example configuration:

"postgres": {
  "host": "192.168.2.102",
  "name": "semaphoreui",
  "user": "semaphoreui",
  "pass": "*****"
},
"dialect": "postgres"

🔐 Logging In & Authentication

Semaphore supports multiple authentication methods to control access:

Local Admin

LDAP (Active Directory)

Semaphore can integrate with LDAP/Active Directory for user authentication. This allows domain users to log in with their existing credentials.

Example configuration highlights:

OAuth2 (Entra ID)

Semaphore supports OAuth2 authentication through Microsoft Entra ID (formerly Azure AD) as the Identity Provider (IdP).

🖥️ Systemd Service

Semaphore UI runs automatically via a systemd unit file (/etc/systemd/system/semaphore.service):

[Unit]
Description=Semaphore Ansible
Documentation=https://docs.semaphoreui.com
Wants=network-online.target
After=network-online.target
ConditionPathExists=/usr/bin/semaphore
ConditionPathExists=/ansible/semaphore/etc/config.json

[Service]
User=semaphore
Group=ansible
ExecReload=/bin/kill -HUP $MAINPID
ExecStart=/bin/bash -c 'source /opt/python_3.12/bin/activate && /usr/bin/semaphore server --config=/ansible/semaphore/etc/config.json'
SyslogIdentifier=semaphore
Restart=always
RestartSec=10s

[Install]
WantedBy=multi-user.target

Note: The service runs as user semaphore and group ansible, using a Python virtual environment.

👤 Service Account

A dedicated Active Directory account must be created to run the Semaphore UI service. Example PowerShell command:

New-ADUser -Name "Semaphore" -GivenName "Semaphore" -Surname "User" `
  -SamAccountName "semaphore" -UserPrincipalName "semaphore@refol.us" `
  -AccountPassword (Read-Host -AsSecureString "Input Password") -Enabled $true

🌐 Web Host

Semaphore UI is accessible at: https://semaphore.refol.us

🛠️ Troubleshooting

Semaphore does not maintain its own log file. All output is sent to system messages.
View logs with:

sudo journalctl -u semaphore -f

📦 Deployment with Ansible

Semaphore UI can be provisioned and deployed using Ansible playbooks. The playbook calls the entra_id_oauth2 role which registers the Semaphore application to EntraID and generates credentials. The Semaphore role writes those credentials into config.json as an OIDC provider named azure.

1. Provision Ubuntu VM

ansible-playbook -u ansible -k -i inventory/ansible/inventory.ini playbooks/provision_vm.yml -l ansible-1

2. Deploy Semaphore UI

ansible-playbook -k -i inventory/ansible/inventory.ini playbooks/deploy_semaphoreui.yml

Uses the postgresql_setup role plus Python/Ansible modules.

3. Configure Reverse Proxy

ansible-playbook -k -i inventory/ansible/inventory.ini playbooks/rproxy/config_rproxy.yml

4. Generate Certificates

ansible-playbook -k -i inventory/ansible/inventory.ini playbooks/certs/generate_certs.yml
ansible-playbook -k -i inventory/ansible/inventory.ini playbooks/certs/stage_certs.yml

5. Backup Database

ansible-playbook -k -i inventory/ansible/inventory.ini playbooks/semaphoreui/backup_db.yml

Uses pg_dump to /nfs/backups/ with filenames prefixed semaphoreui_YYYY-MM-DD.

🚀 Using Semaphore

After deployment:

Minimum Setup

Task Templates & Inventory

📘 Set Up using Ansible

For detailed instructions on configuring Semaphore projects, templates, dynamic templates, views, keystores, and schedules using Ansible,

👉 See: Configure Semaphore UI Projects Runbook

This runbook provides step-by-step examples, YAML snippets, and guidance for safely managing your Semaphore UI configuration in a fully declarative way.

⚡ Automatic Configuration via GitHub Actions

Semaphore UI configuration is applied automatically whenever files under:

inventory/semaphore/group_vars/semaphore/

are modified.

A dedicated GitHub Action detects these changes and triggers the Setup Semaphore task inside the Home Lab project in Semaphore UI.

This ensures that any update to your declarative inventory immediately results in a fresh configuration run—no manual playbook execution required.

👉 See: Trigger Semaphore Setup Workflow for a full breakdown of how the automation works.

Quick Preview: Manual Execution (Optional)

If you prefer to run the configuration locally—or need to test changes before pushing—you can still execute the playbook manually:

ansible-playbook -k -i inventory/semaphore/inventory.ini setup-semaphore.yml

Notes: