How to Install Ansible Semaphore on Debian 11

Ansible Semaphore is an open-source web UI for Ansible playbooks. It enables the deployment using Ansible automation via a web browser. Ansible Semaphore is purely written in Go, it can be run on Linux, Windows, and macOS. Ansible Semaphore allows the deployment via Ansible from an intuitive and responsive web administration dashboard. You can always roll back, restore the configuration, and manage environments, secrets, inventories, and access keys. It allows you to run playbooks by schedule with detailed logs and notifications.

Ansible Semaphore will enable secure deployment and configuration. Provides an access control that can be used for managing users and allow to run specific playbooks.

In this tutorial, you will install the Ansible Semaphore on a Debian 11 server. You will set up Ansible Semaphore with the latest version of Ansible, using the PostgreSQL server to store users' data, and also using the Nginx web server as a reverse proxy for the Ansible Semaphore web applications.

Prerequisites

To complete this tutorial, you must have the following requirements:

  • A Linux server running Debian 11 - This example uses a Debian server with the hostname 'semaphore'.
  • A non-root user with sudo/root privileges - This example uses a non-root user 'bob'.
  • A domain name pointed to a server IP address - This example uses a domain name called 'ansible.howtoforge.local'.

Installing Dependencies

First, you will install some package dependencies that will be used to install the Ansible Semaphore. You will install the latest version of Ansible, the PostgreSQL database server, and the Nginx web servers. And all of those packages are available by default on the Debian repository.

To start, type the following command to update and refresh your Debian package index.

sudo apt update

Once the package index is updated, run the following apt command to install some basic dependencies to your system. Input y when prompted and press ENTER to proceed.

sudo apt install git curl wget software-properties-common

install deps

Next, you will also need to install some package dependencies that will be used to run the Ansible Semaphore. This includes the latest version of Ansible, the PostgreSQL server, and the Nginx web server. And all of those packages are available by default on the Debian repository.

Type the following command to install Ansible, PostgreSQL, and Nginx. When prompted, input y and press ENTER.

sudo apt install ansible postgresql nginx

install ansible nginx postgresql

With Ansible, PostgreSQL, and Nginx installed, enter the following command to verify the status of both PostgreSQL and Nginx services.

sudo systemctl is-enabled postgresql
sudo systemctl status postgresql

The output below confirms that the PostgreSQL server is enabled and will start automatically upon the system's startup. Also. it's running by default after the installation is finished.

verify postgresql

Below is the command to check the Nginx service.

sudo systemctl is-enabled nginx
sudo systemctl status nginx

The output below confirms that the Nginx web server is enabled and will start automatically upon the system startup. Also. it's running by default after the installation is finished.

verify nginx

With this, you have installed package dependencies for Ansible Semaphore, which includes the latest version of Ansible, the PostgreSQL database server, and the Nginx web server.

Setting up PostgreSQL Database

By default, the Ansible Semaphore supports multiple databases such as MySQL/MariaDB, BoldDB, and the PostgreSQL server. After installing the PostgreSQL server, you will now set up the PostgreSQL database and user that will be used by Ansible Semaphore.

Log in to the PostgreSQL shell by entering the following command. Once logged in, the PostgreSQL prompt will become like 'postgres=#'.

sudo -u postgres psql

Now enter the following queries to create a new PostgreSQL database and user that will be used by Ansible Semaphore. In this example, you will create a new user called 'semaphore' and the database 'semaphoredb'. Also, be sure to change the password in this query.

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

create database and user

Next, enter the following queries to verify the list of users and databases on your PostgreSQL server. If the database is created, you should see the database called 'semaphoredb' on the database list. And as for the PostgreSQL user, you should see the user 'semaphore' on the list of users.

\du
\l

List of users on the PostgreSQL server.

list users

List of databases on the PostgreSQL server.

list database

Now that you have created the database and user for Ansible Semaphore. Now move to the section below to start the Ansible Semaphore installation.

Installing Ansible Semaphore

With package dependencies installed and the PostgreSQL database and the user created, you will next install the Ansible Semaphore package. There are multiple packages available for various Linux distributions, visit the official Ansible Semaphore GitHub page to get detailed versions.

Enter the following command to download the Debian package file for Ansible Semaphore. In this example, you will download the latest version of Ansible Semaphore from the official Ansible Semaphore GitHub page.

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

