How to Install Ansible Semaphore on Debian 12

This tutorial exists for these OS versions

Debian 12 (Bookworm)
Debian 11 (Bullseye)

Ansible Semaphore allows deployment via Ansible from an intuitive and responsive web administration dashboard. You can always roll back and restore the configuration and manage environments, secrets, inventories, and access keys. It also allows you to run playbooks by schedule with detailed logs and notifications.

In this guide, we’ll walk you through the installation of Ansible Semaphore on the Debian 12 server. You’ll install Semaphore with PostgreSQL as a database and Nginx as a reverse proxy.

Prerequisites

To get started with this guide, make sure you have the following:

A Debian 12 server.
A non-root user with administrator privileges.

Installing dependencies

To install Ansible Semaphore, you must install dependencies such as Ansible, PostgreSQL, and Nginx on your system. You’ll be using PostgreSQL as the database and Nginx as a reverse proxy.

First, run the command below to update your Debian package index and install dependencies, such as the ansible, postgresql database, and nginx web server.

sudo apt update
sudo apt install git curl wget software-properties-common ansible postgresql nginx

Input Y to confirm with the installation.

After the installation is complete, check the postgresql service with the command below.

sudo systemctl is-enabled postgresql
sudo systemctl status postgresql

You’ll see the postgresql service is running.

Now check the nginx service status with the following:

sudo systemctl is-enabled nginx
sudo systemctl status nginx

In the following, you can see the nginx web server is running.

Lastly, check the ansible version using the command below. The Ansible 2.14 should be installed on your Debian system.

ansible --version

Setting up database

Now that you’ve installed dependencies, you’ll configure PostgreSQL and create a new database and user that Ansible Semaphore will use.

sudo -u postgres psql

Now run the queries below to create a new database semaphoredb and user semaphore. Adjust the password with your information.

CREATE USER semaphore WITH PASSWORD 'passw0rd';
CREATE DATABASE semaphoredb OWNER semaphore;

Next, run the following queries to verify the list of databases and users in PostgreSQL. You’ll see a new user semaphore and database semaphoredb are available.

\du
\l

Lastly, type quit to exit from the PostgreSQL.

Installing Ansible Semaphore

Ansible Semaphore provides packages for different Linux distributions, including Debian/Ubuntu. You can download the DEB file of Ansible Semaphore and install it with the dpkg command.

Download the Ansible Semaphore debian package with the following command:

VER=$(curl -s https://api.github.com/repos/semaphoreui/semaphore/releases/latest|grep tag_name | cut -d '"' -f 4|sed 's/v//g')
wget -q https://github.com/semaphoreui/semaphore/releases/download/v${VER}/semaphore_${VER}_linux_amd64.deb

Once downloaded, install Ansible Semaphore with the dpkg command below:

sudo dpkg -i semaphore_${VER}_linux_amd64.deb

Below you can see the installation is complete.

Now run the command below to locate the semaphore binary, and should be available at /usr/bin/semaphore.

which semaphore

Check the Ansible Semaphore version with the following command. You’ll see Ansible Semaphore 2.9 is installed.

semaphore version
semaphore help

Configuring Ansible Semaphore

In this section, you’ll configure the Ansible Semaphore installation directory, integrate Semaphore with PostgreSQL, and then set up the admin user and password for Semaphore. After that, you’ll also run Semaphore in the background as a systemd service.

Create a new configuration directory /etc/semaphore and go into it. And then, run the semaphore setup command to configure Ansible Semaphore.

mkdir -p /etc/semaphore; cd /etc/semaphore semaphore setup

Input 3 to use PostgreSQL as the database.
Input /opt/playbook to set up the default playbook directory.
Press ENTER and leave the public URL as default.
Press ENTER to use default notification settings.
Enter your admin username, password, and email address. This will be used to log in to the Ansible Semaphore web application.

After the process is complete, you’ll see the confirmation below:

Now that you’ve configured Ansible Semaphore, you’ll create a new systemd service and run Ansible Semaphore in the background.

Create a new systemd service file /etc/systemd/system/semaphore.service with the nano editor.

sudo nano /etc/systemd/system/semaphore.service

Insert the configuration below.

[Unit]
Description=Semaphore Ansible
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 service --config=/etc/semaphore/config.json
SyslogIdentifier=semaphore
Restart=always

[Install]
WantedBy=multi-user.target

Save the file and exit the editor.

Next, run the systemctl command below to reload the systemd manager and apply your changes.

sudo systemctl daemon-reload

Lastly, run the command below to start and enable the semaphore service. And then, check the service to ensure it is running.

sudo systemctl enable --now semaphore
sudo systemctl status semaphore

You can see below, the semaphore service is running. And by default, it is running on port 3000.

Setting up Nginx as a reverse proxy

Now that Semaphore is running, you’ll set up Nginx as a reverse for your Semaphore installation. Make sure you have the domain name ready (local or public domain name).

Create a new server block configuration /etc/nginx/sites-available/semaphore.conf with the nano editor.

sudo nano /etc/nginx/sites-available/semaphore.conf

Insert the following configuration to set up Nginx as a reverse proxy for Ansible Semaphore that running on port 3000. Make sure to change the server_name option with your domain name.

upstream semaphore {
    server 127.0.0.1:3000;
  }

server {
    listen 80;
    server_name auto.howtoforge.local;
      client_max_body_size 0;
      chunked_transfer_encoding on;

    location / {
      proxy_pass http://semaphore/;
      proxy_set_header Host $http_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 "";
    }
}

Save the file and exit the editor when done.

Now run the command below to activate the server block file semaphore.conf and verify your Nginx syntax. If you’ve correct syntax, you’ll see an output test is successful - syntax is ok.

sudo ln -s /etc/nginx/sites-available/semaphore.conf /etc/nginx/sites-enabled/
sudo nginx -t

Lastly, run the following systemctl command below to restart Nginx and apply your changes.

sudo systemctl restart nginx

Securing Ansible Semaphore with HTTPS

To secure Ansible Semaphore installation, you’ll enable HTTPS on top of the Nginx reverse proxy. You’ll be using Certbot for generating and configuring HTTPS for Semaphore.

Install certbot and python3-certbot-nginx packages with the following command:

sudo apt install certbot python3-certbot-nginx -y

After the installation is complete, run the certbot command below to generate SSL/TLS certificates for your Ansible Semaphore installation. Make sure to change the domain and email address with your information.

sudo certbot --nginx --agree-tos --no-eff-email --redirect --email [email protected] -d auto.howtoforge.local

Once the process is complete, your SSL certificates will be available at the /etc/letsencrypt/live/domain.com directory and your Semaphore installation will be secured with HTTPS.

Loggin into Ansible Semaphore

Visit your Semaphore domain name, which is https://auto.howtoforge.local/. If your installation is successful, you’ll see the Ansible Semaphore login page.

Enter your admin user and password, and then click SIGN IN to confirm.

Now enter the name of your first project and click Next to continue.

You’ll see the Semaphore dashboard like the following:

Conclusion

Congratulations! You’ve completed the installation of Ansible Semaphore on the Debian 12 server. You’ve installed Semaphore with the PostgreSQL server and the Nginx web server. You also secure Semaphore with HTTPS through certbot and Letsencrypt.