### Setup and Run Semaphore Server

Source: https://docs.semaphoreui.com/print

Commands to set up and run the Semaphore server. The setup command initializes the necessary configurations, and the server command starts the Semaphore application with a specified configuration file.

```bash
semaphore setup

semaphore server --config=./config.json

```

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

### Initial Semaphore Setup

Source: https://docs.semaphoreui.com/print

Command for initial setup of Semaphore. This is applicable when Semaphore is not installed via Snap.

```bash
semaphore setup

```

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

### Download and Install Semaphore (Linux amd64)

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

This snippet demonstrates downloading the Semaphore binary for Linux amd64 from a tar.gz archive, unpacking it, and running the setup command. It is a prerequisite for running the Semaphore server.

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

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

### Start Semaphore Server and Runner with Configuration

Source: https://docs.semaphoreui.com/print

Commands to start the Semaphore server and runner processes, specifying the path to the configuration file. Ensure the `config.json` is correctly formatted and located.

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

```

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

```

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

### Download and Extract Semaphore (Linux ARM64)

Source: https://docs.semaphoreui.com/print

This snippet demonstrates downloading the Semaphore binary for Linux ARM64 architecture using wget, extracting the archive, and starting the setup.

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

```

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

### Download and Install Semaphore (Linux arm64)

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

This snippet shows how to download the Semaphore binary for Linux arm64 from a tar.gz archive, extract its contents, and execute the setup command. This prepares the system for running Semaphore.

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

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

### Example Deploy Ansible Role

Source: https://docs.semaphoreui.com/print

This provides an example of an Ansible role for a deployment task. It covers downloading the artifact from S3, unpacking it, updating configuration files, and restarting the application service.

```yaml
# 1. Download `app-{{semaphore_vars.task_details.incoming_version}}.tar.gz` from an S3 bucket to destination servers
# 2. Unpack `app-{{semaphore_vars.task_details.incoming_version}}.tar.gz` to destination directory
# 3. Create or update configuration files
# 4. Restart app service

```

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

### Download and Install Semaphore (Windows amd64)

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

This code block details the process of downloading the Semaphore binary for Windows amd64 as a zip archive using PowerShell, extracting the contents, and running the setup command to prepare for Semaphore execution.

```powershell
Invoke-WebRequest `
-Uri ("https://github.com/semaphoreui/semaphore/releases/" +
      "download/v2.15.0/semaphore_2.15.0_windows_amd64.zip") `
-OutFile semaphore.zip

Expand-Archive -Path semaphore.zip  -DestinationPath ./ 

./semaphore setup
```

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

### Semaphore CLI: Specific Migration Application Example

Source: https://docs.semaphoreui.com/print

An example of using the `semaphore migrate` command to apply all database migrations up to a specific version (e.g., 2.15.1). This is useful for controlled upgrades.

```bash
semaphore migrate --apply-to 2.15.1
```

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

### Python Requirements File Example

Source: https://docs.semaphoreui.com/print

An example of a `requirements.txt` file used to list Python packages required for a project. This file is essential for reproducible Python environments, especially when using pip.

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

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

### Manage Semaphore Snap Configurations

Source: https://docs.semaphoreui.com/print

Commands to view, get, and set configurations for Semaphore when installed via Snap. Includes changing the port and restarting the service.

```bash
sudo snap get semaphore

```

```bash
sudo snap set semaphore port=4444

```

```bash
sudo snap restart semaphore

```

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

### Ansible Requirements File Example

Source: https://docs.semaphoreui.com/print

An example of a `requirements.yml` file used to define Ansible collections and roles to be installed. This is crucial for ensuring all necessary Ansible components are available.

```yaml
---

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

roles:
  - src: 'namespace.role'
```

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

### Semaphore CLI: Basic Commands

Source: https://docs.semaphoreui.com/print

Provides essential Semaphore CLI commands for checking the current version, accessing help, and initiating setup. These are foundational commands for interacting with the Semaphore system.

```bash
semaphore version
```

```bash
semaphore help
```

```bash
semaphore setup
```

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

### Run Semaphore Server

Source: https://docs.semaphoreui.com/print

This command starts the Semaphore server, specifying the configuration file to use. Semaphore will then be accessible at https://localhost:3000.

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

```

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

### Example Build Ansible Role

Source: https://docs.semaphoreui.com/print

This outlines a typical Ansible role for a build task. It includes steps for fetching source code, compilation, packaging artifacts with versioning, and uploading to an S3 bucket.

```yaml
# 1. Get app source code from GitHub
# 2. Compile source code
# 3. Pack created binary to a tarball with name `app-{{semaphore_vars.task_details.target_version}}.tar.gz`
# 4. Send `app-{{semaphore_vars.task_details.target_version}}.tar.gz` to an S3 bucket

```

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

