### Start Server with Configuration File Path

Source: https://github.com/semaphoreui/semaphore-docs/blob/main/docs/admin-guide/cli.md

Example command to start the server, specifying the configuration file path. This is typically generated during the setup process.

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

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

### Interactive Runner Setup

Source: https://github.com/semaphoreui/semaphore-docs/blob/main/docs/admin-guide/cli/runners.md

Guides through creating a runner configuration file and optionally registering the runner with the server.

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

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

### Get Available Snap Options

Source: https://github.com/semaphoreui/semaphore-docs/blob/main/docs/admin-guide/configuration/snap.md

Use this command to list all configurable options for Semaphore when installed via Snap.

```bash
sudo snap get semaphore
```

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

### Install Semaphore Snap

Source: https://github.com/semaphoreui/semaphore-docs/blob/main/docs/admin-guide/installation/snap.md

Run this command to install Semaphore from the Snap store. Ensure you have snapd installed and configured.

```bash
sudo snap install semaphore
```

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

### Start Runner

Source: https://github.com/semaphoreui/semaphore-docs/blob/main/docs/admin-guide/cli/runners.md

Starts the runner, connects to the server, and begins accepting tasks using a specified configuration file.

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

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

### Interactive Setup for First-Time Configuration

Source: https://github.com/semaphoreui/semaphore-docs/blob/main/docs/admin-guide/cli.md

Use this command for initial setup, which includes generating secrets, configuring settings interactively, writing the config file, running database migrations, and creating the first admin user.

```bash
semaphore setup
```

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

### Gotify Configuration Example

Source: https://github.com/semaphoreui/semaphore-docs/blob/main/docs/admin-guide/notifications/gotify.md

Example JSON configuration for enabling and setting up Gotify notifications. Ensure to replace '...' with your Gotify server URL and '***' with your application token.

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

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

### Start the Runner

Source: https://github.com/semaphoreui/semaphore-docs/blob/main/docs/admin-guide/runners.md

Command to start the runner service using its configuration file.

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

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

### Setup a Runner

Source: https://github.com/semaphoreui/semaphore-docs/blob/main/docs/admin-guide/runners.md

Command to set up a runner, which creates a configuration file.

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

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

### Runner Configuration File Example

Source: https://github.com/semaphoreui/semaphore-docs/blob/main/docs/admin-guide/runners.md

Example structure of a runner configuration file, including temporary path, web host, and runner-specific options like token or token file.

```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.
    // ...
  }
}
```

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

### Example Semaphore Configuration File

Source: https://github.com/semaphoreui/semaphore-docs/blob/main/docs/admin-guide/configuration/config-file.md

This is a comprehensive example of a `config.json` file, illustrating various configuration options for Semaphore server and runners.

```javascript
{
	"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"
	}
 }
```

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

### Install Debian/Ubuntu Package

Source: https://github.com/semaphoreui/semaphore-docs/blob/main/docs/admin-guide/upgrading.md

Download and install the .deb package for Debian or Ubuntu systems.

```bash
wget https://github.com/semaphoreui/semaphore/releases/\ndownload/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/\ndownload/v2.17.15/semaphore_2.17.15_linux_arm64.deb

sudo dpkg -i semaphore_2.17.15_linux_arm64.deb
```

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

### Install Semaphore on Debian/Ubuntu (x64)

Source: https://github.com/semaphoreui/semaphore-docs/blob/main/docs/admin-guide/installation/package-manager.md

Download the .deb package for Debian/Ubuntu (x64) and install it using dpkg.

```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
```

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

### Accessing Task Details in Python

Source: https://github.com/semaphoreui/semaphore-docs/blob/main/docs/admin-guide/cicd.md

Provides an example of how to get task details like type, target version, and incoming version using environment variables in Python.

```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")
```

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

### Example Key Files in Directory

Source: https://github.com/semaphoreui/semaphore-docs/blob/main/docs/admin-guide/security/encryption.md

Illustrates the expected content of a directory used for key registry, where each file contains a base64 encoded key.

```text
/run/secrets/enc-keys/
secrets_key_primary.txt     # one base64 key per file
secrets_key_old.txt         # retired keys stay as files
options_key_primary.txt
```

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

### Mount requirements.txt for Python Packages

