Semaphore UI

https://semaphoreui.com/docs
Admin
Semaphore UI is a modern user interface and powerful API for managing and automating IT...
Tokens:41,096
Snippets:647
Trust Score:7.8
Update:1 month ago
Show doc for...
Tokens:
Raw
### Example Runner Configuration File

Source: https://semaphoreui.com/docs/admin-guide/runners

The structure of the JSON configuration file generated by the setup command, containing host and token details.

```json
{
  "tmp_path": "/tmp/semaphore",
  "web_host": "https://semaphore_server_host",
  
  // Here you can provide other settings, for example: git_client, ssh_config_path, etc.  
  // ...  
    
  // Runner specific options  
  "runner": {  
    "token": "your runner's token",  
    // or  
    "token_file": "path/to/the/file/where/runner/saves/token"
  
    // Here you can provide other runner-specific options, 
    // which will be used for runner registration, for example: 
    // max_parallel_tasks, webhook, one_off, etc.
    // ...
  }
}
```

--------------------------------

### Start the runner

Source: https://semaphoreui.com/docs/admin-guide/cli/runners

Starts the runner to connect to the server and accept tasks.

```bash
semaphore runner start --config /path/to/config.runner.json
```

--------------------------------

### Full Systemd Service Examples

Source: https://semaphoreui.com/docs/admin-guide/installation_manually

Complete unit file examples for Python modules in user-context or virtual environments.

```ini
[Unit]  
Description=Semaphore UI  
Documentation=https://semaphoreui.com/docs  
Wants=network-online.target  
After=network-online.target  
ConditionPathExists=/usr/bin/semaphore  
ConditionPathExists=/etc/semaphore/config.json  
  
[Service]  
User=semaphore  
Group=semaphore  
Restart=always  
RestartSec=10s  
Environment="PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:~/.local/bin"  
  
ExecStartPre=/bin/bash -c 'ansible-galaxy collection install --upgrade -r /home/semaphore/requirements.yml'  
ExecStartPre=/bin/bash -c 'ansible-galaxy role install --force -r /home/semaphore/requirements.yml'  
ExecStartPre=/bin/bash -c 'python3 -m pip install --upgrade --user -r /home/semaphore/requirements.txt'  
  
ExecStart=/usr/bin/semaphore server --config /etc/semaphore/config.json  
ExecReload=/bin/kill -HUP $MAINPID  
  
[Install]  
WantedBy=multi-user.target  
```

```ini
[Unit]  
Description=Semaphore UI  
Documentation=https://semaphoreui.com/docs  
Wants=network-online.target  
After=network-online.target  
ConditionPathExists=/usr/bin/semaphore  
ConditionPathExists=/etc/semaphore/config.json  
  
[Service]  
User=semaphore  
Group=semaphore  
Restart=always  
RestartSec=10s  
  
ExecStartPre=/bin/bash -c 'source /home/semaphore/venv/bin/activate \
                           && python3 -m pip install --upgrade -r /home/semaphore/requirements.txt'  
ExecStartPre=/bin/bash -c 'source /home/semaphore/venv/bin/activate \
                           && ansible-galaxy collection install --upgrade -r /home/semaphore/requirements.yml \
                           && ansible-galaxy role install --force -r /home/semaphore/requirements.yml'  
  
ExecStart=/bin/bash -c 'source /home/semaphore/venv/bin/activate \
                        && /usr/bin/semaphore server --config /etc/semaphore/config.json'  
ExecReload=/bin/kill -HUP $MAINPID  
  
[Install]  
WantedBy=multi-user.target  
```

--------------------------------

### Run interactive setup

Source: https://semaphoreui.com/docs/admin-guide/configuration/cli

Executes the initial configuration wizard for the Semaphore CLI.

```bash
semaphore setup
```

--------------------------------

### Install requirements in user-context

Source: https://semaphoreui.com/docs/admin-guide/installation_manually

Commands to manually install collections and roles as the semaphore user.

```bash
sudo su --login semaphore  
ansible-galaxy collection install --upgrade -r /home/semaphore/requirements.yml  
ansible-galaxy role install --force -r /home/semaphore/requirements.yml
```

--------------------------------

### Install Kerberos Dependencies

Source: https://semaphoreui.com/docs/user-guide/inventory/kerberos

Install the necessary Kerberos client packages on the Semaphore host.

```bash
sudo apt install libkrb5-dev krb5-user  
```

--------------------------------

### Configure and Run Semaphore

Source: https://semaphoreui.com/docs/admin-guide/installation/package-manager

Commands to initialize the Semaphore configuration and start the server.

```bash
semaphore setup
```

```bash
semaphore server --config=./config.json
```

--------------------------------

### Start Semaphore Container