### Run Semaphore Server

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

This command initiates the Semaphore server process, specifying the configuration file to be used. It assumes that Semaphore has already been installed and the necessary configuration is in place.

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

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

### Example LDAP Configuration for Semaphore UI

Source: https://docs.semaphoreui.com/print

This JSON object presents a sample LDAP configuration for Semaphore UI, intended for use with a self-hosted LDAP server (like the one started with Docker). It details server, bind, search, and mapping parameters tailored for this environment.

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

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

### Start and Unregister Semaphore Runner

Source: https://docs.semaphoreui.com/print

Commands to start and unregister a Semaphore runner using its configuration file. Starting the runner allows it to execute tasks, while unregistering removes its connection from the server.

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

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

### Download and Extract Semaphore (Linux AMD64)

Source: https://docs.semaphoreui.com/print

This snippet shows how to download the Semaphore binary for Linux AMD64 architecture using wget, extract the archive, and initiate the setup process.

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

```

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

### Manage Semaphore systemd Service

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

These commands are used to manage the Semaphore service on systems using systemd. They include reloading the systemd daemon, starting the Semaphore service, checking its status, and enabling it to start automatically on boot.

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

sudo systemctl status semaphore

sudo systemctl enable semaphore
```

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

### Initialize Semaphore UI Setup

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

Initiates the setup process for the Semaphore UI, typically used for first-time configurations. It may guide the user through necessary initial settings.

```bash
semaphore setup
```

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

### Generate Semaphore Configuration Interactively

Source: https://docs.semaphoreui.com/print

Use these commands to interactively generate the `config.json` file for the Semaphore server or runner. This is the primary method for initial setup.

```bash
semaphore setup

```

```bash
semaphore runner setup

```

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

### Run Semaphore Server

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

Starts the Semaphore UI server. Requires a configuration file (e.g., config.json) to be present in the current directory or specified path.

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

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

### Configure and Register Semaphore Runner

Source: https://docs.semaphoreui.com/print

Commands to set up and register a Semaphore runner. The setup command generates a configuration file, which is then used for registration, optionally via stdin for the registration token. This process is essential for connecting a runner to the Semaphore server.

```bash
semaphore runner setup --config /path/to/your/config/file.json
semaphore runner register --config /path/to/your/config/file.json
echo REGISTRATION_TOKEN | semaphore runner register --stdin-registration-token --config /path/to/your/config/file.json
```

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

### Semaphore config.json Structure

Source: https://docs.semaphoreui.com/print

This is an example of the `config.json` file used by Semaphore. It includes settings for database connections, Git clients, authentication, runners, logging, and process sandboxing.

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

```

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

### Manage Semaphore Snap Service and Configuration

Source: https://docs.semaphoreui.com/print

These commands interact with the Semaphore snap installation. `snap services semaphore` checks the service status, while `snap get semaphore` displays current configuration options.

```bash
sudo snap services semaphore

sudo snap get semaphore

```

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

### Download and Extract Semaphore (Windows AMD64)

Source: https://docs.semaphoreui.com/print

This snippet illustrates downloading the Semaphore binary for Windows AMD64 using PowerShell's Invoke-WebRequest, extracting the zip archive, and running the setup.

```powershell
Invoke-WebRequest `
-Uri ("https://github.com/semaphoreui/semaphore/releases/" +
      "download/v2.15.0/semaphore_2.15.0_windows_amd64.zip") `
-OutFile semaphore.zip

Expand-Archive -Path semaphore.zip  -DestinationPath ./

./semaphore setup

```

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

### Manage Semaphore Systemd Service

Source: https://docs.semaphoreui.com/print

These commands are used to manage the Semaphore systemd service. `daemon-reload` updates systemd configurations, `start` initiates the service, `status` checks its running state, and `enable` ensures it starts on boot.

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

sudo systemctl status semaphore

sudo systemctl enable semaphore

```

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

### Semaphore CLI: Server and Runner Control

Source: https://docs.semaphoreui.com/print

Commands to start the main Semaphore server and its associated runner processes. These are critical for the operational status of the Semaphore environment.

```bash
semaphore server
```

```bash
semaphore runner
```

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

### Claim Expression Example (Text)

Source: https://docs.semaphoreui.com/print

This example shows a claim expression format used for configuring `username_claim` and `email_claim` in OIDC providers. It demonstrates how to map fields from the identity provider or use a fallback expression.

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

```

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

### Install Semaphore via Snap

Source: https://docs.semaphoreui.com/print

This command installs Semaphore using the Snap package manager. After installation, Semaphore will be available at https://localhost:3000.

```bash
sudo snap install semaphore

