### Semaphore Setup Command

Source: https://github.com/semaphoreui/semaphore/wiki/Installation

Initiates the setup process for Semaphore after installation. This command guides the user through configuring database credentials and playbook paths.

```bash
semaphore -setup
```

```bash
semaphore setup
```

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

### Run Semaphore Setup and Configuration

Source: https://github.com/semaphoreui/semaphore/wiki/Install-Semaphore-on-Debian-like-Linux-with-MySQL-8

Initiates the Semaphore setup process, guiding the user through database configuration, playbook path setup, migrations, and initial user creation. It shows an example of the generated configuration and prompts for confirmation.

```bash
$ sudo semaphore -setup

 Hello! You will now be guided through a setup to:

 1. Set up configuration for a MySQL/MariaDB database
 2. Set up a path for your playbooks (auto-created)
 3. Run database Migrations
 4. Set up initial semaphore user & password

 > DB Hostname (default 127.0.0.1:3306): 127.0.0.1:3306
 > DB User (default root): semaphore
 > DB Password: yourdbpasswd
 > DB Name (default semaphore): semaphore
 > Playbook path (default /tmp/semaphore): /opt/semaphore
 > **Web root URL (optional, example http://localhost:8010/):**
 > WARN[0065] An input error occured:unexpected newline
 > Enable email alerts (y/n, default n): n
 > Enable telegram alerts (y/n, default n): n
 > Enable LDAP authentication (y/n, default n): n

 Generated configuration:
 {
        "mysql": {
                "host": "127.0.0.1:3306",
                "user": "semaphore",
                "pass": "yourdbpasswd",
                "name": "semaphore"
        },
        "port": "",
        "interface": "",
        "tmp_path": "/opt/semaphore",
        "cookie_hash": "64AS4uNWiT7X5n7wSo5vqGYL/D0UEUgjjX36bF9LPOg=",
        "cookie_encryption": "JhKbJF79d0okR5Lky6SFYpIdaGP7KnRuKfOvK9rCa+M=",
        "email_sender": "",
        "email_host": "",
        "email_port": "",
        "web_host": "",
        "ldap_binddn": "",
        "ldap_bindpassword": "",
        "ldap_server": "",
        "ldap_searchdn": "",
        "ldap_searchfilter": "",
        "ldap_mappings": {
                "dn": "",
                "mail": "",
                "uid": "",
                "cn": ""
        },
        "telegram_chat": "",
        "telegram_token": "",
        "concurrency_mode": "",
        "max_parallel_tasks": 0,
        "email_alert": false,
        "telegram_alert": false,
        "ldap_enable": false,
        "ldap_needtls": false,
        "old_frontend": false
 }

 > Is this correct? (yes/no): yes
 > Config output directory (default /opt/semaphore): /opt/semaphore
 >  Running: mkdir -p /opt/semaphore..
 >  Configuration written to /opt/semaphore/config.json..
 >  Pinging db..

 Running DB Migrations..
Checking DB migrations


 > Username: Admin
 > Email: youremail@something.com

 Welcome back, Semaphore Admin! (a user with this username/email is already set up..)

 Re-launch this program pointing to the configuration file

./semaphore -config /opt/semaphore/config.json

 To run as daemon:

nohup ./semaphore -config /opt/semaphore/config.json &

You can login with youremail@something.com or admin.
```

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

### Nginx Reverse Proxy Configuration Example

Source: https://github.com/semaphoreui/semaphore/wiki/Installation

An example Nginx configuration file for setting up a reverse proxy for Semaphore, enabling HTTPS and secure access. This is a common method for securing web applications.

```nginx
server {
    listen 80;
    server_name semaphore.example.com;

    location / {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}
```

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

### Install Semaphore via Snap

Source: https://github.com/semaphoreui/semaphore/wiki/Installation

Installs the Semaphore application using the snap package manager. This is a straightforward method for installing Semaphore on systems that support snaps.

```bash
sudo snap install semaphore
```

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

### Docker Dependency Installation (MySQL)

Source: https://github.com/semaphoreui/semaphore/wiki/Installation