Source: https://semaphoreui.com/docs/admin-guide/installation/docker

Command to initialize and start the services defined in the docker-compose.yml file.

```bash
docker-compose up  
```

--------------------------------

### Example config.json structure

Source: https://semaphoreui.com/docs/admin-guide/configuration/config-file

A sample configuration file demonstrating database, authentication, runner, and logging settings.

```json
{
	"mysql_test": {
		"host": "127.0.0.1:3306",
		"user": "root",
		"pass": "***",
		"name": "semaphore"
	},

	"dialect": "mysql",

	"git_client": "go_git",

	"auth": {
		"totp": {
			"enabled": false,
			"allow_recovery": true
		}
	},

	"use_remote_runner": true,
	"runner_registration_token": "73fs***",

 	"tmp_path": "/tmp/semaphore",
 	"cookie_hash": "96Nt***",
 	"cookie_encryption": "x0bs***",
 	"access_key_encryption": "j1ia***",

	"max_tasks_per_template": 3,

	"schedule": {
		"timezone": "UTC"
	},

	"log": {
		"events": {
			"enabled": true,
			"path": "./events.log"
		}
	},

	"process": {
		"chroot": "/opt/semaphore/sandbox"
	}
 }
```

--------------------------------

### Start Runner Service

Source: https://semaphoreui.com/docs/admin-guide/runners

Launch the runner process using the specified configuration file.

```bash
semaphore runner start --config /path/to/your/config/file.json
```

--------------------------------

### Run interactive setup

Source: https://semaphoreui.com/docs/admin-guide/cli/runners

Initiates an interactive configuration process to create a runner configuration file.

```bash
semaphore runner setup --config /path/to/config.runner.json
```

--------------------------------

### Example requirements.txt file

Source: https://semaphoreui.com/docs/admin-guide/installation_manually

A list of Python packages required for Ansible operations.

```text
ansible  
# for common jinja-filters  
netaddr  
jmespath  
# for common modules  
pywinrm  
passlib  
requests  
docker  
```

--------------------------------

### Check version

Source: https://semaphoreui.com/docs/admin-guide/cli

Print the currently installed version of the Semaphore binary.

```bash
semaphore version  
```

--------------------------------

### Download and Setup Semaphore Binaries

Source: https://semaphoreui.com/docs/admin-guide/installation/binary-file

Commands to download, extract, and initialize Semaphore for different operating systems.

```bash
wget https://github.com/semaphoreui/semaphore/releases/download/v2.17.15/semaphore_2.17.15_linux_amd64.tar.gz  
  
tar xf semaphore_2.17.15_linux_amd64.tar.gz  
  
./semaphore setup  
```

```bash
wget https://github.com/semaphoreui/semaphore/releases/download/v2.17.15/semaphore_2.17.15_linux_arm64.tar.gz  
  
tar xf semaphore_2.17.15_linux_arm64.tar.gz  
  
./semaphore setup  
```

```powershell
Invoke-WebRequest `  
-Uri ("https://github.com/semaphoreui/semaphore/releases/" +  
      "download/v2.17.15/semaphore_2.17.15_windows_amd64.zip") `  
  
-OutFile semaphore.zip  
  
Expand-Archive -Path semaphore.zip  -DestinationPath ./  
  
./semaphore setup  
```

--------------------------------

### Run interactive setup

Source: https://semaphoreui.com/docs/admin-guide/cli

Execute the initial configuration wizard to generate secrets, create a config file, run migrations, and add an admin user.

```bash
semaphore setup  
```

--------------------------------

### Install requirements in user context

Source: https://semaphoreui.com/docs/admin-guide/installation_manually

Commands and tasks to install Python dependencies for the semaphore user.

```bash
sudo --login -u semaphore python3 -m pip install --user --upgrade -r /home/semaphore/requirements.txt  
```

```yaml
- name: Install requirements  
  ansible.builtin.pip:  
    requirements: '/home/semaphore/requirements.txt'  
    extra_args: '--user --upgrade'  
  become_user: 'semaphore'  
```

--------------------------------

### Start Semaphore Server

Source: https://semaphoreui.com/docs/admin-guide/installation/binary-file

Command to launch the Semaphore server using a specific configuration file.

```bash
./semaphore server --config=./config.json  
```

--------------------------------

### Start Semaphore with configuration file

Source: https://semaphoreui.com/docs/admin-guide/configuration/config-file

Commands to launch the server or runner using a specific configuration file path.

```bash
semaphore server --config ./config.json
```

```bash
semaphore runner start --config ./config.json
```

--------------------------------

### Vault Check Output Example

Source: https://semaphoreui.com/docs/admin-guide/cli/vaults

Example output showing the status and row count for encryption keys.