```

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

### Create systemd Service File for Semaphore

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

This snippet demonstrates how to create a systemd service file for Semaphore. It configures the service to run as a simple process, reload on HUP signals, start with a specified server command and config file, log using syslog, and restart automatically. Replace placeholders for paths.

```shell
sudo cat > /etc/systemd/system/semaphore.service <<EOF
[Unit]
Description=Semaphore Ansible
Documentation=https://github.com/semaphoreui/semaphore
Wants=network-online.target
After=network-online.target

[Service]
Type=simple
ExecReload=/bin/kill -HUP $MAINPID
ExecStart=/path/to/semaphore server --config=/path/to/config.json
SyslogIdentifier=semaphore
Restart=always
RestartSec=10s

[Install]
WantedBy=multi-user.target
EOF
```

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

### Semaphore CLI: Specific Migration Rollback Example

Source: https://docs.semaphoreui.com/print

An example of using the `semaphore migrate` command to undo database migrations and roll back the schema to a previous version (e.g., 2.13). This is useful for downgrades or error recovery.

```bash
semaphore migrate --undo-to 2.13
```

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

### Example Semaphore Runner Configuration File

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

An example of the configuration file generated after running `semaphore runner setup`. It includes paths for temporary files, the web host address, and runner-specific settings like the authentication token.

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

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

### Install Semaphore UI (Binary Tarball) on Linux

Source: https://docs.semaphoreui.com/print

Downloads and unpacks the Semaphore UI binary from a tarball for Linux systems. It requires `wget` and `tar` commands. The unpacked binary should replace the old Semaphore binary.

```shell
wget https://github.com/semaphoreui/semaphore/releases/download/v2.15.0/semaphore_2.15.0_linux_amd64.tar.gz
tar xf semaphore_2.15.0_linux_amd64.tar.gz
```

```shell
wget https://github.com/semaphoreui/semaphore/releases/download/v2.15.0/semaphore_2.15.0_linux_arm64.tar.gz
tar xf semaphore_2.15.0_linux_arm64.tar.gz
```

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

### Configure Gotify Alerts in Semaphore UI

Source: https://docs.semaphoreui.com/print

Example JSON configuration for enabling and setting up Gotify alerts in Semaphore UI. This includes the boolean flag to enable alerts and fields for the Gotify server URL and authentication token.

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

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

### Install Semaphore UI (.deb) on Debian/Ubuntu

Source: https://docs.semaphoreui.com/print

Downloads and installs the Semaphore UI package file for Debian and Ubuntu systems. It requires the `wget` and `dpkg` commands. The output is the installed Semaphore UI application.

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

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

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

### Install Semaphore UI (.rpm) on CentOS/RedHat

Source: https://docs.semaphoreui.com/print

Downloads and installs the Semaphore UI package file for CentOS and RedHat systems. It requires the `wget` and `yum` commands. The output is the installed Semaphore UI application.

```shell
wget https://github.com/semaphoreui/semaphore/releases/download/v2.15.0/semaphore_2.15.0_linux_amd64.rpm
sudo yum install semaphore_2.15.0_linux_amd64.rpm
```

```shell
wget https://github.com/semaphoreui/semaphore/releases/download/v2.15.0/semaphore_2.15.0_linux_arm64.rpm
sudo yum install semaphore_2.15.0_linux_arm64.rpm
```

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

### GitHub OIDC Provider Configuration (JSON)

Source: https://docs.semaphoreui.com/print

This example demonstrates the JSON configuration for integrating GitHub as an OIDC provider in Semaphore UI. It includes essential parameters like client ID, secret, redirect URL, and endpoint details for authentication.

```json
{
  "oidc_providers": {
		"github": {
			"icon": "github",
			"display_name": "Sign in with GitHub",
			"client_id": "***",
			"client_secret": "***",
			"redirect_url": "https://your-domain.com/api/auth/oidc/github/redirect",
			"endpoint": {
				"auth": "https://github.com/login/oauth/authorize",
				"token": "https://github.com/login/oauth/access_token",
				"userinfo": "https://api.github.com/user"
			},
			"scopes": ["read:user", "user:email"],
			"username_claim": "|",
			"email_claim": "email | {{ .id }}@github.your-domain.com",
			"name_claim": "name",
			"order": 1
		}
  }
}

```

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

### Task Execution API

Source: https://docs.semaphoreui.com/print

Initiate the execution of tasks, such as building or deploying artifacts, using an API token for authentication.

```APIDOC
## POST /api/project/:project_id/tasks

### Description
Launches a 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.

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

### Request Example
```json
{
  "template_id": 1
}
```