Launches a MySQL Docker container for use as a dependency for Semaphore. This command sets up a MySQL instance accessible on the host machine.

```bash
docker run -d --name=mysql -p 127.0.0.1:3306:3306 -e MYSQL_ROOT_PASSWORD=my-secret-pw mysql:5.6
```

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

### Manual Installation via Curl

Source: https://github.com/semaphoreui/semaphore/wiki/Installation

Downloads the Semaphore binary for Linux using curl and places it in the system's executable path. This method requires manual download and placement of the binary.

```bash
curl -L <link> > /usr/bin/semaphore
```

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

### Build, Setup, and Run Semaphore

Source: https://github.com/semaphoreui/semaphore/blob/develop/CONTRIBUTING.md

Compiles the Semaphore application, sets up the environment, and starts the server. The server can be configured via a JSON file.

```bash
task build
go run cli/main.go setup
go run cli/main.go service --config ./config.json
```

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

### Start Semaphore UI Server (Image)

Source: https://github.com/semaphoreui/semaphore/blob/develop/deployment/compose/README.md

Starts the Semaphore UI server by downloading a pre-released Docker image from DockerHub and configuring it. This uses integrated bootstrapping scripts.

```console
docker-compose -f deployment/compose/server/base.yml -f deployment/compose/server/image.yml up
```

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

### Project Setup and Dependencies

Source: https://github.com/semaphoreui/semaphore/blob/develop/web/README.md

Installs all necessary project dependencies using npm.

```bash
npm install
```

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

### Install Development Dependencies

Source: https://github.com/semaphoreui/semaphore/blob/develop/CONTRIBUTING.md

Installs the 'task' tool and then runs 'task deps' to fetch all development dependencies required for the project. Windows users may need to manually install goreleaser.

```bash
go install github.com/go-task/task/v3/cmd/task@latest
task deps
```

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

### Start Semaphore UI Server (Build)

Source: https://github.com/semaphoreui/semaphore/blob/develop/deployment/compose/README.md

Starts the Semaphore UI server by building the Docker image from the current source code. This includes all local changes.

```console
docker-compose -f deployment/compose/server/base.yml -f deployment/compose/server/build.yml up
```

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

### Start Semaphore and Authentik Stack

Source: https://github.com/semaphoreui/semaphore/blob/develop/examples/authentik_ldap/README.md

This snippet demonstrates how to start the Semaphore and Authentik Docker containers. It includes setting up environment variables for PostgreSQL password and Authentik secret key, and then launching the services using docker-compose.

```bash
echo "PG_PASS=$(openssl rand 36 | base64)" >> .env
echo "AUTHENTIK_SECRET_KEY=$(openssl rand 60 | base64)" >> .env
echo AUTHENTIK_TOKEN= >> .env
echo SEMAPHORE_LDAP_BIND_PASSWORD= >> .env
docker-compose up -d
```

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

### Start Semaphore UI Runner (Image)

Source: https://github.com/semaphoreui/semaphore/blob/develop/deployment/compose/README.md

Starts the Semaphore UI remote runner by downloading a pre-released Docker image from DockerHub and configuring it. This uses integrated bootstrapping scripts.

```console
docker-compose <server from above> -f deployment/compose/runner/base.yml -f deployment/compose/runner/image.yml up
```

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

### Dredd Configuration Example (BoltDB)

Source: https://github.com/semaphoreui/semaphore/blob/develop/CONTRIBUTING.md

Provides an example configuration file for Dredd, specifying the database connection details. This configuration must match the Semaphore server's database settings.

```json
{
    "bolt": {
        "host": "/tmp/database.boltdb"
    },
    "dialect": "bolt"
}
```

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

### Start Dredd Tests

Source: https://github.com/semaphoreui/semaphore/blob/develop/CONTRIBUTING.md

Initiates the Dredd integration tests using the specified configuration file. Dredd will validate the API against the defined documentation.

```bash
dredd --config ./.dredd/dredd.local.yml
```

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

### Install Dredd Globally

Source: https://github.com/semaphoreui/semaphore/blob/develop/CONTRIBUTING.md

Installs the Dredd command-line interface globally using npm. Dredd is used for API integration testing.