```text
Access keys: 12 total  
  IFTi6Ipik8Q: 12 rows — active  
  rcGGC2AQfKo: 0 rows — retired, SAFE TO REMOVE  
JWT signing key: IFTi6Ipik8Q
```

--------------------------------

### Start OpenLDAP Server with Docker

Source: https://semaphoreui.com/docs/admin-guide/ldap

Command to launch a test OpenLDAP container with pre-configured admin and user accounts.

```bash
docker run -d --name openldap \
  -p 1389:1389 \
  -p 1636:1636 \
  -e LDAP_ADMIN_USERNAME=admin \
  -e LDAP_ADMIN_PASSWORD=pwd \
  -e LDAP_USERS=user1 \
  -e LDAP_PASSWORDS=pwd \
  -e LDAP_ROOT=dc=example,dc=org \
  -e LDAP_ADMIN_DN=cn=admin,dc=example,dc=org \
  bitnami/openldap:latest
```

--------------------------------

### Install Semaphore via Package Manager

Source: https://semaphoreui.com/docs/admin-guide/installation/package-manager

Commands to download and install Semaphore packages for various Linux distributions and architectures.

```bash
wget https://github.com/semaphoreui/semaphore/releases/\
download/v2.17.15/semaphore_2.17.15_linux_amd64.deb  
  
sudo dpkg -i semaphore_2.17.15_linux_amd64.deb
```

```bash
wget https://github.com/semaphoreui/semaphore/releases/\
download/v2.17.15/semaphore_2.17.15_linux_arm64.deb  
  
sudo dpkg -i semaphore_2.17.15_linux_arm64.deb
```

```bash
wget https://github.com/semaphoreui/semaphore/releases/\
download/v2.17.15/semaphore_2.17.15_linux_amd64.rpm  
  
sudo yum install semaphore_2.17.15_linux_amd64.rpm
```

```bash
wget https://github.com/semaphoreui/semaphore/releases/\
download/v2.17.15/semaphore_2.17.15_linux_arm64.rpm  
  
sudo yum install semaphore_2.17.15_linux_arm64.rpm
```

--------------------------------

### Launch runner process

Source: https://semaphoreui.com/docs/admin-guide/cli/runners

Commands to start the runner in the foreground or as a background daemon.

```bash
# Run in the foreground:  
./semaphore runner start --config /path/to/config.runner.json  
  
# Run as a daemon:  
nohup ./semaphore runner start --config /path/to/config.runner.json &
```

--------------------------------

### Start runner mode

Source: https://semaphoreui.com/docs/admin-guide/cli

Initialize the Semaphore instance in task runner mode.

```bash
semaphore runner start --config /path/to/config.json  
```

--------------------------------

### Install requirements in a virtualenv

Source: https://semaphoreui.com/docs/admin-guide/installation_manually

Commands to activate a virtual environment and install Ansible dependencies.

```bash
sudo su --login semaphore  
source /home/semaphore/venv/bin/activate  
# verify we are using python3 from inside the venv  
which python3  
> /home/semaphore/venv/bin/python3  
  
ansible-galaxy collection install --upgrade -r /home/semaphore/requirements.yml  
ansible-galaxy role install --force -r /home/semaphore/requirements.yml  
  
deactivate
```

--------------------------------

### Documenting API Usage for Task Templates

Source: https://semaphoreui.com/docs/user-guide/task-templates/prompts

Example structure for documenting available prompts and their expected JSON payload format when triggering tasks via the API.

```text
## API Usage  
  
Enabled prompts:  
- `limit`: Host pattern (optional)  
- `tags`: Comma-separated tag list (optional)  
  
Example:  
POST /api/project/1/tasks  
{  
  "template_id": 123,  
  "limit": "webservers:&production",  
  "tags": "deploy"  
}  
```

--------------------------------

### Log File Entry Format

Source: https://semaphoreui.com/docs/admin-guide/logs

Example of the format used for each line in the generated log files.

```text
2024-01-03 12:00:34 user=234234 object=template action=delete
```

--------------------------------

### OpenLDAP Configuration for Semaphore

Source: https://semaphoreui.com/docs/admin-guide/ldap

Example configuration JSON tailored for the OpenLDAP Docker container.

```json
{
	"ldap_binddn": "cn=admin,dc=example,dc=org",
	"ldap_bindpassword": "pwd",
	"ldap_server": "ldap-server.com:1389",
	"ldap_searchdn": "dc=example,dc=org",
	"ldap_searchfilter": "(&(objectClass=inetOrgPerson)(uid=%s))",
	"ldap_mappings": {
		"mail": "{{ .cn }}@ldap.your-domain.com",
		"uid": "|",
		"cn": "cn"
	},
	"ldap_enable": true,
	"ldap_needtls": false
}
```