### Headers
- **Authorization**: Bearer YOUR_ACCESS_TOKEN
- **Content-Type**: application/json
- **Accept**: application/json
```

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

### Semaphore CLI: Database Migrations

Source: https://docs.semaphoreui.com/print

Provides commands for managing Semaphore's database schema. This includes viewing available migration commands, applying all migrations, migrating to a specific version, and undoing migrations.

```bash
semaphore migrations --help
```

```bash
semaphore migrate
```

```bash
semaphore migrate --apply-to <version>
```

```bash
semaphore migrate --undo-to <version>
```

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

### Install Kerberos Packages on Semaphore Host

Source: https://docs.semaphoreui.com/print

Installs necessary Kerberos development libraries and the Kerberos user package on the Semaphore host. It also configures the default Kerberos realm in `/etc/krb5.conf` to match the Active Directory domain.

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

```

```ini
[libdefaults]
  default_realm = YOUR.DOMAIN.NAME

```

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

### Configure DingTalk Alerts

Source: https://docs.semaphoreui.com/print

This JSON configuration example shows how to enable DingTalk notifications in Semaphore UI. Set `dingtalk_alert` to true and provide the webhook URL in the `dingtalk_url` field.

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

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

### Configure Remote Runner (Environment Variables)

Source: https://docs.semaphoreui.com/print

This example demonstrates how to configure remote runners for Semaphore using environment variables. This method is an alternative to using a JSON configuration file and sets the necessary parameters for runner registration.

```shell
SEMAPHORE_USE_REMOTE_RUNNER=True
SEMAPHORE_RUNNER_REGISTRATION_TOKEN=long_string_of_random_characters

```

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

### Ansible `semaphore_vars` for Build Tasks

Source: https://docs.semaphoreui.com/print

This example illustrates the structure of `semaphore_vars` provided to Ansible playbooks when a build task is executed. It includes details like the task type, username, message, and the target version for the artifact.

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

```

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

### Ansible `semaphore_vars` for Deploy Tasks

Source: https://docs.semaphoreui.com/print

This example shows the `semaphore_vars` available for Ansible playbooks during a deploy task. It contains information such as the task type, username, message, and the incoming version of the artifact to be deployed.

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

```

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

### Ansible Dependency Upgrade with Virtual Environment Activation (Systemd)

Source: https://docs.semaphoreui.com/print

Sets up the systemd service to activate a Python virtual environment and then upgrade Ansible collections and roles from a requirements file before starting the Semaphore UI. This ensures Ansible dependencies are managed within the virtual environment context.

```systemd
# to auto-upgrade ansible collections and roles at service startup
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'
```

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

### Configure Rocket.Chat Alerts

Source: https://docs.semaphoreui.com/print

This JSON configuration example enables Rocket.Chat notifications within Semaphore UI. You need to set `rocketchat_alert` to true and provide the webhook URL in the `rocketchat_url` field.

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

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

### Install Semaphore .rpm Package (Linux ARM64)

Source: https://docs.semaphoreui.com/print

Installs the Semaphore .rpm package for CentOS and RedHat systems on Linux ARM64 architecture. This involves downloading the package using wget and then installing it using yum.

```bash
wget https://github.com/semaphoreui/semaphore/releases/\ndownload/v2.15.0/semaphore_2.15.0_linux_arm64.rpm

sudo yum install semaphore_2.15.0_linux_arm64.rpm

```

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

### Add Admin User to Semaphore (Snap Install)

Source: https://docs.semaphoreui.com/print

This sequence of commands stops the Semaphore snap service, adds an administrator user with specified credentials, and then restarts the service. This is necessary for initial login after a snap installation.

```bash
sudo snap stop semaphore

sudo semaphore user add --admin \
--login john \
--name=John \
--email=john1996@gmail.com \
--password=12345

sudo snap start semaphore

```

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

### Upgrade Semaphore via Snap

Source: https://docs.semaphoreui.com/print

Command to upgrade Semaphore to the latest stable version when installed using Snap. This ensures you have the most recent features and security patches.

```bash
sudo snap refresh semaphore

```

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

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

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

Downloads and installs the Semaphore UI package for Debian and Ubuntu systems with amd64 architecture. Requires superuser privileges for installation.

```bash
wget https://github.com/semaphoreui/semaphore/releases/\ndownload/v2.15.0/semaphore_2.15.0_linux_amd64.deb

sudo dpkg -i semaphore_2.15.0_linux_amd64.deb
```

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

### Configure Microsoft Teams Alerts

Source: https://docs.semaphoreui.com/print

This is a JSON configuration example for enabling Microsoft Teams notifications in Semaphore UI. It requires setting `microsoft_teams_alert` to true and providing the corresponding webhook URL in `microsoft_teams_url`.

```json
{
    "microsoft_teams_alert": true,
    "microsoft_teams_url":   "...",
}
```

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

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

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