```bash
npm install -g dredd
```

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

### Start Semaphore UI Runner (Build)

Source: https://github.com/semaphoreui/semaphore/blob/develop/deployment/compose/README.md

Starts the Semaphore UI remote runner by building the Docker image from the current source code. This includes all local changes.

```console
docker-compose <server from above> -f deployment/compose/runner/base.yml -f deployment/compose/runner/build.yml up
```

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

### Start Semaphore Server for Dredd

Source: https://github.com/semaphoreui/semaphore/blob/develop/CONTRIBUTING.md

Starts the Semaphore server, which is required for Dredd to run integration tests against. The `--config` option can be used if a specific configuration file is needed.

```bash
./bin/semaphore server
```

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

### Start Semaphore UI Server with Custom Config

Source: https://github.com/semaphoreui/semaphore/blob/develop/deployment/compose/README.md

Starts the Semaphore UI server and allows providing a custom config.json file for options not exposed as environment variables. The config file is sourced from the current working directory.

```console
docker-compose <server from above> -f deployment/compose/server/config.yml up
```

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

### Run Semaphore Application

Source: https://github.com/semaphoreui/semaphore/wiki/Install-Semaphore-on-Debian-like-Linux-with-MySQL-8

Starts the Semaphore application using the generated configuration file. The application can then be accessed via a web browser at the specified URL. Instructions for running as a daemon are also provided.

```bash
$ sudo semaphore -config /opt/semaphore/config.json

In the browser input
http://semaphoresrv:3000/ to access the Semaphore.

User: Admin
Password: semaphore
```

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

### Configure PostgreSQL Database for Semaphore UI

Source: https://github.com/semaphoreui/semaphore/blob/develop/deployment/compose/README.md

Starts an additional container for a PostgreSQL instance to be used as the database backend for Semaphore UI, including the required credentials.

```console
docker-compose <server/runner from above> -f deployment/compose/store/postgres.yml up
```

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

### Create Go Workspace Directory

Source: https://github.com/semaphoreui/semaphore/blob/develop/CONTRIBUTING.md

Creates the necessary directory structure for the Go workspace and navigates into it. This is where the project source code will be placed.

```bash
mkdir -p $GOPATH/src/github.com/semaphoreui
cd $GOPATH/src/github.com/semaphoreui
```

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

### Configure MariaDB Database for Semaphore UI

Source: https://github.com/semaphoreui/semaphore/blob/develop/deployment/compose/README.md

Starts an additional container for a MariaDB instance to be used as the database backend for Semaphore UI, including the required credentials.

```console
docker-compose <server/runner from above> -f deployment/compose/store/mariadb.yml up
```

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

### Create MySQL Database

Source: https://github.com/semaphoreui/semaphore/blob/develop/CONTRIBUTING.md

Creates the 'semaphore' database in MySQL. This step is optional as Semaphore also supports bbolt, which does not require additional setup.

```bash
echo "create database semaphore;" | mysql -uroot -p
```

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

### Start Docker Compose Stack

Source: https://github.com/semaphoreui/semaphore/blob/develop/examples/openldap/README.md

Starts the Docker Compose services in detached mode. This command is essential for bringing up the necessary containers for Semaphore and OpenLDAP.

```bash
docker-compose up -d
```

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

### Command Line Examples with Curl

Source: https://github.com/semaphoreui/semaphore/wiki/API-&-automation

Provides practical examples of using the `curl` command-line tool to interact with the Semaphore API. These examples cover the entire workflow from logging in and managing authentication tokens to initiating task runs, demonstrating how to pass data and headers.