--------------------------------

### Run Semaphore with LDAP via Docker

Source: https://semaphoreui.com/docs/admin-guide/ldap

Example of running the Semaphore UI container with LDAP settings provided as environment variables.

```bash
docker run -d -p 3000:3000 --name semaphore \
  -e SEMAPHORE_DB_DIALECT=bolt \
  -e SEMAPHORE_ADMIN=admin \
  -e SEMAPHORE_ADMIN_PASSWORD=changeme \
  -e SEMAPHORE_ADMIN_NAME=Admin \
  -e SEMAPHORE_ADMIN_EMAIL=admin@localhost \
  -e SEMAPHORE_LDAP_ENABLE=yes \
  -e SEMAPHORE_LDAP_SERVER=ldap-server.com:1389 \
  -e SEMAPHORE_LDAP_BIND_DN=cn=admin,dc=example,dc=org \
  -e SEMAPHORE_LDAP_BIND_PASSWORD=pwd \
  -e SEMAPHORE_LDAP_SEARCH_DN=dc=example,dc=org \
  -e 'SEMAPHORE_LDAP_SEARCH_FILTER=(&(objectClass=inetOrgPerson)(uid=%s))' \
  -e 'SEMAPHORE_LDAP_MAPPING_MAIL={{ .cn }}@ldap.your-domain.com' \
  -e 'SEMAPHORE_LDAP_MAPPING_UID=|' \
  -e 'SEMAPHORE_LDAP_MAPPING_CN=cn' \
  semaphoreui/semaphore:latest
```

--------------------------------

### Install requirements in a virtual environment

Source: https://semaphoreui.com/docs/admin-guide/installation_manually

Commands and tasks to create and populate a Python virtual environment for Ansible.

```bash
sudo su --login semaphore  
python3 -m pip install --user virtualenv  
python3 -m venv /home/semaphore/venv  
# activate the context of the virtual environment  
source /home/semaphore/venv/bin/activate  
# verify we are using python3 from inside the venv  
which python3  
> /home/semaphore/venv/bin/python3  
python3 -m pip install --upgrade -r /home/semaphore/requirements.txt  
# disable the context to the virtual environment  
deactivate  
```

```yaml
- name: Create virtual environment and install requirements into it  
  ansible.builtin.pip:  
    requirements: '/home/semaphore/requirements.txt'  
    virtualenv: '/home/semaphore/venv'  
    state: present  # or 'latest' to upgrade the requirements  
```

--------------------------------

### Generate Let's Encrypt certificate with Certbot

Source: https://semaphoreui.com/docs/admin-guide/security/network

Use Certbot to install and generate an SSL certificate for Apache.

```bash
sudo snap install certbot
sudo certbot --apache -n --agree-tos -d example.com -m mail@example.com
```

--------------------------------

### Define Ansible Playbook with Tags

Source: https://semaphoreui.com/docs/user-guide/task-templates/prompts

Example playbook structure using tags to categorize tasks for selective execution via prompts.

```yaml
---
- hosts: all
  tasks:
    - name: Install packages
      apt:
        name: nginx
      tags: install

    - name: Deploy application
      copy:
        src: app.tar.gz
        dest: /opt/app/
      tags: deploy

    - name: Restart service
      service:
        name: nginx
        state: restarted
      tags: restart
```

--------------------------------

### View Task Output

Source: https://semaphoreui.com/docs/user-guide/inventory/consul-dynamic-inventory

Example output displayed in the task log after executing a playbook with a Consul inventory script.

```text
TASK [Hello World] *************************************************************  
ok: [node-01] => {  
    "msg": "Hello from node-01"  
}  
ok: [node-02] => {  
    "msg": "Hello from node-02"  
}  

```

--------------------------------

### Access task details via environment variables

Source: https://semaphoreui.com/docs/admin-guide/cicd

Examples of retrieving task details using environment variables in Bash, PowerShell, and Python.

```bash
echo "$SEMAPHORE_TASK_DETAILS_TYPE"  
echo "$SEMAPHORE_TASK_DETAILS_TARGET_VERSION"  
```

```powershell
$env:SEMAPHORE_TASK_DETAILS_TYPE  
$env:SEMAPHORE_TASK_DETAILS_INCOMING_VERSION  
```

```python
import os  
  
task_type = os.getenv("SEMAPHORE_TASK_DETAILS_TYPE")  
target_version = os.getenv("SEMAPHORE_TASK_DETAILS_TARGET_VERSION")  
incoming_version = os.getenv("SEMAPHORE_TASK_DETAILS_INCOMING_VERSION")  
```

--------------------------------

### Claim Expression Example

Source: https://semaphoreui.com/docs/admin-guide/ldap