Downloads and installs the Semaphore UI package for Debian and Ubuntu systems with arm64 architecture. Requires superuser privileges for installation.

```bash
wget https://github.com/semaphoreui/semaphore/releases/\ndownload/v2.15.0/semaphore_2.15.0_linux_arm64.deb

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

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

### Install Semaphore .deb Package (Linux AMD64)

Source: https://docs.semaphoreui.com/print

Installs the Semaphore .deb package for Debian and Ubuntu systems on Linux AMD64 architecture. This involves downloading the package using wget and then installing it using dpkg.

```bash
wget https://github.com/semaphoreui/semaphore/releases/\ndownload/v2.15.0/semaphore_2.15.0_linux_amd64.deb

sudo dpkg -i semaphore_2.15.0_linux_amd64.deb

```

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

### Install Semaphore .deb Package (Linux ARM64)

Source: https://docs.semaphoreui.com/print

Installs the Semaphore .deb package for Debian and Ubuntu systems on Linux ARM64 architecture. This involves downloading the package using wget and then installing it using dpkg.

```bash
wget https://github.com/semaphoreui/semaphore/releases/\ndownload/v2.15.0/semaphore_2.15.0_linux_arm64.deb

sudo dpkg -i semaphore_2.15.0_linux_arm64.deb

```

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

### Install Semaphore .rpm Package (Linux AMD64)

Source: https://docs.semaphoreui.com/print

Installs the Semaphore .rpm package for CentOS and RedHat systems on Linux AMD64 architecture. This involves downloading the package using wget and then installing it using yum.

```bash
wget https://github.com/semaphoreui/semaphore/releases/\ndownload/v2.15.0/semaphore_2.15.0_linux_amd64.rpm

sudo yum install semaphore_2.15.0_linux_amd64.rpm

```

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

### Running a Single Command as a Service User

Source: https://docs.semaphoreui.com/print

Shows how to execute a single command within the context of a specific service user (e.g., 'semaphore'). This allows you to run commands with the user's privileges without fully switching the shell.

```bash
sudo --login -u semaphore <command>
```

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

### Create Systemd Service File for Semaphore

Source: https://docs.semaphoreui.com/print

This snippet shows how to create a systemd service file for Semaphore. It requires replacing placeholder paths for the Semaphore executable and configuration file. This enables Semaphore to run as a background service.

```bash
sudo cat > /etc/systemd/system/semaphore.service <<EOF
[Unit]
Description=Semaphore Ansible
Documentation=https://github.com/semaphoreui/semaphore
Wants=network-online.target
After=network-online.target

[Service]
Type=simple
ExecReload=/bin/kill -HUP $MAINPID
ExecStart=/path/to/semaphore server --config=/path/to/config.json
SyslogIdentifier=semaphore
Restart=always
RestartSec=10s

[Install]
WantedBy=multi-user.target
EOF

```

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

### Install Semaphore on CentOS/RedHat (arm64)

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

Downloads and installs the Semaphore UI package for CentOS and RedHat systems with arm64 architecture using yum package manager. Requires superuser privileges for installation.

```bash
wget https://github.com/semaphoreui/semaphore/releases/\ndownload/v2.15.0/semaphore_2.15.0_linux_arm64.rpm

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

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

### Configure Global Notification Provider

Source: https://docs.semaphoreui.com/print

Sets up a global notification provider in Semaphore's config.json. This enables sending notifications about task and project activity to supported channels like Email, Slack, Telegram, etc.

```json
{
  "notifications": {
    "email": {
      "enabled": true,
      "host": "smtp.example.com",
      "port": 587,
      "username": "user@example.com",
      "password": "password"
    }
  }
}
```

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

### Semaphore CLI: Two-Factor Authentication (2FA)

Source: https://docs.semaphoreui.com/print

Illustrates commands for managing Time-based One-Time Password (TOTP) authentication for users. This includes enabling TOTP and generating recovery codes, enhancing security.

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

```bash
# Enable TOTP for a user
semaphore user totp enable --login john
```

```bash
# Generate recovery codes (if allowed by config)
semaphore user totp recovery --login john
```

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

### Configure Activity Log Settings

Source: https://docs.semaphoreui.com/print

Enables and configures activity logging to a file. Supports raw or JSON format and specific logger options. Environment variables can be used to set these parameters.

```env
SEMAPHORE_EVENT_LOG_ENABLED=true
SEMAPHORE_EVENT_LOG_FORMAT=json
SEMAPHORE_EVENT_LOG_LOGGER={"option": "value"}
```

```json
{
  "logging": {
    "activity": {
      "enabled": true,
      "format": "json",
      "logger": {
        "option": "value"
      }
    }
  }
}
```

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