```bash
# Login to Semaphore
curl --cookie-jar /tmp/semaphore-cookie -X POST --header 'Content-Type: application/json' --header 'Accept: application/json'  -d '{"auth": "semaphore_user","password": "semaphore_password"}' https://ansible.yourdomain.com/api/auth/login -v

# Get user tokens
curl -b /tmp/semaphore-cookie https://ansible.yourdomain.com/api/user/tokens -v

# Generate a new token if user had no one
curl -b /tmp/semaphore-cookie -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' https://ansible.yourdomain.com/api/user/tokens -v

# Get user tokens again (after generation)
curl -b /tmp/semaphore-cookie https://ansible.yourdomain.com/api/user/tokens -v

# Launch a task using the generated token
curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'Authorization: Bearer long_random_token_string' -d '{"template_id": 1, "debug": false, "dry_run": false, "playbook": "", "environment": ""}' https://ansible.yourdomain.com/api/project/1/tasks -v

# Alternatively, launch a task using the cookie
curl -X POST -b /tmp/semaphore-cookie --header 'Content-Type: application/json' --header 'Accept: application/json' -d '{"template_id": 1, "debug": false, "dry_run": false, "playbook": "", "environment": ""}' https://ansible.yourdomain.com/api/project/1/tasks -v
```

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

### Start Semaphore UI Runner with Custom Config

Source: https://github.com/semaphoreui/semaphore/blob/develop/deployment/compose/README.md

Starts the Semaphore UI remote runner and allows providing a custom config.json file for options not exposed as environment variables. The config file is sourced from the current working directory.

```console
docker-compose <runner from above> -f deployment/compose/runner/config.yml up
```

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

### Configure MySQL Database for Semaphore UI

Source: https://github.com/semaphoreui/semaphore/blob/develop/deployment/compose/README.md

Starts an additional container for a MySQL instance to be used as the database backend for Semaphore UI, including the required credentials.

```console
docker-compose <server/runner from above> -f deployment/compose/store/mysql.yml up
```

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

### Install MySQL Server and Create Database

Source: https://github.com/semaphoreui/semaphore/wiki/Install-Semaphore-on-Debian-like-Linux-with-MySQL-8

Installs the MySQL server and client packages. It then connects to the MySQL root user to create a new database named 'semaphore' with UTF8 character set and collation.

```bash
$ sudo apt-get install mysql-server mysql-client
$ mysql -u root -p
mysql> CREATE DATABASE semaphore CHARACTER SET utf8 collate utf8_bin;
```

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

### Development Server

Source: https://github.com/semaphoreui/semaphore/blob/develop/web/README.md

Compiles the project and starts a hot-reloading development server.

```bash
npm run serve
```

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

### Install Required Packages

Source: https://github.com/semaphoreui/semaphore/wiki/Install-Semaphore-on-Debian-like-Linux-with-MySQL-8

Installs essential packages like wget, gnupg, git, and curl using apt-get. These are necessary for downloading files and managing software on Debian-based systems.

```bash
$ sudo apt-get update
$ sudo apt-get install wget gnupg git curl
```

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

### Download and Install Semaphore Package

Source: https://github.com/semaphoreui/semaphore/wiki/Install-Semaphore-on-Debian-like-Linux-with-MySQL-8

Downloads the Semaphore .deb package for Linux amd64 architecture and installs it using dpkg. Ensure you download the correct version for your system.

```bash
$ mkdir ~/install/semaphore
$ cd ~/install/semaphore
$ wget https://github.com/ansible-semaphore/semaphore/releases/download/v2.6.8/semaphore_2.6.8_linux_amd64.deb
$ sudo dpkg -i semaphore_2.6.8_linux_amd64.deb
```

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

### Database Migration Failure Example

Source: https://github.com/semaphoreui/semaphore/wiki/Troubleshooting

Shows an example of a database migration failure, indicating that the process did not complete successfully.

```text
Database migrations failed!
 ... error here ...
```

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

### Ansible Configuration for Collections and Roles

Source: https://github.com/semaphoreui/semaphore/wiki/First-Steps

This snippet shows how to configure Ansible to install collections and roles within a project's directory using the `ansible.cfg` file. It specifies custom paths for collections and roles.

```ansible
[defaults]
# Installs collections into [current dir]/ansible_collections/namespace/collection_name
collections_paths = ./

# Installs roles into [current dir]/roles/namespace.rolename
roles_path = ./roles
```

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

### Clone Semaphore Repository

Source: https://github.com/semaphoreui/semaphore/blob/develop/CONTRIBUTING.md

Clones the Semaphore project repository, including its submodules. Submodules are necessary for including external dependencies or components.

```bash
git clone --recursive git@github.com:semaphoreui/semaphore.git && cd semaphore
```

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

