DOCSEARCHbyAlgolia
Submit Docs

Semaphore UI

repository·develop·Indexed 11 days ago

https://github.com/semaphoreui/semaphore

A modern web interface for managing DevOps tools including Ansible, Terraform, OpenTofu, Terragrunt, PowerShell, and Bash scripts. It provides a centralized platform for running automation, managing inventories, and controlling access to deployment systems. Supports deployment via Docker Compose, systemd, and various database backends including SQLite, MariaDB, MySQL, and PostgreSQL.

Tokens
14.6K
Snippets
63
Records
80
Agent score
95%

What's inside Semaphore UI

  1. What are the key concepts in Semaphore UI?

    develop

    To use Semaphore UI effectively, understand these core abstractions:

    • Projects: Collections of related resources, configurations, and tasks.
    • Task Templates: Reusable definitions of tasks that can be executed on demand or scheduled.
    • Task: A specific instance of a job or operation executed by Semaphore.
    • Schedules: Automations that trigger task execution at specific times or intervals.
    • Inventory: A collection of target hosts (servers, VMs, containers, etc.) where tasks are executed.
    • Variable Group: A configuration context used to hold sensitive information like environment variables and secrets for task execution.

  2. Configure Runner Registration Modes

    develop

    Runners connect to the Semaphore UI server using one of two registration methods:

    1. Global registration token: Set runner_registration_token in the server configuration (or retrieve the token from Admin → Runners in the UI). The runner presents this token on its first connection to receive a long-lived auth token.

    2. Per-runner registration token (smrs_…): This is ideal for Terraform-provisioned infrastructure where each host requires a unique identity.

      • Create an unregistered runner in the UI (uncheck "Registered") or via the API by setting "registered": false.
      • Generate a one-time registration token for that specific runner.
      • Pass the token to the semaphore runner register command.
      • Note: These tokens expire after one hour. If they expire, regenerate them from the UI.

    A runner is considered registered once it possesses an auth token (runner.token in the database). Unregistered runners will appear in the UI with a filter and cannot execute tasks until the registration process is complete.

  4. Explore other installation methods for Semaphore UI

    develop

    Beyond Docker, Semaphore UI can be installed via several methods:

    • Marketplace VM Deployments: Available on AWS, DigitalOcean, Vultr, and Yandex Cloud.
    • Snap: Available via Snapcraft.
    • Binary/Packages: Direct binary downloads or Debian/RPM packages.

    For a full list of options, visit the official Installation page.

  9. Set up Semaphore with Authentik LDAP using Docker Compose

    develop

    This guide demonstrates how to deploy Semaphore alongside Authentik using LDAP for authentication.

    1. Initialize Environment Variables

    Generate secure passwords for PostgreSQL and the Authentik secret key, and initialize the required LDAP environment variables in a .env file:

    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

    2. Perform Initial Semaphore Setup

    1. Navigate to http://localhost:9000/if/flow/initial-setup/.
    2. Set a password for the default akadmin user.

    3. Configure Authentik LDAP

    1. Set up LDAP in Authentik following the Authentik - LDAP Generic Setup tutorial.
    2. Copy the AUTHENTIK_TOKEN from the Authentik interface.

    4. Link Semaphore to Authentik

    1. Open your .env file.
    2. Paste the copied token after AUTHENTIK_TOKEN=.
    3. Enter your ldapservice user password after SEMAPHORE_LDAP_BIND_PASSWORD=.
    4. Restart the stack to apply the configuration:
    docker-compose down
docker-compose up -d

    5. Verify LDAP Login

    1. Open http://localhost:3000.
    2. Log in using the ldapservice user credentials.
    3. Create a new project to verify access.

  10. Deploy the Semaphore UI Server via Docker Compose

    develop

    To deploy the Semaphore UI server, you must first choose between building from local source or using a prebuilt image from DockerHub. You can then optionally add a custom configuration file.

    Build from source

    Use this if you have cloned the repository and want to include local changes in the image.

    Use prebuilt image

    Use this to download the official image from DockerHub.

    Use custom config

    If you need to provide a config.json file for options not exposed via environment variables, use the config.yml snippet which sources the file from your current working directory.

    # Build from source
docker-compose -f deployment/compose/server/base.yml -f deployment/compose/server/build.yml up

# Use prebuilt image
docker-compose -f deployment/compose/server/base.yml -f deployment/compose/server/image.yml up

# Use custom config (append to either of the above)
docker-compose -f deployment/compose/server/base.yml -f deployment/compose/server/image.yml -f deployment/compose/server/config.yml up

  12. Test Docker images for compliance and requirements

    develop

    To verify that your Docker images follow best practices and contain all required binaries and tools, use the docker:test task. This task utilizes Hadolint for linting and Goss for requirement verification.

    Prerequisites:

    • Golang must be installed on your system.

    Customization: You can customize the installation of testing dependencies using these environment variables:

    • INSTALL_PATH: The path where tools are installed (defaults to /usr/local/bin).
    • REQUIRE_SUDO: Set to true if sudo is required for installation.
    task docker:test