Once the Debian package file is downloaded, you should see the file 'semaphore_2.8.77_linux_amd64.deb' in your current working directory. Also, during this writing, the Ansible Semaphore's latest version is 2.8.77.

Now enter the following dpkg command to install the Ansible Semaphore Debian package file 'semaphore_${VER}_linux_amd64.deb'.

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

install semaphore

Once Ansible Semaphore is installed, the binary file called 'semaphore' will be available on the '/usr/bin' directory.

Run the following command to verify the full path of the 'semaphore' binary file.

which semaphore

Then, run the following 'semaphore' commands to verify the current version of Ansible Semaphore that is installed on your system and the help page of the 'semaphore' command.

semaphore version
semaphore help

verify semaphore

With this, the Ansible Semaphore is installed. But to get further, you can also set up a bash completion for the 'semaphore' command utility.

To do that, first, install the 'bash-completion' package to your Debian system via the apt command below.

sudo apt install bash-completion

Once the 'bash-completion' is installed, open the bash config file '~/.bashrc' using the following nano editor command.

sudo nano ~/.bashrc

Add the following configurations to the end of the line.

if [ -f /usr/share/bash-completion/bash_completion ]; then
. /usr/share/bash-completion/bash_completion
elif [ -f /etc/bash_completion ]; then
. /etc/bash_completion
fi

source <(semaphore completion bash)

Save and close the file when finished.

Next, reload the '~/.bashrc' config file and type the 'semaphore' command and press the TAB button to get the list of available options/parameters of the Ansible Semaphore command utility.

source ~/.bashrc
semaphore TAB

When auto-completion for Ansible Semaphore is configured, you should see the list of available parameters of the command like this.

semaphore auto-complete

In this section, you have installed the Ansible Semaphore package from the Debian package file. You have also configured an auto-complete for the 'semaphore' command utility. As for the next step, you will set up the Ansible Semaphore installation.

Configuring Ansible Semaphore

After installing Ansible Semaphore, you will now set up and configure your installation with the default PostgreSQL as the database server. Also, you will generate the configuration of Ansible Semaphore that will be stored in the '/etc/semaphore' directory.

First, create a new configuration directory '/etc/semaphore', and move your working directory into it. This directory will be used for storing the configuration of the Ansible Semaphore.

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

Now enter the following 'semaphore' command to set up and configure the Ansible Semaphore installation.

semaphore setup

After the command is executed, you will be asked for some configurations of Ansible Semaphore.

  • First, select number 3 to set up Ansible Semaphore with the PostgreSQL database server. Then, input details of the PostgreSQL database name, user, and password.
  • As for the Playbook path, input the new directory such as '/opt/playbook'.
  • For the rest configurations, press ENTER to leave with the default settings. You can set up it later after finishing the installation.

Picture

Next, you will also be asked to create a new admin user for Ansible Semaphore. Input your username, email address, and password. When configurations are finished, yous should receive an output similar to this. Also, you will see the generated Ansible Semaphore config file '/etc/semaphore/config.json'.

configure semaphore

With this, you have now configured the Ansible Semaphore installation with the PostgreSQL database server and also configured the admin user and password for Ansible Semaphore. In addition to that, you have also configured the default Playbookj path directory to '/opt/semaphore'.

You're now ready to start the Ansible Semaphore. For the next step, you will set up and run Ansible Semaphore via Systemd.

Running Ansible Semaphore with Systemd