### Run Semaphore as a Systemd Service

Source: https://github.com/semaphoreui/semaphore/wiki/Install-Semaphore-on-Debian-like-Linux-with-MySQL-8

This snippet details the steps to configure and run Semaphore as a systemd service, including creating the service file, linking configuration, and managing the service lifecycle.

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

[Service]
Type=simple
ExecReload=/bin/kill -HUP $MAINPID
ExecStart=/usr/bin/semaphore -config /etc/semaphore/config.json
SyslogIdentifier=semaphore
Restart=always

[Install]
WantedBy=multi-user.target

sudo mkdir /etc/semaphore
sudo ln -s /opt/semaphore/config.json /etc/semaphore/config.json
sudo systemctl daemon-reload
sudo systemctl start semaphore
sudo systemctl status semaphore
# To make it auto start
sudo systemctl enable semaphore.service
```

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

### Configure SQLite Storage for Semaphore UI

Source: https://github.com/semaphoreui/semaphore/blob/develop/deployment/compose/README.md

Configures a named volume for SQLite storage, which is used as the database backend for Semaphore UI.

```console
docker-compose <server/runner from above> -f deployment/compose/store/sqlite.yml up
```

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

### Configure BoltDB Storage for Semaphore UI

Source: https://github.com/semaphoreui/semaphore/blob/develop/deployment/compose/README.md

Configures a named volume for BoltDB storage, which is used as the database backend for Semaphore UI.

```console
docker-compose <server/runner from above> -f deployment/compose/store/boltdb.yml up
```

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

### Database Connection Error Example

Source: https://github.com/semaphoreui/semaphore/wiki/Troubleshooting

Illustrates a common database connection error, specifically 'Access denied' due to incorrect credentials or missing password.

```text
Cannot connect to database!
 Error 1045: Access denied for user 'root'@'localhost' (using password: NO)

Your password for database is empty and is required.
```

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

### Set GOPATH and Add to PATH

Source: https://github.com/semaphoreui/semaphore/blob/develop/CONTRIBUTING.md

Configures the Go workspace path and adds the Go binary directory to the system's PATH environment variable. This is essential for using Go tools and managing Go projects.

```bash
export GOPATH=$HOME/go
export PATH=$PATH:$GOPATH/bin
```

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

### Restart Semaphore and Authentik Stack

Source: https://github.com/semaphoreui/semaphore/blob/develop/examples/authentik_ldap/README.md

This snippet shows the commands to stop and then restart the Docker stack after making changes to the .env file, ensuring that the new configurations are applied.

```bash
docker-compose down
docker-compose up -d
```

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

### Test Docker Images

Source: https://github.com/semaphoreui/semaphore/blob/develop/deployment/docker/README.md

Commands to lint and verify the contents of Semaphore Docker images using Hadolint and Goss. Dependencies like Golang are required, and installation paths can be customized via environment variables.

```console
task docker:test
```

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

### Checking Web Portal Accessibility with Curl

Source: https://github.com/semaphoreui/semaphore/wiki/Install-Semaphore-on-Debian-like-Linux-with-MySQL-8

This snippet demonstrates how to use `curl` to check the accessibility of the Semaphore web portal and inspect the returned HTML for clues about the issue, such as incorrect base URLs.

```bash
loginuser@semaphoresrv:/usr/bin$ curl http://localhost:3000
<!DOCTYPE html>
<html lang="en">
  <head>
    <base href="http://localhost:8010/">
    <meta charset="utf-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width,initial-scale=1.0">
    <link rel="icon" href="favicon.png">
    <title>Ansible Semaphore</title>
  <link href="/css/app.732af4fa.css" rel="preload" as="style"><link href="/css/chunk-vendors.0dc8d6a6.css" rel="preload" as="style"><link href="/js/app.7302c47a.js" rel="preload" as="script"><link href="/js/chunk-vendors.55b0185f.js" rel="preload" as="script"><link href="/css/chunk-vendors.0dc8d6a6.css" rel="stylesheet"><link href="/css/app.732af4fa.css" rel="stylesheet"></head>
  <body>
    <noscript>
      <strong>
          We're sorry but web2 doesn't work properly
          without JavaScript enabled. Please enable it to continue.
      </strong>
    </noscript>
    <div id="app"></div>
    <!-- built files will be auto injected -->
  <script type="text/javascript" src="/js/chunk-vendors.55b0185f.js"></script><script type="text/javascript" src="/js/app.7302c47a.js"></script></body>