Source: https://github.com/semaphoreui/semaphore-docs/blob/main/docs/admin-guide/installation.md

Mount a requirements.txt file to install additional Python packages when starting a Semaphore container. The packages will be installed automatically.

```yaml
volumes:
  - /path/to/requirements.txt:/etc/semaphore/requirements.txt
```

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

### Install CentOS/RedHat Package

Source: https://github.com/semaphoreui/semaphore-docs/blob/main/docs/admin-guide/upgrading.md

Download and install the .rpm package for CentOS or RedHat systems.

```bash
wget https://github.com/semaphoreui/semaphore/releases/\ndownload/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/\ndownload/v2.17.15/semaphore_2.17.15_linux_arm64.rpm

sudo yum install semaphore_2.17.15_linux_arm64.rpm
```

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

### Start Semaphore Server with Configuration

Source: https://github.com/semaphoreui/semaphore-docs/blob/main/docs/admin-guide/configuration/config-file.md

Command to launch the Semaphore server, specifying the path to the configuration file.

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

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

### RocketChat Configuration Example

Source: https://github.com/semaphoreui/semaphore-docs/blob/main/docs/admin-guide/notifications/rocket.md

Example of RocketChat configuration settings in JSON format. Ensure the 'rocketchat_url' is correctly set.

```json
{
    "rocketchat_alert": true,
    "rocketchat_url":   "...",
}
```

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

### Install Semaphore on Debian/Ubuntu (ARM64)

Source: https://github.com/semaphoreui/semaphore-docs/blob/main/docs/admin-guide/installation/package-manager.md

Download the .deb package for Debian/Ubuntu (ARM64) and install it using dpkg.

```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
```

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

### Ansible requirements.yml Example

Source: https://github.com/semaphoreui/semaphore-docs/blob/main/docs/admin-guide/installation_manually.md

Define Ansible collections and roles to be installed using a requirements.yml file. This ensures consistent dependency management.

```yaml
---

collections:
  - 'namespace.collection'
  # for common collections:
  - 'community.general'
  - 'ansible.posix'
  - 'community.mysql'
  - 'community.crypto'

roles:
  - src: 'namespace.role'

```

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

### Authenticate and Login

Source: https://github.com/semaphoreui/semaphore-docs/blob/main/docs/admin-guide/api.md

This example shows how to authenticate with Semaphore and obtain a session cookie.

```APIDOC
## Authenticate and Login

### Description
Logs into Semaphore to obtain a session cookie for subsequent requests.

### Method
POST

### Endpoint
`/api/auth/login`

### Parameters
#### Request Body
- **auth** (string) - Required - Your Semaphore login username.
- **password** (string) - Required - Your Semaphore password. Special characters like '/' should be escaped (e.g., `slashy\\pass`).

### Request Example
```json
{
  "auth": "YOUR_LOGIN",
  "password": "YOUR_PASSWORD"
}
```
```

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

### Launch a Task

Source: https://github.com/semaphoreui/semaphore-docs/blob/main/docs/admin-guide/api.md

This example shows how to launch a new task within a project using an API token.

```APIDOC
## Launch a Task

### Description
Launches a new task within a specified project. Requires an API token for authentication.

### Method
POST

### Endpoint
`/api/project/{project_id}/tasks`

### Parameters
#### Path Parameters
- **project_id** (integer) - Required - The ID of the project where the task will be launched.

#### Headers
- **Authorization**: `Bearer YOUR_ACCESS_TOKEN` - Your API token.

#### Request Body
- **template_id** (integer) - Required - The ID of the task template to use for launching the task.

### Request Example
```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
```
```

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

### Configure Encryption Keys in YAML

Source: https://github.com/semaphoreui/semaphore-docs/blob/main/docs/admin-guide/security/encryption.md

Example configuration for managing multiple encryption keys, including specifying the active secrets key. This is used to migrate old single-key installs to a keys file.

```yaml
keys:
  old: { value: "<the old access_key_encryption value>" }
  new: { value: "<a freshly generated key>" }
active:
  secrets_key: new
```

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

### Start Semaphore Server

Source: https://github.com/semaphoreui/semaphore-docs/blob/main/docs/admin-guide/cli.md

Starts the Semaphore server, which includes the web UI and API. The `--config` flag specifies the path to the configuration file.

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

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