Example of a claim expression used to map user attributes.

```text
email | {{ .username }}@your-domain.com
```

--------------------------------

### View Migration Help

Source: https://semaphoreui.com/docs/admin-guide/cli/migrations

Displays all available migration commands and options.

```bash
semaphore migrate --help  
```

--------------------------------

### View help for projects command

Source: https://semaphoreui.com/docs/admin-guide/cli/projects

Displays the help menu for the projects command.

```bash
semaphore projects --help
```

--------------------------------

### Display runner help

Source: https://semaphoreui.com/docs/admin-guide/cli/runners

Prints the help menu for the runner command.

```bash
semaphore runner --help
```

--------------------------------

### Define Ansible requirements

Source: https://semaphoreui.com/docs/admin-guide/installation_manually

Example content for a requirements.yml file to specify collections and roles.

```yaml
---
  
collections:  
  - 'namespace.collection'  
  # for common collections:  
  - 'community.general'  
  - 'ansible.posix'  
  - 'community.mysql'  
  - 'community.crypto'  
  
roles:  
  - src: 'namespace.role'
```

--------------------------------

### Initialize Runner Configuration

Source: https://semaphoreui.com/docs/admin-guide/runners

Generate the initial runner configuration file at the specified path.

```bash
semaphore runner setup --config /path/to/your/config/file.json
```

--------------------------------

### GET /api/metrics

Source: https://semaphoreui.com/docs/admin-guide/metrics

Retrieves system and task metrics in Prometheus text exposition format.

```APIDOC
## GET /api/metrics

### Description
Returns metrics in Prometheus text exposition format, including Go runtime process stats and Semaphore-specific task metrics.

### Method
GET

### Endpoint
/api/metrics

### Authentication
Requires HTTP Basic Authentication using credentials configured via environment variables or configuration file.

### Response
#### Success Response (200)
- **Content-Type** (text/plain) - Prometheus text exposition format.

#### Error Response (401)
- **Status** (401) - Returned if metrics are disabled or authentication credentials are missing/incorrect.
```

--------------------------------

### Manage Semaphore Service

Source: https://semaphoreui.com/docs/admin-guide/installation/binary-file

Commands to reload, start, check status, and enable the Semaphore service.

```bash
sudo systemctl daemon-reload  
sudo systemctl start semaphore  
```

```bash
sudo systemctl status semaphore  
```

```bash
sudo systemctl enable semaphore  
```

--------------------------------

### List CLI commands

Source: https://semaphoreui.com/docs/admin-guide/cli

Display all available commands and help information for the Semaphore binary.

```bash
semaphore help  
```

--------------------------------

### Import project backups

Source: https://semaphoreui.com/docs/admin-guide/cli/projects

Imports project backups from a single file or a directory of files.

```bash
# Import a single backup:  
semaphore project import --file project-3.backup  
  
# Import a single backup under a new name:  
semaphore project import --file project-3.backup --project-name "My Project (copy)"  
  
# Import every backup in a directory:  
semaphore project import --dir /path/to/backups
```

--------------------------------

### Mount Python Requirements

Source: https://semaphoreui.com/docs/admin-guide/installation/docker

Update the docker-compose.yml to mount a requirements.txt file for automatic dependency installation.

```yaml
services:  
  semaphore:  
    restart: unless-stopped  
    ports:  
      - 3000:3000  
    image: semaphoreui/semaphore:latest  
    volumes:  
      - ./requirements.txt:/etc/semaphore/requirements.txt  
```

--------------------------------

### Configure license key in config.json

Source: https://semaphoreui.com/docs/admin-guide/license

Use the subscription key field in the JSON configuration file to activate the license.

```json
{
  "subscription": {  
    "key": "YOUR_LICENSE_KEY"  
  }  
}
```

--------------------------------

### API Token Management Help

Source: https://semaphoreui.com/docs/admin-guide/cli/users

Displays help information for API token management commands.

```bash
semaphore user token --help  
```

--------------------------------

### Configure license key file in config.json

Source: https://semaphoreui.com/docs/admin-guide/license

Specify a path to a file containing the license key using the key_file field.

```json
{
  "subscription": {  
    "key_file": "/run/secrets/semaphore-license-key"  
  }  
}
```

--------------------------------

### Ansible Task JWT Authentication

Source: https://semaphoreui.com/docs/user-guide/task-templates/jwt

Example of using the JWT token in an Ansible task to authenticate against OpenBao.

```yaml
- hosts: localhost  
  gather_facts: false  
  tasks:  
    - name: Read secret from OpenBao KVv2 via JWT auth  
      ansible.builtin.set_fact:  
        openbao_secret_value: >-  
        {{ lookup(  
          'community.hashi_vault.hashi_vault',  
          secret='kv/data/semaphore/demo:value',  
          auth_method='jwt',  
          url='https://bao.example.com',  
          role_id='semaphore-demo-role',  
          jwt=lookup('ansible.builtin.env', 'SEMAPHORE_JWT')  
        ) }}
```