### Semaphore CLI: User Management

Source: https://docs.semaphoreui.com/print

Demonstrates how to add a new administrative user with specified details and change an existing user's password via the CLI. These commands are vital for access control and user administration.

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

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

```bash
semaphore user change-by-login \
    --login myAdmin \
    --password "New$Password"
```

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

### Ansible Playbook for Windows Host Verification

Source: https://docs.semaphoreui.com/print

A simple Ansible playbook to verify basic connectivity to Windows hosts using WinRM and Kerberos. It utilizes the `win_ping` module to confirm successful communication.

```ansible
- hosts: all
  gather_facts: false

  tasks:
    - win_ping:


```

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

### Launch a Task with API Token (HTTP Request)

Source: https://docs.semaphoreui.com/print

This snippet shows how to launch a task using an API token. The token must be included in the `Authorization` header as a Bearer token. This is a common method for automating task execution via the API.

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

```

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

### User Tokens API

Source: https://docs.semaphoreui.com/print

Manage user API tokens. This includes generating new tokens and revoking existing ones.

```APIDOC
## POST /api/user/tokens

### Description
Generates a new API token for the authenticated user.

### Method
POST

### Endpoint
/api/user/tokens

### Parameters
#### Request Body
None

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

### Response
#### Success Response (200)
- **id** (string) - The newly 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
}
```

## DELETE /api/user/tokens/:token

### Description
Revokes (expires) a specific API token, making it invalid for future requests.

### Method
DELETE

### Endpoint
/api/user/tokens/:token

### Parameters
#### Path Parameters
- **token** (string) - Required - The API token to revoke.
```

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

### Install Semaphore on CentOS/RedHat (amd64)

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

Downloads and installs the Semaphore UI package for CentOS and RedHat systems with amd64 architecture using yum package manager. Requires superuser privileges for installation.

```bash
wget https://github.com/semaphoreui/semaphore/releases/\ndownload/v2.15.0/semaphore_2.15.0_linux_amd64.rpm

sudo yum install semaphore_2.15.0_linux_amd64.rpm
```

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

### Ansible Playbook for System Updates

Source: https://docs.semaphoreui.com/print

This Ansible playbook automates system updates by refreshing the apt cache, upgrading all packages, and removing unused dependencies. It is designed to be run on all hosts specified in the inventory. Ensure the 'apt' module is available and the target systems use APT package management.

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

```

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

### Configure Task Log Settings

Source: https://docs.semaphoreui.com/print

Enables and configures task execution logging to a file. Supports raw or JSON format and specific logger options. Environment variables can be used to set these parameters.

```env
SEMAPHORE_TASK_LOG_ENABLED=true
SEMAPHORE_TASK_LOG_FORMAT=raw
SEMAPHORE_TASK_LOG_LOGGER={"option": "value"}
```

```json
{
  "logging": {
    "tasks": {
      "enabled": true,
      "format": "raw",
      "logger": {
        "option": "value"
      }
    }
  }
}
```

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

### Gitea OIDC Provider Configuration (JSON)

Source: https://docs.semaphoreui.com/print

This JSON configuration details setting up a Gitea instance as an OIDC provider for Semaphore UI. It includes specific endpoint URLs for Gitea's OAuth2 implementation and claim mappings.

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

```

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

### User Authentication API

Source: https://docs.semaphoreui.com/print

Authenticate with Semaphore to obtain a session token for subsequent requests. Ensure passwords with special characters are properly escaped.

```APIDOC
## POST /api/auth/login

### Description
Authenticates a user with provided credentials and generates a session token.

### Method
POST

### Endpoint
/api/auth/login

### Parameters
#### Request Body
- **auth** (string) - Required - The username for authentication.
- **password** (string) - Required - The user's password. Special characters should be escaped (e.g., `slashy\\pass`).

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

### Response
#### Success Response (200)
- **session_token** (string) - The session token obtained after successful authentication.
```

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

### Install Semaphore via Snap

Source: https://docs.semaphoreui.com/administration-guide/installation/snap

Installs the Semaphore application using the snap package manager. After installation, Semaphore will be accessible at https://localhost:3000.

```bash
sudo snap install semaphore
```

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

### Install Semaphore using Debian/Ubuntu Package (.deb)

Source: https://docs.semaphoreui.com/administration-guide/upgrading

Downloads and installs the Semaphore package for Debian-based systems (like Ubuntu). It first downloads the appropriate .deb file and then uses dpkg to install it. Ensure you have wget and dpkg installed.

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

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

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

### Configure Environment Variables for Application Processes

Source: https://docs.semaphoreui.com/print

Demonstrates how to set static environment variables (`env_vars`) and forward specific environment variables (`forwarded_env_vars`) to application processes using both `config.json` and direct environment variables.