### Install Semaphore on CentOS (x64)

Source: https://github.com/semaphoreui/semaphore-docs/blob/main/docs/admin-guide/installation/package-manager.md

Download the .rpm package for CentOS (x64) and install it using yum.

```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
```

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

### Run Semaphore Server

Source: https://github.com/semaphoreui/semaphore-docs/blob/main/docs/admin-guide/installation/package-manager.md

Start the Semaphore server with a specified configuration file.

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

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

### Start Semaphore Runner with Configuration

Source: https://github.com/semaphoreui/semaphore-docs/blob/main/docs/admin-guide/configuration/config-file.md

Command to start a Semaphore runner, indicating the location of its configuration file.

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

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

### Docker Run Command for BoltDB Migration

Source: https://github.com/semaphoreui/semaphore-docs/blob/main/docs/admin-guide/cli/migrations.md

Example of running a Docker container for Semaphore UI to automatically import an existing BoltDB database on initial start. This utilizes the SEMAPHORE_MIGRATE_FROM_BOLTDB environment variable.

```docker
docker run --name semaphore \
-p 3000:3000 \
-e SEMAPHORE_DB_DIALECT=sqlite \
-e SEMAPHORE_ADMIN=admin \
-e SEMAPHORE_ADMIN_PASSWORD=changeme \
-e SEMAPHORE_ADMIN_NAME="Admin" \
-e SEMAPHORE_MIGRATE_FROM_BOLTDB=/var/lib/semaphore/database.boltdb \
-e SEMAPHORE_ADMIN_EMAIL=admin@localhost \
-v semaphore_data:/var/lib/semaphore \
-d semaphoreui/semaphore:v2.18.2
```

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

### Install Semaphore on CentOS (ARM64)

Source: https://github.com/semaphoreui/semaphore-docs/blob/main/docs/admin-guide/installation/package-manager.md

Download the .rpm package for CentOS (ARM64) and install it using yum.

```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
```

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

### Simple Ansible Playbook Example

Source: https://github.com/semaphoreui/semaphore-docs/blob/main/docs/user-guide/inventory/consul-dynamic-inventory.md

A basic Ansible playbook to test the dynamic inventory. It simply prints a 'Hello World' message including the inventory hostname.

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

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

### Document API Usage with Prompts

Source: https://github.com/semaphoreui/semaphore-docs/blob/main/docs/user-guide/task-templates/prompts.md

When triggering templates via API, document the available prompts and their expected format. This markdown example shows how to list prompts and provide an example API call.

```markdown
## 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"
}
```

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

### Download and Extract Semaphore for Linux (x64)

Source: https://github.com/semaphoreui/semaphore-docs/blob/main/docs/admin-guide/installation/binary-file.md

Use these commands to download the binary, extract it, and run the initial setup for Linux x64 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
```

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

### Install Ansible Collections and Roles Manually (User Context)

Source: https://github.com/semaphoreui/semaphore-docs/blob/main/docs/admin-guide/installation_manually.md

Installs Ansible collections and roles for the 'semaphore' user. Use this when not operating within a virtual environment.

```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