--------------------------------

### View User CLI Help

Source: https://semaphoreui.com/docs/admin-guide/cli/users

Displays the help menu for user-related commands.

```bash
semaphore user --help  
```

--------------------------------

### Accessing SEMAPHORE_JWT in Tasks

Source: https://semaphoreui.com/docs/user-guide/task-templates/jwt

Examples of retrieving the JWT token from the environment variable in different task types.

```bash
#!/usr/bin/env bash  
  
# Bash example  
echo "Look at my fancy token: $SEMAPHORE_JWT"  
```

```yaml
- name: Read secret from OpenBao KVv2 via JWT auth  
  ansible.builtin.set_fact:  
    openbao_secret_value: >-  
      {{ lookup(  
        'community.hashi_vault.hashi_vault',  
        secret='kv/data/semaphore/demo:value',  
        auth_method='jwt',  
        url='https://bao.example.com',  
        role_id=bao_role,  
        jwt=lookup('ansible.builtin.env', 'SEMAPHORE_JWT')  
      ) }}
```

--------------------------------

### Configure license key file via environment variable

Source: https://semaphoreui.com/docs/admin-guide/license

Set the SEMAPHORE_SUBSCRIPTION_KEY_FILE environment variable to point to the license key file.

```bash
export SEMAPHORE_SUBSCRIPTION_KEY_FILE=/run/secrets/semaphore-license-key
```

--------------------------------

### JWKS response format

Source: https://semaphoreui.com/docs/admin-guide/security/jwt

Example of the JSON response returned by the JWKS endpoint following RFC 7517.

```json
{
  "keys": [
    {
      "kty": "EC",
      "crv": "P-256",
      "kid": "...",
      "use": "sig",
      "alg": "ES256",
      "x": "...",
      "y": "..."
    }
  ]
}
```

--------------------------------

### Activate Virtual Environment for Troubleshooting

Source: https://semaphoreui.com/docs/admin-guide/installation_manually

Verify the Python environment by activating the virtualenv and checking the path to the python3 executable.

```bash
source /home/semaphore/venv/bin/activate  
# verify we are using python3 from inside the venv  
which python3  
> /home/semaphore/venv/bin/python3  
  
# troubleshooting  
  
deactivate  
```

--------------------------------

### Access semaphore_vars in Ansible

Source: https://semaphoreui.com/docs/admin-guide/cicd

Examples of the semaphore_vars structure provided to Ansible playbooks for build and deploy tasks.

```yaml
semaphore_vars:  
    task_details:  
        type: build  
        username: user123  
        message: New version of some feature  
        target_version: 1.5.33  
```

```yaml
semaphore_vars:  
    task_details:  
        type: deploy  
        username: user123  
        message: Deploy new feature to servers  
        incoming_version: 1.5.33  
```

--------------------------------

### Add a New User

Source: https://semaphoreui.com/docs/admin-guide/cli/users

Creates a new user account with specified credentials and administrative status.

```bash
semaphore user add \
    --admin \
    --login newAdmin \
    --email new-admin@example.com \
    --name "New Admin" \
    --password "New$Password"  
```

--------------------------------

### Enable Apache modules

Source: https://semaphoreui.com/docs/admin-guide/reverse-proxy/apache

Required modules for proxying HTTP and WebSocket traffic.

```bash
sudo a2enmod proxy  
sudo a2enmod proxy_http  
sudo a2enmod proxy_wstunnel  
```

--------------------------------

### Access the JWKS endpoint

Source: https://semaphoreui.com/docs/admin-guide/security/jwt

Retrieve the public signing key from the JWKS endpoint using a GET request.

```http
GET /.well-known/jwks.json
```

--------------------------------

### Additional Service Integrations

Source: https://semaphoreui.com/docs/admin-guide/installation_manually

Configuration snippets for MariaDB, Nginx, and syslog logging.

```ini
[Unit]  
Requires=mariadb.service  
```

```ini
[Unit]  
Wants=nginx.service  
```

```ini
[Service]  
StandardOutput=journal  
StandardError=journal  
SyslogIdentifier=semaphore  
```

--------------------------------

### Target Metadata Groups in Playbooks

Source: https://semaphoreui.com/docs/user-guide/inventory/consul-dynamic-inventory

Example of targeting an automatically generated metadata group within an Ansible playbook.

```yaml
- hosts: role_webserver  
  tasks:  
    - name: Restart nginx  
      ansible.builtin.service:  
        name: nginx  
        state: restarted  
```