</html>
```

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

### Docker Installation

Source: https://github.com/semaphoreui/semaphore/blob/develop/README.md

This snippet demonstrates how to run Semaphore UI using Docker. It maps port 3000, sets an admin user with a password, name, and email, and uses the latest Semaphore UI image. The SEMAPHORE_DB_DIALECT is set to 'bolt'.

```docker
docker run -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 \
	-d semaphoreui/semaphore:latest
```

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

### Semaphore Configuration for Web Host

Source: https://github.com/semaphoreui/semaphore/wiki/Install-Semaphore-on-Debian-like-Linux-with-MySQL-8

This snippet shows the relevant configuration parameter in `config.json` that controls the web portal's host. Setting `web_host` to an empty string is a common solution for accessibility issues.

```json
"web_host":""
```

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

### API Documentation Update Requirement

Source: https://github.com/semaphoreui/semaphore/blob/develop/CONTRIBUTING.md

Guideline for pull requests that modify the API. It emphasizes the need to update the Swagger documentation (`api-docs.yml`) to reflect any changes.

```APIDOC
Swagger Documentation Update:
  When modifying the API, ensure api-docs.yml is updated.
  This ensures consistency between the API implementation and its documentation.
```

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

### Build Dredd Hooks

Source: https://github.com/semaphoreui/semaphore/blob/develop/CONTRIBUTING.md

Compiles the Dredd hooks, which are necessary for running API integration tests. These hooks help Dredd interact with the application's API.

```bash
task dredd:hooks
```

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

### Dredd Integration Test Requirement

Source: https://github.com/semaphoreui/semaphore/blob/develop/CONTRIBUTING.md

Requirement for pull requests that alter the API. It mandates running integration tests using Dredd to ensure the API documentation accurately reflects the responses.

```APIDOC
Dredd Integration Tests:
  If the API is altered, run integration tests using Dredd.
  Verify that the information in the API docs matches the responses.
```

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

### Create MySQL User for Semaphore

Source: https://github.com/semaphoreui/semaphore/wiki/Install-Semaphore-on-Debian-like-Linux-with-MySQL-8

Creates a dedicated MySQL user named 'semaphore' with '%' host access, identified by 'mysql_native_password', and sets a password. This user will be used by the Semaphore application to connect to the database. For MySQL 8+, 'mysql_native_password' must be explicitly used.

```sql
mysql> CREATE USER 'semaphore'@'%' IDENTIFIED WITH mysql_native_password BY 'yourdbpasswd';
```

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

### Semaphore API Authentication and Task Execution

Source: https://github.com/semaphoreui/semaphore/wiki/API-&-automation

This section details the process of authenticating with the Semaphore API and executing tasks. It covers logging in using credentials, obtaining and using user tokens for authorization, and launching task templates via POST requests. Examples demonstrate both token-based and cookie-based authentication methods.

```APIDOC
API Endpoint: /api/auth/login
Method: POST
Description: Authenticates a user with Semaphore.
Request Body:
  {
    "auth": "semaphore_user",
    "password": "semaphore_password"
  }
Headers:
  Content-Type: application/json
  Accept: application/json
Response:
  204 No Content on successful login.
  Cookies: Stores authentication cookie for subsequent requests.

API Endpoint: /api/user/tokens
Method: GET
Description: Retrieves the user's authentication tokens.
Headers:
  Cookie: Session cookie obtained from login.
Response:
  An array of user tokens, or an empty array if none exist.

API Endpoint: /api/user/tokens
Method: POST
Description: Generates a new authentication token for the user.
Headers:
  Content-Type: application/json
  Accept: application/json
  Cookie: Session cookie obtained from login.
Response:
  201 Created on successful token generation.
  Returns the newly created token details.

