Skip to content
Get packs

Guide · Open source

How to use Semaphore UI: Docker install, first run and tips

Updated · written with AI from the project's own documentation and checked against our catalogue data

Semaphore UI is a free, open-source web interface for running DevOps tools such as Ansible playbooks, Terraform and OpenTofu code, and Bash or PowerShell scripts. This guide shows how to start it with Docker, explains the core concepts (projects, task templates, tasks, schedules, inventories and variable groups), and lists the common questions people ask before adopting it. By the end you will know how to run the Docker command from the project README and what each part of the setup does.

Semaphoresemaphoreui/semaphore · ★ 14.4k · MIT

Quick start

  1. 1Install Docker. Semaphore's Docker route requires Docker. Make sure it is installed and running on the host.
  2. 2Start the container. Run the docker run command from the README, changing the admin password from the sample value.
  3. 3Open the web interface. Browse to port 3000 on the host and sign in with the admin account you configured.
  4. 4Create a project and inventory. Group related work into a project and list the target hosts in an inventory.
  5. 5Define a task template. Create a template for your Ansible playbook, Terraform/OpenTofu code or Bash/PowerShell script.
  6. 6Run or schedule the task. Run the template on demand or attach a schedule for repeatable runs, and watch for failure notifications.

What Semaphore UI does

Semaphore UI is a modern web interface for managing popular DevOps tools. Instead of running Ansible or Terraform from a terminal, you start them from a browser.

According to the project, it lets you run Ansible playbooks, Terraform and OpenTofu code, and Bash and PowerShell scripts; receive notifications about failed tasks; and control access to your deployment system.

  • Run Ansible playbooks, Terraform and OpenTofu code, and Bash or PowerShell scripts
  • Receive notifications about failed tasks
  • Control access to your deployment system

Understand the key concepts before you start

Semaphore organizes work into a small set of objects. Knowing them makes the interface easier to follow.

  • Projects: a collection of related resources, configurations and tasks.
  • Task Templates: reusable definitions of tasks that can run on demand or on a schedule.
  • Task: a specific instance of a job or operation executed by Semaphore.
  • Schedules: automate task execution at specified times or intervals.
  • Inventory: a collection of target hosts (servers, virtual machines, containers, etc.) where tasks run.
  • Variable Group: a configuration context holding sensitive information such as environment variables and secrets used by tasks.

Install Semaphore with Docker

The README lists Docker as the most popular installation method. Docker is the only prerequisite named for this route. The command below runs Semaphore on port 3000 with the SQLite database dialect and creates an admin account.

Replace the sample password `changeme` with your own before using the instance beyond testing. The README also recommends the Container Configurator on semaphoreui.com for an ideal Docker configuration.

  • Port 3000 is published to the host, so the web interface is reached on port 3000.
  • SEMAPHORE_DB_DIALECT=sqlite selects SQLite as the database.
  • SEMAPHORE_ADMIN, SEMAPHORE_ADMIN_PASSWORD, SEMAPHORE_ADMIN_NAME and SEMAPHORE_ADMIN_EMAIL set the initial admin account.
docker run -p 3000:3000 --name semaphore -e SEMAPHORE_DB_DIALECT=sqlite -e SEMAPHORE_ADMIN=admin -e SEMAPHORE_ADMIN_PASSWORD=changeme -e SEMAPHORE_ADMIN_NAME=Admin -e SEMAPHORE_ADMIN_EMAIL=admin@localhost -d semaphoreui/semaphore:latest

Create a project, inventory and task template

Once the container is running, sign in with the admin account you set. Group your work into a project, then add an inventory listing the target hosts. Next, define a task template for a playbook, Terraform configuration or script you want to run repeatedly.

Store passwords and secrets in a variable group rather than in the task itself, since variable groups hold sensitive values used during execution.

  • Create a project for related work.
  • Add an inventory of target hosts.
  • Create a task template for the Ansible playbook, Terraform/OpenTofu code or script.
  • Put sensitive values in a variable group.

Run tasks and schedule them

Task templates can be executed on demand. Each run becomes a task, which you can review. For repeatable runs, attach a schedule so the template runs at specified times or intervals.

Semaphore can notify you when a task fails, so problems surface without someone watching the run.

  • Run a template on demand to create a task.
  • Add a schedule to run it at set times or intervals.
  • Watch for failure notifications.

Control who can run deployments

Access control is one of the three main features the project describes. Use it to decide who can run deployment tasks in your system, which matters once more than one person uses the tool.

The README does not describe the specific roles or permission levels, so check the User Guide at docs.semaphoreui.com for those details.

Other install options and resources

Docker is not the only route. The README also lists a binary file, a Debian or RPM package, a Snap, and VM images from several marketplaces, with details on the Installation page at semaphoreui.com/install.

For reference material, the README links to the User Guide (docs.semaphoreui.com), the API Reference (semaphoreui.com/api-docs) and a Postman Collection.

  • Binary file, Debian or RPM package, Snap, or marketplace VM images
  • User Guide: docs.semaphoreui.com
  • API Reference: semaphoreui.com/api-docs

What people use it for

  • Running an Ansible playbook against a group of servers from a browser instead of a personal terminal
  • Scheduling a recurring Terraform or OpenTofu run for infrastructure that must be kept in a known state
  • Letting operations staff start approved deployment tasks while restricting who can run them
  • Running Bash or PowerShell maintenance scripts with failure notifications

Frequently asked questions

Is Semaphore UI free?

Semaphore UI is open source under the MIT licence, according to the README. The README also mentions a SaaS option, but that section is commented out, so the project's own docs are the place to confirm any hosted offering.

What are the requirements to install Semaphore UI?

The Docker install method listed in the README requires Docker. Other routes include a binary file, a Debian or RPM package, a Snap, or a marketplace VM, all detailed on the installation page.

How do I install Semaphore UI with Docker?

Run the docker run command from the README, which publishes port 3000 and sets SQLite and an admin account through environment variables. Then open the web interface on port 3000 and sign in.

Which tools does Semaphore UI run?

According to the README, it runs Ansible playbooks, Terraform and OpenTofu code, and Bash and PowerShell scripts. The README's headline also mentions Terragrunt.

Is Semaphore UI only for Ansible?

No. It supports Terraform, OpenTofu, Terragrunt, Bash, PowerShell and other DevOps tools, per the README. If you only use one tool from the command line and don't need a shared interface, it adds a server you must maintain.

What are the alternatives to Semaphore UI?

Comparable projects named for this item include AWX, Rundeck, Jenkins and Terraform Cloud alternatives such as Atlantis. Compare them on the tools each one runs and how much server maintenance it needs.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Semaphore UI suits teams that have outgrown running Ansible or Terraform from a personal terminal and want scheduled runs, failure notifications and access control. Solo users comfortable with the command line, or teams using tools outside Ansible, Terraform/OpenTofu, Terragrunt, Bash and PowerShell, should pick something else. It is also not a fit if you want a hosted service with nothing to install.

Install options & downloads