--------------------------------

### Troubleshoot virtual environment

Source: https://semaphoreui.com/docs/admin-guide/installation_manually

Steps to activate and verify the virtual environment context for debugging.

```bash
sudo su --login semaphore  
source /home/semaphore/venv/bin/activate  
# verify we are using python3 from inside the venv  
which python3  
> /home/semaphore/venv/bin/python3  
  
# troubleshooting  
  
deactivate  
```

--------------------------------

### TOTP Management Help

Source: https://semaphoreui.com/docs/admin-guide/cli/users

Displays help information for TOTP (2FA) management commands.

```bash
semaphore user totp --help  
```

--------------------------------

### System Update Playbook

Source: https://semaphoreui.com/docs/user-guide/schedules

Example Ansible playbook for performing system updates, suitable for scheduling as a maintenance task.

```yaml
# Example playbook for system updates
---
- hosts: all
  become: yes
  tasks:
    - name: Update apt cache
      apt:
        update_cache: yes

    - name: Upgrade all packages
      apt:
        upgrade: yes

    - name: Remove dependencies that are no longer required
      apt:
        autoremove: yes
```

--------------------------------

### Ansible Gathering Facts Error Log

Source: https://semaphoreui.com/docs/admin-guide/troubleshooting

Example of the error output when Ansible fails to gather facts on localhost.

```text
4:10:16 PM  
TASK [Gathering Facts] *********************************************************  
4:10:17 PM  
fatal: [localhost]: FAILED! => changed=false  
```

--------------------------------

### Launch a Task via API

Source: https://semaphoreui.com/docs/admin-guide/api

Execute a task by providing the template ID and the bearer token in the request header.

```bash
curl -v -XPOST \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
-d '{"template_id": 1}' \
http://localhost:3000/api/project/1/tasks  

```

--------------------------------

### Telegram Configuration in config.json

Source: https://semaphoreui.com/docs/admin-guide/notifications/telegram

Example JSON structure for defining Telegram alert settings within the configuration file.

```json
{
    "telegram_alert": true,  
    "telegram_token": "64********:AAG****_rM6obyR********************",  
    "telegram_chat":  "",  
}
```

--------------------------------

### Use Docker Secrets for Credentials

Source: https://semaphoreui.com/docs/admin-guide/installation/docker

Example of using Docker Secrets to manage sensitive environment variables like passwords.

```yaml
secrets:  
  semaphore_admin_pw:  
    file: semaphore_admin_password.txt  
  
services:  
  semaphore:  
    restart: unless-stopped  
    ports:  
      - 3000:3000  
    image: semaphoreui/semaphore:latest  
    environment:  
      SEMAPHORE_ADMIN_PASSWORD_FILE: /run/secrets/semaphore_admin_pw  
      SEMAPHORE_ADMIN_NAME: admin  
      SEMAPHORE_ADMIN_EMAIL: admin@localhost  
      SEMAPHORE_ADMIN: admin  
```

--------------------------------

### Display Vault Help

Source: https://semaphoreui.com/docs/admin-guide/cli/vaults

View available commands and options for the vault utility.

```bash
semaphore vault --help
```

--------------------------------

### Configure license key via environment variable

Source: https://semaphoreui.com/docs/admin-guide/license

Set the SEMAPHORE_SUBSCRIPTION_KEY environment variable to provide the license key.

```bash
export SEMAPHORE_SUBSCRIPTION_KEY=YOUR_LICENSE_KEY
```

--------------------------------

### Compliance Check Playbook

Source: https://semaphoreui.com/docs/user-guide/schedules

Example Ansible playbook for running compliance scripts and fetching logs, suitable for scheduled security scans.

```yaml
# Example compliance check playbook
---
- hosts: all
  tasks:
    - name: Run compliance checks
      script: /path/to/compliance_script.sh

    - name: Collect compliance reports
      fetch:
        src: /var/log/compliance-report.log
        dest: reports/{{ inventory_hostname }}/
        flat: yes
```

--------------------------------

### Configure Gotify in config.json

Source: https://semaphoreui.com/docs/admin-guide/notifications/gotify

Define the Gotify alert status, server URL, and authentication token within the configuration file.

```json
{
    "gotify_alert": true,  
    "gotify_url":   "...",  
    "gotify_token": "***",  
}  
```

--------------------------------

### Enable metrics via environment variables

Source: https://semaphoreui.com/docs/admin-guide/metrics

Set these environment variables to enable the metrics endpoint and define authentication credentials.

```bash
SEMAPHORE_METRICS_ENABLED=true
SEMAPHORE_METRICS_USERNAME=prometheus
SEMAPHORE_METRICS_PASSWORD=changeme
```

