Pull semaphoreui/semaphore:latest this week and the container reports the 2.18 maintenance line, while the newest stable release on GitHub belongs to the 2.19 line. The two branches publish images on the same day, and whichever push lands last takes the latest tag, so an unpinned Compose file can quietly run the older branch. On our test box the gap was six database migrations, which is why every command below pins the tag it detects from the GitHub API.
This Semaphore Docker Compose setup runs the Ansible web UI with PostgreSQL 18 and puts it behind nginx with HTTPS. It then works through the objects the UI asks for in order: key store, repository, inventory, a task template that runs a real playbook over SSH, and a cron schedule. An image upgrade and a database backup that we restored close it out. We ran every step on an Ubuntu 26.04 VM with 4 vCPU and 6 GB of RAM, and the timings in the next section come from that box.
Tested October 2026 on Semaphore 2.19.16 (Ubuntu 26.04).
What the test box measured
The whole stack is light. Semaphore idled at 13 MiB of RAM and PostgreSQL at 34 MiB, so the memory a host needs is set by the Ansible runs, not by the UI. The larger cost is disk: the Semaphore image is 1.46 GB because it ships Python, ansible-core and the Galaxy tooling inside it.
| Measurement | Result | How it was taken |
|---|---|---|
First docker compose up -d | 47.9 s | time; Semaphore image pulled, postgres:18 already cached |
| Semaphore idle memory | 13.02 MiB | docker stats --no-stream after first start |
| PostgreSQL 18 idle memory | 33.64 MiB | same docker stats sample |
| Image sizes | 1.46 GB Semaphore, 650 MB postgres:18 | docker image ls |
| First playbook run, 5 tasks on 1 host | 6.9 s | task start and end times from the API |
| Upgrade from the 2.18 line to the 2.19 line | 6 migrations, API answering after 2.1 s | curl /api/ping loop after docker compose up -d |
| Database dump with 1 project and 1 task | 162 KB | pg_dump -Fc, restored into a scratch database |
Two of those rows change how the stack should be run. The 2.1 s upgrade window means an image bump can happen during working hours, as long as no task is running at that moment, because a task in flight dies with its container. The 162 KB dump means a nightly backup costs nothing, and losing the database without one costs every project, key and run log Semaphore holds.
How the pieces connect
Two containers and one host service make up the stack. nginx runs on the host, terminates TLS and forwards to Semaphore on the loopback address only. Semaphore talks to PostgreSQL over the private Compose network, and PostgreSQL publishes no port at all. Playbooks reach managed hosts over SSH from inside the Semaphore container, which is where ansible-playbook actually runs.