In this section, you will create a new systemd unit file that will be used for managing the Ansible Semaphore p[rocess. This allows you easily to manage Ansible Semaphore via the systemctl command utility.

Create a new systemd unit file '/etc/systemd/system/semaphore.service' using the following nano editor command.

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

Add the following lines to the file.

[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 when finished.

Now enter the following command to reload the systemd manager and apply the new systemd unit file. With this, you can now start the Ansible Semaphore service via the systemctl command.

sudo systemctl daemon-reload

Type the following 'systemctl' command to start and enable the 'semaphore' service. And it's running by default on the TCP port '3000'.

sudo systemctl start semaphore
sudo systemctl enable semaphore

semaphore systemd

Then, verify the 'semaphore' service to ensure that the service is running and enabled.

sudo systemctl status semaphore

An output 'enabled' confirms that the Ansible Semaphore will be run automatically at system startup. And the status of Ansible Semaphore is running.

verify ansible semaphore

Lastly, you can also access the Ansible Semaphore from your web browser. Open the web browser and visit the server IP address followed by the default port 3000 (i.e: http://192.168.5.10:3000/). When Ansible Semaphore is running, you should see the login page of the Ansible Semaphore web application.

semaphore login

Now that the Ansible Semaphore is running in the background as a systemd service and it's running on the default port 3000. As for the next step, you will set up Nginx as a reverse proxy for Ansible Semaphore.

Running Ansible Semaphore with Nginx Reverse Proxy

At this point, you have finished the Ansible Semaphore installation and it's now running on default port 3000. In this section, you will set up the Nginx as a reverse proxy for the Ansible Semaphore. So before you start, ensure that you have the domain name for your installation.

Create a new Nginx server block file '/etc/nginx/sites-available/semaphore.conf' using the following nano editor command.

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

Add the following lines to the file and be sure to change the 'server_name' parameter with your domain name.

upstream semaphore {
    server 127.0.0.1:3000;
  }

server {
    listen 80;
    server_name ansible.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 and close the file when finished.

Next, enter the following command to activate the server block configuration 'semaphore.conf'. Then, verify Nginx configurations to ensure that you have proper and correct configuration files. When the operation is successful, you should see an output such as 'syntax is ok - test is successful'.

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

Lastly, restart the Nginx service to apply the changes. Now the Ansible Semaphore installation is accessible from your domain name.

sudo systemctl restart nginx

setup nginx semaphore

Setting up UFW

In this example, you will install and enable the firewall on your Debian system via UFW. You will be using UFW to open the SSH, HTTP, and HTTPS services.

First, install the UFW package via the apt command below. Input and press ENTER to proceed.

sudo apt install ufw

install ufw

Next, run the following command to add the OpenSSH and 'Nginx Full' applications to the UFW. The OpenSSH application will open the default SSH port 22 and the 'Nginx Full' application will open both HTTP and HTTPS ports.

sudo ufw allow OpenSSH
sudo ufw allow "Nginx Full"

Now run the following command to start and enable UFW. Input y and press ENTER to confirm.

sudo ufw enable

enable ufw

Lastly, verify the status of UFW using the below command. You should see the UFW with the 'Status: Active'; both OpenSSH and 'Nginx Full' applications are added and available on the rule list.

sudo ufw status

ufw status

Securing Ansible Semaphore with Letsencrypt

After configuring UFW, you will now set up and secure Ansible Semaphore with SSL/TLS certificates via Certbot and Letsencrypt. You will install Certbot with the Certbot-Nginx plugin, then you will generate SSL/TLS certificates from letsencrypt.

Enter the following command to install the Certbot and Certbot-Nginx plugin. When prompted, input y to confirm and press ENTER to proceed.

sudo apt install certbot python3-certbot-nginx

install certbot

Once Certbot is installed, run the following command to generate SSL certificates for your domain name and secure the Ansible Semaphore installation. Be sure to change the email address and the domain name in this command.

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

When the process is finished, your SSL/TLS certificates will be generated at the '/etc/letsencrypt/live/yourdomain.com/' directory. Also, the Ansible Semaphore is now accessible via a secure HTTPS connection and will automatically redirect any HTTP requests to the secure HTTPS connection.

Now open your web browser and visit the domain name of your Ansible Semaphore installation (i.e: https://ansible.howtoforge.local/auth/login). When you have proper Nginx configurations and the SSL Letsencrypt is working, you should see the Ansible Semaphore login page.

Input your admin user and password for Ansible Semaphore, then click SIGN IN to confirm.

login semaphore

When successful, you will be asked to create the first project for your installation. Input the project name, then click CREATE.

create first project

After the first project is created, you should see the administration dashboard of Ansible Semaphore.

semaphore dashboard

Conclusion

Throughout this tutorial, you have installed and configured Ansible Semaphore on Debian 11 server with PostgreSQL as the database server and Nginx as a reverse proxy for the Ansible Semaphore. You have learned the basic usage of PostgreSQL for creating a database and user and the basic configuration of the Nginx server block for the reverse proxy.

In addition to that, you have also secured the Ansible Semaphore installation via UFW and SSL/TLS certificates generated from Letsencrypt.

With this in mind, you can now integrate your Ansible playbook into Ansible Semaphore via the web administration dashboard. You can also set up multiple notification systems via Email, Slack, and many more. To get details information, visit the official documentation of the Ansible Semaphore application.

Share this page:

0 Comment(s)