```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"
  ]
}

```

```bash
export SEMAPHORE_ENV_VARS='{"HTTP_PROXY":"http://proxy.internal:3128","ANSIBLE_STDOUT_CALLBACK":"yaml"}'
export SEMAPHORE_FORWARDED_ENV_VARS='["AWS_ACCESS_KEY_ID","AWS_SECRET_ACCESS_KEY","GOOGLE_APPLICATION_CREDENTIALS"]'

```

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

### Setup Semaphore Runner

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

Command to set up a Semaphore runner, which creates a configuration file for the runner. Ensure the server is configured to accept remote runners before executing this.

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

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

### Get Semaphore Configuration

Source: https://docs.semaphoreui.com/administration-guide/installation/snap

Retrieves the current configuration settings for Semaphore installed via snap. Available options can be found in the Configuration options reference.

```bash
sudo snap get semaphore
```

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

### Docker Compose Volume for Python Requirements

Source: https://docs.semaphoreui.com/print

This snippet demonstrates how to mount a requirements.txt file into a Docker container for installing additional Python packages required by Ansible modules or roles. It ensures that necessary Python dependencies are available within the Semaphore container environment.

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

```

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

### Configure File Logging for Semaphore Events and Tasks

Source: https://docs.semaphoreui.com/print

JSON configuration to enable and specify filenames for writing Semaphore event and task logs to files. This is an alternative to default stdout logging.

```json
{
  "log": {
    "events": {
      "enabled": true,
      "logger": {
        "filename": "../events.log"
        // other logger options
      }
    },
    "tasks": {
      "enabled": true,
      "logger": {
        "filename": "../tasks.log"
        // other logger options
      },
			"result_logger": {
				"filename": "../task_results.log"
        // other logger options
			}
    }
  }
}
```

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

### Activating Semaphore Virtual Environment

Source: https://docs.semaphoreui.com/print

A command to activate the Python virtual environment located at `/home/semaphore/venv/bin/activate`. After activation, subsequent Python commands will use the interpreter and packages within this virtual environment.

```bash
source /home/semaphore/venv/bin/activate
```

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

### Generate Access Key for Data Encryption

Source: https://docs.semaphoreui.com/print

Generates a 32-byte random key suitable for Access Keys encryption in Semaphore. This key should be base64 encoded and configured in the `access_key_encryption` setting.

```bash
head -c32 /dev/urandom | base64
```

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

### Create Python Virtual Environment with Ansible

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

Creates and manages a Python virtual environment for Semaphore using the Ansible 'pip' module. It installs the specified requirements into the virtual environment, ensuring a clean and isolated Python setup.

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

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

### Google OIDC Provider Configuration (JSON)

Source: https://docs.semaphoreui.com/print

This JSON configuration illustrates how to set up Google as an OIDC provider for Semaphore UI. It specifies parameters such as color, icon, display name, client ID, secret, and redirect URL.

```json
{
  "oidc_providers": {
		"google": {
			"color": "blue",
			"icon": "google",
			"display_name": "Sign in with Google",
			"provider_url": "https://accounts.google.com",
			"client_id": "***.apps.googleusercontent.com",
			"client_secret": "GOCSPX-***",
			"redirect_url": "https://your-domain.com/api/auth/oidc/google/redirect",
			"username_claim": "|",
			"name_claim": "name",
			"order": 2
		}
  }
}

```

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

### Systemd Service: MariaDB Dependency

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

Defines a dependency on the MariaDB service for the Semaphore UI. This ensures that MariaDB is running before the Semaphore UI service attempts to start.

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

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

### Verifying Python 3 Path within Virtual Environment

Source: https://docs.semaphoreui.com/print

After activating a virtual environment, this command verifies that the `which python3` command now points to the Python interpreter within the activated virtual environment, confirming the environment is correctly set up.

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

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

### Configure Apache Virtual Host for Semaphore

Source: https://docs.semaphoreui.com/print

Sets up an SSL-enabled virtual host to proxy HTTP and WebSocket traffic to a Semaphore server running on localhost:3000. This configuration is essential for secure and proper communication with the Semaphore application.

```apache
<VirtualHost *:443>

    ServerName example.com

    ServerAdmin webmaster@localhost
	
    SSLEngine on
    SSLCertificateFile /path/to/example.com.crt
    SSLCertificateKeyFile /path/to/example.com.key

    ProxyPreserveHost On

    <Location />
        ProxyPass http://127.0.0.1:3000/
        ProxyPassReverse http://127.0.0.1:3000/
    </Location>

    <Location /api/ws>
        RewriteCond %{HTTP:Connection} Upgrade [NC]
        RewriteCond %{HTTP:Upgrade} websocket [NC]

        ProxyPass ws://127.0.0.1:3000/api/ws/
        ProxyPassReverse ws://127.0.0.1:3000/api/ws/

    </Location>