```

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

### Start OpenLDAP Server with Docker

Source: https://github.com/semaphoreui/semaphore-docs/blob/main/docs/admin-guide/ldap.md

Use this command to launch an OpenLDAP server instance with an admin account and a test user. Ensure the exposed ports are accessible.

```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
```

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

### Ansible Playbook Output Example

Source: https://github.com/semaphoreui/semaphore-docs/blob/main/docs/user-guide/inventory/consul-dynamic-inventory.md

This is an example of the expected output when Ansible runs a playbook using a Consul dynamic inventory script.

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

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

### Download and Extract Semaphore for Linux (ARM64)

Source: https://github.com/semaphoreui/semaphore-docs/blob/main/docs/admin-guide/installation/binary-file.md

Use these commands to download the binary, extract it, and run the initial setup for Linux ARM64 systems.

```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
```

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

### Install Kerberos Development Packages on Semaphore Host

Source: https://github.com/semaphoreui/semaphore-docs/blob/main/docs/user-guide/inventory/kerberos.md

Install necessary Kerberos development libraries and user tools on the Semaphore host. This is required for Kerberos functionality.

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

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

### Install Python Requirements Manually (User Context)

Source: https://github.com/semaphoreui/semaphore-docs/blob/main/docs/admin-guide/installation_manually.md

Manually install Python modules listed in requirements.txt for the 'semaphore' user. Ensure you are in the user's context or use 'sudo --login -u semaphore' to run this command.

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

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

### Example semaphore_vars for Deploy Tasks

Source: https://github.com/semaphoreui/semaphore-docs/blob/main/docs/admin-guide/cicd.md

Shows the structure of semaphore_vars for deploy tasks, including task type, username, message, and the incoming version.

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

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

### System Maintenance Playbook Example

Source: https://github.com/semaphoreui/semaphore-docs/blob/main/docs/user-guide/schedules.md

An example Ansible playbook for performing system updates, including updating the apt cache, upgrading packages, and removing unused dependencies. This can be scheduled to run weekly.

```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
```

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

### Run Semaphore Server

Source: https://github.com/semaphoreui/semaphore-docs/blob/main/docs/admin-guide/installation/binary-file.md

Command to start the Semaphore server with a specified configuration file. Ensure the config file path is correct.

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

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

### Example semaphore_vars for Build Tasks

Source: https://github.com/semaphoreui/semaphore-docs/blob/main/docs/admin-guide/cicd.md

Illustrates the structure of semaphore_vars for build tasks, including task type, username, message, and target version.

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

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

### Download and Extract Semaphore for Windows (x64)

Source: https://github.com/semaphoreui/semaphore-docs/blob/main/docs/admin-guide/installation/binary-file.md

Use these PowerShell commands to download the binary, extract it, and run the initial setup for Windows x64 systems.

```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
```

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

### Gitea OIDC Configuration Example

Source: https://github.com/semaphoreui/semaphore-docs/blob/main/docs/admin-guide/openid/gitea.md

This JSON snippet shows the configuration for integrating Gitea as an OIDC provider. Ensure the `client_id`, `client_secret`, and `redirect_url` are correctly set for your Gitea instance and Semaphore.

```json
"oidc_providers": {
    "github": {
        "icon": "github",
        "display_name": "Sign in with gitea instance",
        "client_id": "123-456-789",
        "client_secret": "**********",
        "redirect_url": "https://your-semaphore.tld/api/auth/oidc/github/redirect",
        "endpoint": {
            "auth": "https://your-gitea.tld/login/oauth/authorize",
            "token": "https://your-gitea.tld/login/oauth/access_token",
            "userinfo": "https://your-gitea.tld/api/v1/user"
        },
        "scopes": ["read:user", "user:email"],
        "username_claim": "login",
        "email_claim": "email",
        "name_claim": "full_name",
        "order": 1
    }
}
```

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

### Start Semaphore with Docker Compose

Source: https://github.com/semaphoreui/semaphore-docs/blob/main/docs/admin-guide/installation/docker.md

Command to launch the Semaphore services defined in your docker-compose.yml file.

```bash
docker-compose up
```

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

### Configure OIDC Providers in JSON

Source: https://github.com/semaphoreui/semaphore-docs/blob/main/docs/admin-guide/openid.md

Example JSON structure for defining multiple OIDC providers in the configuration.

```json
{
  "oidc_providers": {
    "mysso": {
      "display_name": "Sign in with MySSO",
      "color": "orange",
      "icon": "login",
      "provider_url": "https://mysso-provider.com",
      "client_id": "***",
      "client_secret": "***",
      "redirect_url": "https://your-domain.com/api/auth/oidc/mysso/redirect"
    }
  }
}
```

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

### Example Playbook for WinRM + Kerberos

Source: https://github.com/semaphoreui/semaphore-docs/blob/main/docs/user-guide/inventory/kerberos.md

A basic Ansible playbook to verify connectivity to Windows hosts using WinRM and Kerberos authentication. This task uses the `win_ping` module.

```yaml
- hosts: all
  gather_facts: false

  tasks:
    - win_ping:
```

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

### DingTalk Configuration Example

Source: https://github.com/semaphoreui/semaphore-docs/blob/main/docs/admin-guide/notifications/ding.md

Use this JSON snippet to configure DingTalk alerts in your settings. Ensure the 'dingtalk_url' is correctly set.

```json
{
    "dingtalk_alert": true,
    "dingtalk_url":   "...",
}
```

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

### Display Help Information

Source: https://github.com/semaphoreui/semaphore-docs/blob/main/docs/admin-guide/cli.md

Run this command to list all available commands and their usage.

```bash
semaphore help
```

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

### Mount Requirements File for Python Dependencies

Source: https://github.com/semaphoreui/semaphore-docs/blob/main/docs/admin-guide/installation/docker.md

Example of updating the docker-compose.yml to mount a local requirements.txt file into the Semaphore container, allowing automatic installation of Python packages.

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

```

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

### Systemd Service for Virtualenv Python Modules

Source: https://github.com/semaphoreui/semaphore-docs/blob/main/docs/admin-guide/installation_manually.md

Configure the systemd service to run Semaphore UI within a virtual environment. This setup activates the virtualenv before executing commands for installing Python requirements and Ansible modules.

```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
```

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

### Install Ansible Collections and Roles Manually (Virtualenv)

Source: https://github.com/semaphoreui/semaphore-docs/blob/main/docs/admin-guide/installation_manually.md

Installs Ansible collections and roles within a specified virtual environment for the 'semaphore' user. Activates the virtual environment before installation.

```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

```

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

### Claim Expression Example

Source: https://github.com/semaphoreui/semaphore-docs/blob/main/docs/admin-guide/ldap.md

An example of a claim expression used for mapping user attributes. This specific example shows how to construct an email address if the primary email claim is empty.

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

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

### Install Python Requirements with Ansible (User Context)

Source: https://github.com/semaphoreui/semaphore-docs/blob/main/docs/admin-guide/installation_manually.md

Automate the installation of Python modules specified in requirements.txt for the 'semaphore' user using Ansible. This ensures the modules are installed with the '--user' flag.

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

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

### Show CLI help for users

Source: https://github.com/semaphoreui/semaphore-docs/blob/main/docs/admin-guide/cli/users.md

Displays available user management commands and their options.

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

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

### Show Help for Projects Command

Source: https://github.com/semaphoreui/semaphore-docs/blob/main/docs/admin-guide/cli/projects.md

Displays the help information for the main 'semaphore projects' command.

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

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

### Show CLI help for user tokens

Source: https://github.com/semaphoreui/semaphore-docs/blob/main/docs/admin-guide/cli/users.md

Displays available commands for managing user API tokens.

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

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

### Show All Migration Commands

Source: https://github.com/semaphoreui/semaphore-docs/blob/main/docs/admin-guide/cli/migrations.md

Run this command to view all available migration subcommands and their options.

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

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

### Example config.json for Telegram Alerts

Source: https://github.com/semaphoreui/semaphore-docs/blob/main/docs/admin-guide/notifications/telegram.md

This JSON object shows an example of how to configure Telegram alerts within the config.json file.

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

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

### Launch a Task via API

Source: https://github.com/semaphoreui/semaphore-docs/blob/main/docs/admin-guide/api.md

This command demonstrates how to launch a new task for a specific project using an API token. Replace 'YOUR_ACCESS_TOKEN' and project ID as needed.

```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
```

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

### Set up Python Virtual Environment Manually

Source: https://github.com/semaphoreui/semaphore-docs/blob/main/docs/admin-guide/installation_manually.md

Manually create and activate a Python virtual environment for the 'semaphore' user. This isolates project dependencies. After activation, verify the Python interpreter path.

```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
```

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

### Enable Apache Modules

Source: https://github.com/semaphoreui/semaphore-docs/blob/main/docs/admin-guide/reverse-proxy/apache.md

Enable the proxy, proxy_http, and proxy_wstunnel modules required for reverse proxying and WebSocket tunneling.

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

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

### Install Python Requirements with Ansible (Virtualenv)

Source: https://github.com/semaphoreui/semaphore-docs/blob/main/docs/admin-guide/installation_manually.md

Use Ansible to create a Python virtual environment and install the specified requirements into it. This is a convenient way to manage dependencies for Semaphore.

```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
```

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

### Compliance Check Playbook Example

Source: https://github.com/semaphoreui/semaphore-docs/blob/main/docs/user-guide/schedules.md

An example Ansible playbook to run compliance checks using a script and collect reports. This playbook can be scheduled to ensure systems meet security requirements.