--------------------------------

### Configure HashiCorp Vault Agent sink

Source: https://semaphoreui.com/docs/user-guide/key-store/hashicorp-vault

Example configuration for Vault Agent to handle auto-authentication and write the token to a file for Semaphore to read.

```hcl
auto_auth {
method {
    type = "approle"
    config = {
    role_id_file_path   = "/etc/vault/role-id"
    secret_id_file_path = "/etc/vault/secret-id"
    }
}
  
sink {
    type = "file"
    config = {
    path = "/etc/vault/token"
    }
}
}
```

--------------------------------

### Run database migration

Source: https://semaphoreui.com/docs/admin-guide/cli

Update the database schema to the latest version.

```bash
semaphore migrate --config /path/to/config.json  
```

--------------------------------

### GitLab OIDC Provider Configuration

Source: https://semaphoreui.com/docs/admin-guide/openid/gitlab

Add this configuration to your config.json file to enable GitLab authentication. Ensure the redirect_url matches your specific domain setup.

```json
{
	"oidc_providers": {  
        "gitlab": {  
            "display_name": "Sign in with GitLab",  
            "color": "orange",  
            "icon": "gitlab",  
            "provider_url": "https://gitlab.com",  
            "client_id": "***",  
            "client_secret": "gloas-***",  
            "redirect_url": "https://your-domain.com/api/auth/oidc/gitlab/redirect",  
            "username_claim": "|",  
            "order": 3  
        }  
	}
}
```

--------------------------------

### List All Users

Source: https://semaphoreui.com/docs/admin-guide/cli/users

Lists the logins of all registered users.

```bash
semaphore user list  
```

--------------------------------

### Basic Caddyfile configuration

Source: https://semaphoreui.com/docs/admin-guide/reverse-proxy/caddy

Standard configuration for proxying traffic to a local Semaphore UI instance on port 3000.

```Caddyfile
example.com {  
    reverse_proxy 127.0.0.1:3000 {  
        header_up X-Real-IP {client_ip}  
    }  
}  
```

--------------------------------

### Set Initiate Login URI

Source: https://semaphoreui.com/docs/admin-guide/openid/okta

The URI to be configured in the Okta Admin Console for IdP-initiated login.

```text
https://semaphore.example.com/api/auth/oidc/okta/initiate
```

--------------------------------

### Create Test Playbook

Source: https://semaphoreui.com/docs/user-guide/inventory/consul-dynamic-inventory

A basic Ansible playbook to verify connectivity to hosts discovered via the Consul inventory.

```yaml
- hosts: all  
  gather_facts: false  
  tasks:  
    - name: Hello World  
      ansible.builtin.debug:  
        msg: "Hello from {{ inventory_hostname }}"  
```

--------------------------------

### Verify Connectivity with Playbook

Source: https://semaphoreui.com/docs/user-guide/inventory/kerberos

A simple playbook to test WinRM connectivity using the configured Kerberos settings.

```yaml
- hosts: all  
  gather_facts: false  
  
  tasks:  
    - win_ping:  
```

--------------------------------

### Configure Environment Variables via JSON

Source: https://semaphoreui.com/docs/admin-guide/configuration/env-vars

Define static environment variables and a list of forwarded variables using a configuration file.

```json
{
  "env_vars": {  
    "HTTP_PROXY": "http://proxy.internal:3128",  
    "ANSIBLE_STDOUT_CALLBACK": "yaml"  
  },  
  "forwarded_env_vars": [  
    "AWS_ACCESS_KEY_ID",  
    "AWS_SECRET_ACCESS_KEY",  
    "GOOGLE_APPLICATION_CREDENTIALS"  
  ]  
}  
```

--------------------------------

### Base Systemd Service Template

Source: https://semaphoreui.com/docs/admin-guide/installation_manually

The foundational systemd unit file for Semaphore UI.

```ini
[Unit]  
Description=Semaphore UI  
Documentation=https://semaphoreui.com/docs  
Wants=network-online.target  
After=network-online.target  
ConditionPathExists=/usr/bin/semaphore  
ConditionPathExists=/etc/semaphore/config.json  
  
[Service]  
ExecStart=/usr/bin/semaphore server --config /etc/semaphore/config.json  
ExecReload=/bin/kill -HUP $MAINPID  
Restart=always  
RestartSec=10s  
  
[Install]  
WantedBy=multi-user.target  
```

--------------------------------

### Enable IdP-Initiated Login

Source: https://semaphoreui.com/docs/admin-guide/openid/okta

Add the allow_idp_initiated flag to the Okta provider configuration.

```json
{
  "oidc_providers": {
    "okta": {
      "...": "...",
      "allow_idp_initiated": true
    }
  }
}
```
Tokens:
Raw