API Endpoint: /api/project/{project_id}/tasks
Method: POST
Description: Launches a task template within a project.
Parameters:
  project_id: The ID of the project.
Request Body:
  {
    "template_id": 1,       // ID of the task template to run
    "debug": false,         // Enable debug mode
    "dry_run": false,       // Perform a dry run
    "playbook": "",         // Specify a playbook (optional)
    "environment": ""     // Specify environment variables (optional)
  }
Headers (Token-based):
  Content-Type: application/json
  Accept: application/json
  Authorization: Bearer <user_token>
Headers (Cookie-based):
  Content-Type: application/json
  Accept: application/json
  Cookie: Session cookie obtained from login.
Response:
  Details of the launched task.
```

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

### Grant Privileges to Semaphore MySQL User

Source: https://github.com/semaphoreui/semaphore/wiki/Install-Semaphore-on-Debian-like-Linux-with-MySQL-8

Grants all privileges on the 'semaphore' database to the 'semaphore' MySQL user. This allows the Semaphore application to perform necessary database operations. It also includes an example of how to alter the user's password.

```sql
mysql> GRANT ALL PRIVILEGES ON semaphore.* TO 'semaphore'@'%';
mysql> QUIT;
mysql> ALTER USER 'semaphore'@'%' IDENTIFIED WITH mysql_native_password BY 'newpasswd';
mysql> EXIT;
```

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

### Production Build

Source: https://github.com/semaphoreui/semaphore/blob/develop/web/README.md

Compiles and minifies the project for production deployment.

```bash
npm run build
```

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

### Systemd Unit File for Semaphore

Source: https://github.com/semaphoreui/semaphore/blob/develop/deployment/systemd/README.md

This systemd unit file defines how to run the Semaphore service. It specifies dependencies, user, working directory, execution commands, and restart policies. Logs are directed to the system journal.

```systemd
[Unit]
Description=Semaphore CI/CD
After=network.target

[Service]
Type=simple
User=semaphore
Group=semaphore
WorkingDirectory=/home/semaphore/semaphore
ExecStart=/usr/bin/semaphore
Restart=on-failure

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

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

### Linting and Formatting

Source: https://github.com/semaphoreui/semaphore/blob/develop/web/README.md

Lints the project files and automatically fixes common issues.

```bash
npm run lint
```

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

### MySQL 8 Authentication Error Resolution

Source: https://github.com/semaphoreui/semaphore/wiki/Install-Semaphore-on-Debian-like-Linux-with-MySQL-8

This section addresses the 'this authentication plugin is not supported' error when Semaphore connects to MySQL 8. It shows how to check the user's authentication plugin and how to alter the user to use 'mysql_native_password'.

```bash
mysql > CREATE USER 'semaphore'@'%' IDENTIFIED BY 'yourdbpasswd';
        ERROR when start semaphore:
        loginuser@semaphoresrv:~$ semaphore -config path/to/config.json
        Using config file: install/semaphore/config.json
        Semaphore v2.6.8
        Interface
        Port :3000
        MySQL semaphore@127.0.0.1:3306 semaphore
        Tmp Path (projects home) /home/loginuser/install/semaphore/playbook

         Have you run semaphore -setup?
        panic: this authentication plugin is not supported
    
        goroutine 1 [running]:
        main.main()
                        /go/src/github.com/ansible-semaphore/semaphore/cli/main.go:55 +0x845
```

```bash
$ sudo mysql -uroot -p
Enter password:
Welcome to the MySQL monitor.  Commands end with ; or \g.
Your MySQL connection id is 20772
Server version: 8.0.23-0ubuntu0.20.04.1 (Ubuntu)

Copyright (c) 2000, 2021, Oracle and/or its affiliates. 

Oracle is a registered trademark of Oracle Corporation and/or its
affiliates. Other names may be trademarks of their respective
owners.

Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.

mysql> use mysql
Reading table information for completion of table and column names
You can turn off this feature to get a quicker startup with -A

Database changed
mysql> select user, plugin from user;
+------------------+-----------------------+
| user             | plugin                |
+------------------+-----------------------+
| semaphore        | caching_sha2_password |
| debian-sys-maint | caching_sha2_password |
| mysql.infoschema | caching_sha2_password |
| mysql.session    | caching_sha2_password |
| mysql.sys        | caching_sha2_password |
| root             | auth_socket           |
| zabbix           | caching_sha2_password |
+------------------+-----------------------+
7 rows in set (0.01 sec)
```