</VirtualHost>
```

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

### Start Semaphore Runner

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

Command to start the Semaphore runner service using its configuration file. Once started, the runner is ready to accept and execute tasks assigned by the Semaphore server.

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

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

### Semaphore API Authorization Header

Source: https://docs.semaphoreui.com/print

This snippet shows the required format for the Authorization header when making requests to the Semaphore API. It demonstrates how to include an API token using the Bearer authentication scheme.

```text
Authorization: Bearer YOUR_API_TOKEN
```

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

### Configure Semaphore UI with Docker Compose

Source: https://docs.semaphoreui.com/print

This `docker-compose.yml` file sets up Semaphore UI with a MySQL database. It includes configurations for environment variables, database connection details, and optional LDAP settings. Note that sensitive variables like passwords and encryption keys need to be explicitly set.

```yaml
services:
  # uncomment this section and comment out the mysql section to use postgres instead of mysql
  #postgres:
    #restart: unless-stopped
    #image: postgres:14
    #hostname: postgres
    #volumes:
    #  - semaphore-postgres:/var/lib/postgresql/data
    #environment:
    #  POSTGRES_USER: semaphore
    #  POSTGRES_PASSWORD: semaphore
    #  POSTGRES_DB: semaphore
  # if you wish to use postgres, comment the mysql service section below
  mysql:
    restart: unless-stopped
    image: mysql:8.0
    hostname: mysql
    volumes:
      - semaphore-mysql:/var/lib/mysql
    environment:
      MYSQL_RANDOM_ROOT_PASSWORD: 'yes'
      MYSQL_DATABASE: semaphore
      MYSQL_USER: semaphore
      MYSQL_PASSWORD: semaphore
  semaphore:
    restart: unless-stopped
    ports:
      - 3000:3000
    image: semaphoreui/semaphore:latest
    environment:
      SEMAPHORE_DB_USER: semaphore
      SEMAPHORE_DB_PASS: semaphore
      SEMAPHORE_DB_HOST: mysql # for postgres, change to: postgres
      SEMAPHORE_DB_PORT: 3306 # change to 5432 for postgres
      SEMAPHORE_DB_DIALECT: mysql # for postgres, change to: postgres
      SEMAPHORE_DB: semaphore
      # To use SQLite instead of MySQL/Postgres (v2.16+)
      # SEMAPHORE_DB_DIALECT: sqlite
      # SEMAPHORE_DB: "/etc/semaphore/semaphore.sqlite"
      SEMAPHORE_PLAYBOOK_PATH: /tmp/semaphore/
      SEMAPHORE_ADMIN_PASSWORD: changeme
      SEMAPHORE_ADMIN_NAME: admin
      SEMAPHORE_ADMIN_EMAIL: admin@localhost
      SEMAPHORE_ADMIN: admin
      SEMAPHORE_ACCESS_KEY_ENCRYPTION: gs72mPntFATGJs9qK0pQ0rKtfidlexiMjYCH9gWKhTU=
      SEMAPHORE_LDAP_ACTIVATED: 'no' # if you wish to use ldap, set to: 'yes'
      SEMAPHORE_LDAP_HOST: dc01.local.example.com
      SEMAPHORE_LDAP_PORT: '636'
      SEMAPHORE_LDAP_NEEDTLS: 'yes'
      SEMAPHORE_LDAP_DN_BIND: 'uid=bind_user,cn=users,cn=accounts,dc=local,dc=example,dc=com'
      SEMAPHORE_LDAP_PASSWORD: 'ldap_bind_account_password'
      SEMAPHORE_LDAP_DN_SEARCH: 'dc=local,dc=example,dc=com'
      SEMAPHORE_LDAP_SEARCH_FILTER: "(& (uid=%s)(memberOf=cn=ipausers,cn=groups,cn=accounts,dc=local,dc=example,dc=com))"
      TZ: UTC
    depends_on:
      - mysql # for postgres, change to: postgres
volumes:
  semaphore-mysql: # to use postgres, switch to: semaphore-postgres

```

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

### Netbox Dynamic Inventory Plugin Configuration

Source: https://docs.semaphoreui.com/print

Configuration for the `netbox.netbox.nb_inventory` Ansible plugin to create a dynamic inventory in Semaphore. It requires the Netbox API endpoint, an API token for authentication, and can optionally disable certificate validation.

```yaml
plugin: netbox.netbox.nb_inventory
api_endpoint: http://your_netbox_url_here
token: YOUR_NETBOX_API_TOKEN
validate_certs: False
config_context: False


```