```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
```

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

### Show CLI help for TOTP management

Source: https://github.com/semaphoreui/semaphore-docs/blob/main/docs/admin-guide/cli/users.md

Displays available commands for managing user TOTP (2FA) verification.

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

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

### Systemd Service for User-Context Python Modules

Source: https://github.com/semaphoreui/semaphore-docs/blob/main/docs/admin-guide/installation_manually.md

Configure the systemd service to run Semaphore UI with Python modules installed in the user context. This includes pre-start commands for installing Ansible collections, roles, and Python requirements.

```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
```

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

### Expiring an API Token

Source: https://github.com/semaphoreui/semaphore-docs/blob/main/docs/admin-guide/api.md

This example demonstrates how to revoke (expire) an API token.

```APIDOC
## Expiring an API Token

### Description
Revokes an API token, making it invalid for future authentication.

### Method
DELETE

### Endpoint
`/api/user/tokens/{token_id}`

### Parameters
#### Path Parameters
- **token_id** (string) - Required - The ID of the API token to expire.

#### Headers
- **Authorization**: `Bearer YOUR_ACCESS_TOKEN` - Your API token.
```

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

### Configure Semaphore Server via Environment Variables

Source: https://github.com/semaphoreui/semaphore-docs/blob/main/docs/admin-guide/runners.md

Enable remote runners and set a registration token using environment variables.

```bash
SEMAPHORE_USE_REMOTE_RUNNER=True
SEMAPHORE_RUNNER_REGISTRATION_TOKEN=long_string_of_random_characters
```

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

### Check Semaphore Service Status

Source: https://github.com/semaphoreui/semaphore-docs/blob/main/docs/admin-guide/installation/snap.md

Verify that the Semaphore service is running correctly after installation or restart.

```bash
sudo snap services semaphore
```

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

### Enable Activity and Task Logging via Environment Variables

Source: https://github.com/semaphoreui/semaphore-docs/blob/main/docs/admin-guide/logs.md

Alternatively, enable activity and task logging to files using these environment variables.

```bash
export SEMAPHORE_EVENT_LOG_ENABLED=True
export SEMAPHORE_EVENT_LOG_LOGGER={"filename": "./events.log"}

export SEMAPHORE_TASK_LOG_ENABLED=True
export SEMAPHORE_EVENT_LOG_LOGGER={"filename": "./tasks.log"}
```

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

### Import All Backups from Directory

Source: https://github.com/semaphoreui/semaphore-docs/blob/main/docs/admin-guide/cli/projects.md

Restores one or more projects by importing all valid backup files found within a specified directory.

```bash
semaphore project import --dir /path/to/backups
```

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

### Import Single Backup File

Source: https://github.com/semaphoreui/semaphore-docs/blob/main/docs/admin-guide/cli/projects.md

Restores a project from a single backup file.

```bash
semaphore project import --file project-3.backup
```

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

### Download Windows Binary

Source: https://github.com/semaphoreui/semaphore-docs/blob/main/docs/admin-guide/upgrading.md

Download and extract the .zip archive for Windows systems.

```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 ./ 
```

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

### Generate API Token

Source: https://github.com/semaphoreui/semaphore-docs/blob/main/docs/admin-guide/api.md

This example demonstrates how to generate a new API token using the obtained session cookie.

```APIDOC
## Generate API Token

### Description
Generates a new API token that can be used for authenticating API requests.

### Method
POST

### Endpoint
`/api/user/tokens`

### Parameters
#### Headers
- **Cookie**: The session cookie obtained from the login request.

### Response
#### Success Response (200)
- **id** (string) - The generated API token.
- **created** (string) - The timestamp when the token was created.
- **expired** (boolean) - Indicates if the token has expired.
- **user_id** (integer) - The ID of the user associated with the token.

### Response Example
```json
{
    "id": "YOUR_ACCESS_TOKEN",
    "created": "2025-05-21T02:35:12Z",
    "expired": false,
    "user_id": 3
}
```
```

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

### Ansible Playbook Targeting a Dynamic Group

Source: https://github.com/semaphoreui/semaphore-docs/blob/main/docs/user-guide/inventory/consul-dynamic-inventory.md

Example Ansible playbook demonstrating how to target hosts within a dynamically created group, such as 'role_webserver'.

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