Binding Semaphore to 127.0.0.1:3000 is the setting that matters most in that picture. Docker writes its own iptables rules for published ports, so a plain 3000:3000 mapping is reachable from the LAN even when UFW denies it. With the loopback binding, a connection from a second machine to port 3000 was refused while HTTPS on 443 answered with a 200.
Prerequisites
Semaphore itself needs very little, so the sizing question is really about Ansible. Each running task forks ansible-playbook inside the container, and a playbook against 50 hosts with the default 5 forks uses far more CPU and memory than the UI ever will. The list below is what this guide assumes:
- Host: Ubuntu 26.04 with 2 vCPU and 2 GB RAM as a floor for following along (24.04 ships nginx 1.24, which rejects the
http2 on;line used in Step 4, and was not tested here); the 4 vCPU, 6 GB VM used here is not a production recommendation. Size up with forks and parallel tasks. - Docker: Docker Engine with the Compose plugin, and your user in the
dockergroup. The Docker CE install for Ubuntu 26.04 covers both. - Domain: an A record such as
semaphore.example.compointing at the server, with port 80 reachable from the internet for the Let’s Encrypt HTTP-01 check. Any DNS provider works. - Targets: at least one Linux host Semaphore can reach over SSH with a key, plus a Git repository or local directory holding playbooks.
- Disk: about 2.5 GB for images, plus the PostgreSQL volume, which grows with task logs.
Semaphore runs playbooks, it does not teach you how to write them, and a UI in front of a broken playbook only makes the failure prettier. Every task template in this guide points at a playbook you own, so the quality of the automation is set long before Semaphore enters the picture. If roles, handlers and inventories still feel unfamiliar, the Ansible books we rate for 2026 are a faster route than learning through failed task logs.
Our Ansible automation guide walks through the same concepts with tested examples. Working through it first means the templates you build in Step 9 point at playbooks you already trust from the command line. Any failure in Semaphore is then a Semaphore problem, not a playbook problem.
Step 1: Set reusable shell variables
The directory, hostname and image tag appear in several commands, so they live in shell variables. The version detection reads the newest stable release tag from the GitHub API instead of trusting latest, for the reason the intro gave. It relies on the maintainers marking only the newest branch as the GitHub “latest” release, which held when we tested. Check that the echo line shows the 2.19 line or newer before going on. If it shows a 2.18 tag, take the newest 2.19 tag from the releases page and set SEMAPHORE_VERSION to it by hand (the full tag, including the leading v). Replace the domain and email with your own values:
export APP_ROOT="/opt/semaphore"
export SITE_DOMAIN="semaphore.example.com"
export ADMIN_EMAIL="[email protected]"
export SEMAPHORE_VERSION=$(curl -s https://api.github.com/repos/semaphoreui/semaphore/releases/latest | grep '"tag_name"' | cut -d '"' -f 4)
echo "Semaphore: ${SEMAPHORE_VERSION} Root: ${APP_ROOT} Domain: ${SITE_DOMAIN}"
The echo line should print a tag that starts with v. An empty value usually means the GitHub API rate limit was hit from a shared IP, so wait a minute and run the export again before going further. Our run printed this.
Semaphore: v2.19.16 Root: /opt/semaphore Domain: semaphore.example.com
These variables only exist in the current shell. After reconnecting, export the four lines again before running any later command, otherwise ${APP_ROOT} expands to an empty string and commands such as cd ${APP_ROOT} land in the home directory instead. That failure is silent, so the echo line is worth repeating after every reconnect.
Step 2: Write the Semaphore Docker Compose file
Secrets go into a .env file next to the Compose file, which Docker Compose reads automatically, so the Compose file itself can be shared without leaking passwords. The command below generates the database password, the admin password and the 32-byte key that encrypts everything stored in the Key Store:
sudo mkdir -p "${APP_ROOT}/playbooks"
sudo chown -R "$USER": "${APP_ROOT}"
cd "${APP_ROOT}"
printf 'SEMAPHORE_VERSION=%s\nSITE_DOMAIN=%s\nDB_PASS=%s\nADMIN_PASS=%s\nADMIN_EMAIL=%s\nACCESS_KEY_ENCRYPTION=%s\n' "${SEMAPHORE_VERSION}" "${SITE_DOMAIN}" "$(openssl rand -hex 16)" "$(openssl rand -hex 12)" "${ADMIN_EMAIL}" "$(head -c32 /dev/urandom | base64)" > .env
chmod 600 .env
Treat ACCESS_KEY_ENCRYPTION as part of the database. Semaphore encrypts SSH keys and passwords with it before writing them to PostgreSQL, so a restored database without the matching key still lists every credential but cannot decrypt any of them. You would then re-enter every key by hand, which on a busy project means touching every managed host again. The backup step later copies .env for exactly that reason, and the file should live wherever you keep other secrets, never in the playbook repository.
Open the Compose file in the project directory. Docker Compose looks for compose.yaml and .env in the directory it runs from, so keeping both in /opt/semaphore means every later command works after a plain cd ${APP_ROOT}.
vim "${APP_ROOT}/compose.yaml"
Paste the following, which is the exact file the test box ran:
services:
postgres:
image: postgres:18
restart: unless-stopped
environment:
POSTGRES_USER: semaphore
POSTGRES_PASSWORD: ${DB_PASS}
POSTGRES_DB: semaphore
volumes:
- pgdata:/var/lib/postgresql
healthcheck:
test: ["CMD-SHELL", "pg_isready -U semaphore -d semaphore"]
interval: 5s
timeout: 5s
retries: 10
semaphore:
image: semaphoreui/semaphore:${SEMAPHORE_VERSION}
restart: unless-stopped
ports:
- "127.0.0.1:3000:3000"
environment:
SEMAPHORE_DB_DIALECT: postgres
SEMAPHORE_DB_HOST: postgres
SEMAPHORE_DB_PORT: 5432
SEMAPHORE_DB_USER: semaphore
SEMAPHORE_DB_PASS: ${DB_PASS}
SEMAPHORE_DB: semaphore
SEMAPHORE_ADMIN: admin
SEMAPHORE_ADMIN_NAME: Admin
SEMAPHORE_ADMIN_EMAIL: ${ADMIN_EMAIL}
SEMAPHORE_ADMIN_PASSWORD: ${ADMIN_PASS}
SEMAPHORE_ACCESS_KEY_ENCRYPTION: ${ACCESS_KEY_ENCRYPTION}
SEMAPHORE_WEB_ROOT: https://${SITE_DOMAIN}
TZ: UTC
volumes:
- ./playbooks:/playbooks:ro
extra_hosts:
- "host.docker.internal:host-gateway"
depends_on:
postgres:
condition: service_healthy
volumes:
pgdata:
Most of that file is the upstream example from the Semaphore Docker docs. Some edits are obvious: postgres:18 instead of 14, a pinned tag instead of latest, and secrets read from .env. We also dropped SEMAPHORE_PLAYBOOK_PATH, which the current server no longer reads. The changes below matter more, because the defaults failed or exposed something on the test box:
- Volume at
/var/lib/postgresql: the PostgreSQL 18 image changed its data layout and refuses to start with the old/var/lib/postgresql/datapath; the exact error is in the troubleshooting section. - Health check plus
condition: service_healthy: Semaphore waits until PostgreSQL accepts connections, which avoids the restart loop older guides fixed by hand withdocker compose restart. 127.0.0.1:3000binding: only nginx on the same host can reach the UI, so Docker’s own iptables rules cannot expose it to the LAN.- Read-only
./playbooksmount andextra_hosts: a task can never rewrite the code it runs, and playbooks can reach the Docker host itself ashost.docker.internal. SEMAPHORE_WEB_ROOTset to the HTTPS URL: Semaphore marks its session cookieSecureonly when this is an https URL, and task links in alerts use it; our login over HTTPS returnedSecure; HttpOnly; SameSite=Laxwith it set.
Validate the file before starting anything, because Compose substitutes the ${...} references at this point and a typo in a variable name only shows up as an empty value. No output and a zero exit code mean the YAML parsed and every reference resolved:
docker compose config --quiet; echo "config rc=$?"
A missing .env value shows up here as a warning naming the variable. That is far easier to fix now than after PostgreSQL has initialised its volume with an empty password. The postgres image applies POSTGRES_PASSWORD only when it initialises an empty data directory, so changing .env later does not update it.
Step 3: Start Semaphore and check the logs
Start both containers. Compose waits for the PostgreSQL health check before it starts Semaphore, so the first run takes longer than later ones. On the test box it needed 47.9 seconds, which included pulling the Semaphore image (postgres:18 was already cached). Later restarts reuse the images and the initialised volume and finish in a few seconds:
docker compose up -d
We trimmed the image pull progress from this excerpt. The last lines show PostgreSQL reaching healthy before Semaphore starts.
Container semaphore-postgres-1 Started
Container semaphore-postgres-1 Waiting
Container semaphore-postgres-1 Healthy
Container semaphore-semaphore-1 Starting
Container semaphore-semaphore-1 Started
On first start Semaphore runs its schema migrations, creates the admin user from the environment and then starts the HTTP server. Wait until the API answers, then pull the three lines that confirm each of those happened out of the log. The wait gives up after two minutes, so a Semaphore that cannot start (it restarts in a loop when the database is unreachable) returns you to the prompt instead of hanging; in that case read docker compose logs semaphore in full:
timeout 120 sh -c 'until curl -sf http://127.0.0.1:3000/api/ping >/dev/null; do sleep 2; done'
docker compose logs --no-log-prefix semaphore 2>&1 | grep -E "Migrations Finished|You can login|Server is running"
All three should appear on a first start. If Migrations Finished is missing, Semaphore could not reach the database and the lines above it in the full log name the reason:
Migrations Finished
You can login with [email protected] or admin.
Server is running
The API answers on the loopback address only. A pong here, combined with a refused connection from any other machine, is the state to reach before nginx goes in front, because it proves the UI cannot be reached around the proxy:
curl -s http://127.0.0.1:3000/api/ping; echo
The capture below was taken on the test box after the HTTPS step. It also shows the tag trap from the intro: the same host pulling latest gets the older branch.

The admin password is the random value written to .env in Step 2. Semaphore only reads SEMAPHORE_ADMIN_PASSWORD when it creates the admin on first start, so changing it in .env later has no effect. Print it once and store it in your password manager:
grep '^ADMIN_PASS=' "${APP_ROOT}/.env"
If you lose it anyway, Step 12 ends with the one-line reset from the host, so a forgotten password never means a reinstall.
Step 4: Add nginx and HTTPS
Semaphore serves plain HTTP and streams task logs over a WebSocket, so the proxy has two jobs: terminate TLS and pass the Upgrade header through on /api/ws. Install nginx and certbot from the Ubuntu archive:
sudo apt install -y nginx certbot
Request the certificate before writing the Semaphore site. The stock nginx site already serves /var/www/html on port 80, which is all the HTTP-01 webroot challenge needs. Using webroot also means the nginx file below stays exactly as written instead of being edited by certbot:
sudo certbot certonly --webroot -w /var/www/html -d "${SITE_DOMAIN}" --non-interactive --agree-tos -m "${ADMIN_EMAIL}" --deploy-hook "systemctl reload nginx"
That command was not run in our lab because the VM has no public DNS name; it is the standard certbot HTTP-01 webroot flow. The lab placed a certificate signed by a private test CA at the same paths under /etc/letsencrypt/live/, so every nginx line below was tested as written. If port 80 cannot be opened (a server on a private network, or a wildcard name), use a certbot DNS plugin for your provider instead. Ubuntu packages them as python3-certbot-dns-cloudflare, python3-certbot-dns-route53 and similar, and the rest of this step stays unchanged.
Create the site file in conf.d, which nginx on Ubuntu includes automatically, so no symlink into sites-enabled is needed.
sudo vim /etc/nginx/conf.d/semaphore.conf
Add this configuration. SITE_DOMAIN_HERE is a placeholder that the next command replaces:
upstream semaphore {
server 127.0.0.1:3000;
}
server {
listen 80;
listen [::]:80;
server_name SITE_DOMAIN_HERE;
location /.well-known/acme-challenge/ {
root /var/www/html;
}
location / {
return 301 https://$host$request_uri;
}
}
server {
listen 443 ssl;
listen [::]:443 ssl;
http2 on;
server_name SITE_DOMAIN_HERE;
ssl_certificate /etc/letsencrypt/live/SITE_DOMAIN_HERE/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/SITE_DOMAIN_HERE/privkey.pem;
ssl_protocols TLSv1.2 TLSv1.3;
add_header Strict-Transport-Security "max-age=31536000" always;
location / {
proxy_pass http://semaphore;
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;
proxy_buffering off;
proxy_request_buffering off;
}
location /api/ws {
proxy_pass http://semaphore/api/ws;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Origin "";
proxy_set_header Host $host;
proxy_read_timeout 1h;
}
}
Each block in that file answers a specific failure we wanted to avoid, and the WebSocket one is the easiest to get wrong:
- Port 80 server: keeps
/.well-known/acme-challenge/on plain HTTP so certbot renewals keep working, and sends everything else to HTTPS with a 301. location /: forwards to127.0.0.1:3000with buffering off, so large task outputs reach the browser as they are written.location /api/ws: passesUpgradeandConnection, and setsOrigin ""as Semaphore’s own nginx example does, so a Semaphore build that checks the Origin header still accepts the proxied socket.proxy_read_timeout 1h: Semaphore pings an idle socket only about every two minutes, and nginx would otherwise close a quiet log stream after 60 seconds.
Fill in the domain, drop the default site and test the result. The sed line exists because nginx cannot read shell variables, so the placeholder has to be replaced in the file itself:
sudo sed -i "s/SITE_DOMAIN_HERE/${SITE_DOMAIN}/g" /etc/nginx/conf.d/semaphore.conf
sudo rm -f /etc/nginx/sites-enabled/default
sudo nginx -t && sudo systemctl reload nginx
nginx -t must report both lines below before the reload runs. The && means a failed test skips the reload, so a typo leaves the previous configuration serving traffic instead of taking the site down.
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful
Open only SSH, HTTP and HTTPS in UFW. Allow OpenSSH first, because enabling UFW without it over an SSH session cuts the session off. If that happens, the Proxmox, cloud or IPMI console is the way back in, where sudo ufw allow OpenSSH restores access:
sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw --force enable
Port 3000 is not in that list and does not need a deny rule, because it is bound to the loopback address. Check the redirect, the challenge path and the HTTPS API in one pass:
curl -sI "http://${SITE_DOMAIN}/auth/login" | grep -iE '^(HTTP|location)'
curl -s "https://${SITE_DOMAIN}/api/ping"; echo
Port 80 answers with a 301 to HTTPS and the API replies through nginx. These lines came from our lab run, where curl also passed --cacert for the private CA, a flag a Let’s Encrypt certificate does not need.
HTTP/1.1 301 Moved Permanently
Location: https://semaphore.example.com/auth/login
pong
On Rocky Linux or AlmaLinux with SELinux enforcing, nginx also needs sudo setsebool -P httpd_can_network_connect 1 before it may connect to port 3000. Without it every request returns 502, and ausearch -m avc -ts recent shows the denial. That came from the April run of this guide on Rocky Linux 10.1 and was not repeated this month. On the RHEL family, check the AVC log after the first login rather than assuming the boolean is still the only change needed.
Step 5: Log in and create a project
Browse to https://semaphore.example.com and sign in as admin with the password from .env. The login page loads over HTTPS:

A fresh install has no projects, so Semaphore opens the New Project form straight after login. A project is the boundary for everything else: keys, repositories, inventories and templates created inside one project are invisible to another, which makes it the natural unit for separating teams or environments. Enter a name and click CREATE; the lab used Homelab Baseline, and the rest of this guide refers to that project. CREATE DEMO PROJECT fills a project with sample objects instead, which is useful for a look around and noise afterwards.

The project sidebar then lists Dashboard, Task Templates, Workflows, Schedule, Inventory, Variable Groups, Key Store, Repositories, Integrations, Team and Runners. The next four steps fill them in the order the template needs them.
Step 6: Store an SSH key in the Key Store
Semaphore connects to managed hosts with a key from its Key Store, so the key comes first. Generate a dedicated key pair on the Docker host and authorise it for the account Ansible will log in as. Run this as your own login on the Docker host, the account that owns ~/.ssh/authorized_keys; our lab used the klinsmann account, so put your own username wherever this guide shows that one. The playbook later uses become: true, so that account also needs passwordless sudo, or a sudo password stored in the Key Store and picked as Sudo Credentials in Step 8:
ssh-keygen -t ed25519 -N "" -C semaphore -f ~/.ssh/semaphore_ed25519 -q
cat ~/.ssh/semaphore_ed25519.pub >> ~/.ssh/authorized_keys
For a remote server, append the .pub file to that server’s ~/.ssh/authorized_keys instead, for example with ssh-copy-id -i ~/.ssh/semaphore_ed25519.pub user@host (the lab only used the local host). In the UI, open Key Store, click NEW KEY, name it bench01-ssh, choose SSH Key as the type, put your login in Username (Optional) and paste the output of cat ~/.ssh/semaphore_ed25519 into Private Key:

In the lab the same fields were sent to POST /api/project/1/keys from the VM, so the private key never left the test host; the stored result is identical. After CREATE, the key list shows bench01-ssh next to the built-in None key, which is what public repositories use:

With the key stored, nothing else in the project needs the private key again, because inventories and repositories refer to it by name.
Step 7: Add the playbook repository
A repository can be a Git URL over SSH or HTTPS, or a local path. A Git URL is the right choice for a team, because Semaphore clones the branch on every run and the task log records the commit. The lab used a local path to stay self-contained: a Git repository in /opt/semaphore/playbooks, mounted read-only at /playbooks. Create the playbook file:
vim "${APP_ROOT}/playbooks/baseline.yml"
Paste this playbook. It installs two packages, writes a marker file and reports uptime, which is enough to prove that SSH, sudo and the task log all work:
---
- name: Baseline for managed hosts
hosts: all
become: true
tasks:
- name: Install baseline packages
ansible.builtin.apt:
name:
- jq
- tree
state: present
update_cache: true
cache_valid_time: 3600
- name: Write the managed-by marker
ansible.builtin.copy:
dest: /etc/managed-by-semaphore
content: "Managed by Semaphore. Manual edits are overwritten.\n"
mode: "0644"
- name: Read uptime
ansible.builtin.command: uptime -p
register: host_uptime
changed_when: false
- name: Report uptime
ansible.builtin.debug:
msg: "{{ inventory_hostname }} is {{ host_uptime.stdout }}"
Commit it and let the Ansible inside the Semaphore image check the syntax. The image carries its own ansible-core, so the host does not need Ansible installed at all. Keep the -T and < /dev/null on exec lines that have more commands after them: docker compose exec reads the terminal, and when we pasted multi-line blocks, an exec without them swallowed the lines that followed it.
cd "${APP_ROOT}/playbooks"
git init -q -b main
git add baseline.yml
git -c user.name="Semaphore Admin" -c user.email="${ADMIN_EMAIL}" commit -qm "Add baseline playbook"
cd "${APP_ROOT}"
docker compose exec -T semaphore ansible --version < /dev/null | head -1
docker compose exec semaphore ansible-playbook --syntax-check /playbooks/baseline.yml
The image on the test box shipped ansible-core 2.20, and the syntax check ends on the playbook path. The two warnings about an empty inventory are expected, because no inventory is passed to a syntax check:
ansible [core 2.20.10]
[WARNING]: No inventory was parsed, only implicit localhost is available
[WARNING]: provided hosts list is empty, only localhost is available. Note that the implicit localhost does not match 'all'
playbook: /playbooks/baseline.yml
In Repositories, click NEW REPOSITORY, name it baseline-playbooks, put /playbooks in URL or path and pick None as the access key. Semaphore labels the value as a local absolute path under the field, which confirms it parsed the entry the way you meant:

Click CREATE and the repository appears in the list with its path and the None key.
Step 8: Add an inventory and variable group
Under Inventory, click NEW INVENTORY and choose Ansible Inventory. Name it bench-hosts, set User Credentials to the SSH key from Step 6, pick Static as the type and paste an INI inventory. Inside the container, host.docker.internal resolved to the Docker host at 172.17.0.1 on our test box. Replace klinsmann with your own login, and for remote servers list their real hostnames or IPs instead:
[bench]
host.docker.internal ansible_user=klinsmann
The dialog with those values filled in looks like this. Sudo Credentials stays empty because the lab user has passwordless sudo; for an account that needs a sudo password, store it as a Login with password key and select it there:

Templates also take one or more variable groups, which hold extra vars and secrets per environment. Open Variable Groups, click NEW GROUP, name it bench-vars and save it empty for now. Keeping one group per environment from the start makes it simple to clone a template for production later and swap only the group.
Step 9: Create a task template and run it
A task template ties a repository path, an inventory and variable groups together, and it is the object people actually click. Open Task Templates, choose NEW TEMPLATE and then Ansible Playbook. Fill in the name, the repository, baseline.yml as the playbook path, the bench-hosts inventory and the bench-vars group:

After CREATE, the template appears in the list with the status Not launched. Click the play button on its row. The run dialog takes an optional message, which shows up in the history and answers the question of why a run happened, plus Dry Run and Diff switches that map to --check and --diff:

Click RUN. The log streams live over the WebSocket, so seeing the lines arrive while the task runs is the quickest proof that the /api/ws block in the nginx file works. The first run on the test box finished in 6.9 seconds:

We also pulled the same log as text from the API. Its recap line is the part to read, because changed=1 is the marker file, the packages were already present on this cloud image, and unreachable=0 confirms the key and inventory are right.
PLAY RECAP *********************************************************************
host.docker.internal : ok=5 changed=1 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0
Ansible on the target is not touched by any of this. The playbook ran inside the Semaphore container, and the managed host only needs SSH and Python, which is why the log carries a warning about the discovered /usr/bin/python3.14 interpreter on the target. The warning does not fail the run.
Step 10: Schedule the template
Schedules run a template on a cron expression. Open Schedule, click NEW SCHEDULE, choose Cron from its menu, pick the template and enter the expression in the Cron field, with the Show cron format toggle on as in the screenshot. Use 0 3 * * * for a nightly baseline. The lab used */5 * * * * only so a scheduled run could be observed within minutes; left like that, it adds 288 task logs a day to the database:

Cron times are UTC by default, as the dialog notes, and SEMAPHORE_SCHEDULE_TIMEZONE in the Compose environment changes that. The first scheduled run started at 12:45:00 UTC exactly, carried no user name and reported changed=0, which is what an idempotent playbook should do on its second pass. The dashboard history keeps both runs side by side:

The core setup ends here, with HTTPS, a project, a key, a repository, an inventory, a template and a schedule in place. The next two steps are what keep it running for longer than a month, and both were exercised on the test box rather than copied from the docs.
Step 11: Upgrade Semaphore
An upgrade is a new tag in .env, a pull and a container recreate; Semaphore applies any schema migrations on start. Take a dump first (Step 12 shows the command) so a failed migration can be rolled back, and pick a moment with no task running, because the recreate kills a task in progress. It also logs everyone out: the config inside the container is regenerated on every recreate, and a session cookie from before a forced recreate got HTTP 401 afterwards on our box. The pull fetches both images, so PostgreSQL picks up its minor releases at the same time. Re-run the detection and write the new tag:
cd "${APP_ROOT}"
export SEMAPHORE_VERSION=$(curl -s https://api.github.com/repos/semaphoreui/semaphore/releases/latest | grep '"tag_name"' | cut -d '"' -f 4)
sed -i "s/^SEMAPHORE_VERSION=.*/SEMAPHORE_VERSION=${SEMAPHORE_VERSION}/" .env
docker compose pull
docker compose up -d
To test this path, a second stack was started on the 2.18 build that latest pointed at, given a project, then bumped with exactly these commands. The log shows each migration it applied, all within the same second, and the project created on the old build was still listed afterwards:
Executing migration v2.18.6 (at 2026-10-18 12:43:06.325905981 +0000 UTC)...
Executing migration v2.18.15 (at 2026-10-18 12:43:06.342926922 +0000 UTC)...
Executing migration v2.19.2 (at 2026-10-18 12:43:06.3739785 +0000 UTC)...
Executing migration v2.19.11 (at 2026-10-18 12:43:06.377908667 +0000 UTC)...
Executing migration v2.19.12 (at 2026-10-18 12:43:06.383671257 +0000 UTC)...
Executing migration v2.19.14 (at 2026-10-18 12:43:06.387525372 +0000 UTC)...
Migrations Finished
Semaphore v2.19.16-f8cefe6-1791363789
PostgreSQL is a different matter. Its tag in the Compose file is the major version on purpose, so postgres:18 picks up minor releases on a pull. A move to 19 needs pg_upgrade or a dump and restore, because a new major will not open the old data directory. We would treat it as a planned job, never as part of a routine pull.
Step 12: Back up and restore the database
Everything Semaphore knows lives in PostgreSQL, apart from the encryption key in .env. A custom-format dump plus a copy of .env is therefore a complete backup, and pg_dump takes a consistent snapshot while the stack keeps running, so there is no need to stop Semaphore for it:
cd "${APP_ROOT}"
mkdir -p backups
docker compose exec -T postgres pg_dump -U semaphore -Fc semaphore < /dev/null > "backups/semaphore-$(date +%F).dump"
cp .env "backups/env-$(date +%F)"
chmod 600 backups/*
A backup is only proven once it restores. The drill below loads the dump into a scratch database next to the live one and counts the rows that matter, then drops the scratch copy:
docker compose exec -T postgres createdb -U semaphore semaphore_restore < /dev/null
docker compose exec -T postgres pg_restore -U semaphore -d semaphore_restore < "backups/semaphore-$(date +%F).dump"
docker compose exec -T postgres psql -U semaphore -d semaphore_restore -tAc "select 'projects', count(*) from project union all select 'templates', count(*) from project__template union all select 'tasks', count(*) from task union all select 'keys', count(*) from access_key" < /dev/null
docker compose exec -T postgres dropdb -U semaphore semaphore_restore
The counts we got match what the UI shows, with one project, one template, the first task and two keys (the SSH key plus the built-in None). The dump was 162 KB.
projects|1
templates|1
tasks|1
keys|2
A full restore over the live database is the same dump loaded into an empty semaphore database while Semaphore is stopped. In a real recovery the dump you want is usually from an earlier day, so list the files and set DUMP to the one you need first:
cd "${APP_ROOT}"
ls backups/
export DUMP="backups/semaphore-2026-10-18.dump"
Then stop Semaphore and replace the database. We tested this sequence after deleting a project, and the project came back and the admin could log in again:
cd "${APP_ROOT}"
docker compose stop semaphore
docker compose exec -T postgres dropdb -U semaphore semaphore < /dev/null
docker compose exec -T postgres createdb -U semaphore semaphore < /dev/null
docker compose exec -T postgres pg_restore -U semaphore -d semaphore < "${DUMP}"
docker compose start semaphore
A new host needs a different order, because there is no database or Semaphore container yet. On a genuinely new machine, install Docker, run the Step 1 exports again and create ${APP_ROOT} as in Step 2 first, and set up nginx and the certificate from Steps 4 and 5 before HTTPS answers. Copy compose.yaml, the old .env, playbooks/ and backups/ into ${APP_ROOT} before the first docker compose up. PostgreSQL takes its password from .env only when it creates the volume, and Semaphore needs the same ACCESS_KEY_ENCRYPTION to read the stored keys. Set DUMP as above, start PostgreSQL alone, restore, then bring up the rest:
cd "${APP_ROOT}"
docker compose up -d --wait postgres
docker compose exec -T postgres pg_restore -U semaphore -d semaphore < "${DUMP}"
docker compose up -d
There is no dropdb or createdb here, because the postgres image creates the empty semaphore database from POSTGRES_DB on first start, and --wait holds the restore back until the health check passes. We tested this on the same VM by deleting the whole directory and its volume, copying the four items into a fresh /opt/semaphore and running the block, so the images, nginx and the certificate were already in place: the project created before the dump was listed again, the admin login returned 204 and the HTTPS front page 200. Copy backups/ off the host regularly, because a dump that sits on the same disk as the database protects against mistakes, not against losing the server.
Two smaller recovery tasks come up often enough to keep at hand. A forgotten admin password is reset from the host with docker compose exec semaphore semaphore user change-by-login --login admin --password 'NewPass2026' --config /etc/semaphore/config.json, which the lab used and which replied User admin <[email protected]> changed!. For a lighter footprint without Docker, the native .deb install of Semaphore on Ubuntu and Debian uses a systemd service instead.
Teams that need Ansible’s own controller model can compare it with AWX on Rocky Linux. AWX runs on Kubernetes through its operator, so it brings far more moving parts than the two containers measured here. We would only reach for it when an organisation already standardises on the Red Hat automation stack.
Troubleshooting
Error: “in 18+, these Docker images are configured to store database data in a format which is compatible with pg_ctlcluster”
PostgreSQL 18 images store data under a major-version directory, /var/lib/postgresql/18/docker, instead of /var/lib/postgresql/data. Compose files copied from older guides, including the previous version of this one, mount the volume at the old path, and the container then exits on every start. Mounting the old path on a fresh volume reproduced it on the test box:
Error: in 18+, these Docker images are configured to store database data in a
format which is compatible with "pg_ctlcluster" (specifically, using
major-version-specific directory names). This better reflects how
PostgreSQL itself works, and how upgrades are to be performed.
See also https://github.com/docker-library/postgres/pull/1259
Counter to that, there appears to be PostgreSQL data in:
/var/lib/postgresql/data (unused mount/volume)
On a new install, change the mount to pgdata:/var/lib/postgresql as in Step 2. On an existing PostgreSQL 17 volume, keep postgres:17 until a planned upgrade, because pointing the 18 image at 17 data is exactly the case the error is protecting you from.
The UI shows an older version than the GitHub release page
This is the latest tag problem from the intro rather than a caching bug. Check what the container runs with docker compose exec semaphore semaphore version. If it reports the 2.18 line while you expected 2.19, set SEMAPHORE_VERSION in .env to the tag from the API detection and recreate the container as in Step 11.
What to watch after go-live
A Semaphore host rarely fails loudly. It fails as a schedule that stopped running or a disk that filled with task logs, so the checks worth automating are small:
- Task failures: the dashboard history filtered by status, or
select status, count(*) from task group by statusin PostgreSQL; a scheduled template that stops adding rows is a dead schedule. - Database size:
select pg_size_pretty(pg_database_size('semaphore')); task output is stored row by row, and long, chatty playbooks grow it fastest. - Container memory during runs:
docker statswhile a large inventory runs; idle numbers (13 MiB here) say nothing about a 50-host play with 20 forks. - Certificate renewal:
sudo certbot renew --dry-runonce after setup, then the certbot timer’s journal. - Image tag drift: compare
semaphore versionwith the GitHub API detection monthly, since nothing upgrades a pinned tag for you.
Of those, the backup restore drill is the one teams skip and regret. Run Step 12’s restore against a scratch database once a month, because it is the only proof that the dump and the encryption key in .env still belong together.