```sql
mysql > ALTER USER 'semaphore'@'%' IDENTIFIED WITH mysql_native_password BY 'yourdbpasswd';
```

```bash
$ vim /etc/mysql/mysql.conf.d/mysqld.cnf
Add one line to set the default authentication to mysql_native_password.


    [mysqld]
    
    ... 
    default-authentication-plugin=mysql_native_password
    ...
    

$ sudo semaphore -setup
```

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

### Unit Tests

Source: https://github.com/semaphoreui/semaphore/blob/develop/web/README.md

Executes the project's unit tests.

```bash
npm run test:unit
```

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

### Build Docker Images

Source: https://github.com/semaphoreui/semaphore/blob/develop/deployment/docker/README.md

Commands to build and push Docker images for Semaphore. These tasks can be customized using environment variables for organization, server/runner names, and the build command itself (e.g., using Podman).

```console
task docker:build
task docker:push
```

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

### Semaphore UI - Ansible Playbook Repository

Source: https://github.com/semaphoreui/semaphore/wiki/Screenshots

Configuration screen for Ansible Playbook Repositories. This allows users to specify the location and details of their Ansible playbook source code.

```APIDOC
Screenshot:
  Name: playboookrepository
  URL: https://user-images.githubusercontent.com/29892975/27851752-c9c461b0-6179-11e7-9ddd-ea1e521ad82d.PNG
```

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

### Git SSH Command Environment Variable Requirement

Source: https://github.com/semaphoreui/semaphore/wiki/First-Steps

This explains a common troubleshooting step for Git clone failures in Semaphore. It highlights that Semaphore relies on the `GIT_SSH_COMMAND` environment variable, which requires Git version 2.3.0 or later.

```git
As `semaphore` rely on `GIT_SSH_COMMAND` environment variable, which was introduced in git 2.3.0,

---> update git to a more recent version!
```

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

### Apache License 2.0 Boilerplate

Source: https://github.com/semaphoreui/semaphore/blob/develop/web/src/assets/fonts/LICENSE.txt

This snippet shows the standard boilerplate notice required when applying the Apache License to your work. It includes placeholders for copyright year and owner, and the license text itself.

```plaintext
Copyright [yyyy] [name of copyright owner]

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
```

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

### Upgrade Failure: Semaphore Binary Not Found

Source: https://github.com/semaphoreui/semaphore/wiki/Troubleshooting

Details an upgrade issue where the 'semaphore' binary is not found in the system's PATH, preventing upgrades. It suggests moving the binary to a PATH-accessible location.

```text
`semaphore` not found in `$PATH`. Upgrading will not work.

You should move the `semaphore` binary to a location inside `$PATH` and run semaphore from there.

Well it isn't really possible for programs to tell where the binary is launched from. The program does its best to locate the binary by looking inside `$PATH` and `argv[0]`.
See [this SO question](https://stackoverflow.com/questions/933850/how-to-find-the-location-of-the-executable-in-c).
```

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

### Semaphore UI - Main Dashboard

Source: https://github.com/semaphoreui/semaphore/wiki/Screenshots

Screenshot of the main dashboard after a user logs into the Semaphore application. This view provides an overview of the system's status and key information.

```APIDOC
Screenshot:
  Name: maindashboard
  URL: https://user-images.githubusercontent.com/29892975/27851748-c9ac9e40-6179-11e7-9819-ea21052f1747.PNG
```

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

### Semaphore UI - Keystores

Source: https://github.com/semaphoreui/semaphore/wiki/Screenshots

Interface for managing Keystores. Keystores are used to securely store sensitive information like credentials or keys required for operations.

```APIDOC
Screenshot:
  Name: keystore
  URL: https://user-images.githubusercontent.com/29892975/27851750-c9bbd946-6179-11e7-8adf-5013f3f02eb2.PNG
```