Install Semaphore on Debian like Linux

Semaphore is the web GUI for ansible.

This instructions will install Semaphore v2.6.8 on Ubuntu 20.04 Linux with MySQL 8

Install the list of required packages if not already installed

$ sudo apt-get update
$ sudo apt-get install wget gnupg git curl

Install the MySQL database service if not already installed

$ sudo apt-get install mysql-server mysql-client
$ mysql -u root -p
mysql> CREATE DATABASE semaphore CHARACTER SET utf8 collate utf8_bin;

NOTE: Create database named as semaphore(optional). If no such data base is created the semaphore -setup application will create the database by itself.The database name must match the "DB Name" during setup process.

Create user and set a Password for the MySQL user.

This user will be used by Semphore applicatiotn to connect to the database The password must match the "DB Password" during the setup.

mysql> CREATE USER 'semaphore'@'%' IDENTIFIED WITH mysql_native_password BY 'yourdbpasswd';

NOTE: If the MySQL version is 8+ must use use "mysql_native_password" explicitly. For MySQL 8 the default authentication is caching_sha2_password in MySQL 8. Check the "Trouble Shooting" section

Now grant all privileges of semaphore.* to user 'semaphore'@'%'

mysql> GRANT ALL PRIVILEGES ON semaphore.* TO 'semaphore'@'%';
mysql> QUIT;

If the user wants to change the database user password, run this command.

mysql> ALTER USER 'semaphore'@'%' IDENTIFIED WITH mysql_native_password BY 'newpasswd';
mysql> EXIT;

Install Semaphore

NOTE Here semaphore_2.6.8_linux_amd64.deb is just an example. Please choose the one you need.

$ mkdir ~/install/semaphore
$ cd ~/install/semaphore
$ wget https://github.com/ansible-semaphore/semaphore/releases/download/v2.6.8/semaphore_2.6.8_linux_amd64.deb
$ sudo dpkg -i semaphore_2.6.8_linux_amd64.deb

Start the Ansible Semaphore setup process.

$ sudo semaphore -setup


 Hello! You will now be guided through a setup to:

 1. Set up configuration for a MySQL/MariaDB database
 2. Set up a path for your playbooks (auto-created)
 3. Run database Migrations
 4. Set up initial semaphore user & password

 > DB Hostname (default 127.0.0.1:3306): 127.0.0.1:3306
 > DB User (default root): semaphore
 > DB Password: yourdbpasswd
 > DB Name (default semaphore): semaphore
 > Playbook path (default /tmp/semaphore): /opt/semaphore
 > **Web root URL (optional, example http://localhost:8010/):**
 > WARN[0065] An input error occured:unexpected newline
 > Enable email alerts (y/n, default n): n
 > Enable telegram alerts (y/n, default n): n
 > Enable LDAP authentication (y/n, default n): n

 Generated configuration:
 {
        "mysql": {
                "host": "127.0.0.1:3306",
                "user": "semaphore",
                "pass": "yourdbpasswd",
                "name": "semaphore"
        },
        "port": "",
        "interface": "",
        "tmp_path": "/opt/semaphore",
        "cookie_hash": "64AS4uNWiT7X5n7wSo5vqGYL/D0UEUgjjX36bF9LPOg=",
        "cookie_encryption": "JhKbJF79d0okR5Lky6SFYpIdaGP7KnRuKfOvK9rCa+M=",
        "email_sender": "",
        "email_host": "",
        "email_port": "",
        "web_host": "",
        "ldap_binddn": "",
        "ldap_bindpassword": "",
        "ldap_server": "",
        "ldap_searchdn": "",
        "ldap_searchfilter": "",
        "ldap_mappings": {
                "dn": "",
                "mail": "",
                "uid": "",
                "cn": ""
        },
        "telegram_chat": "",
        "telegram_token": "",
        "concurrency_mode": "",
        "max_parallel_tasks": 0,
        "email_alert": false,
        "telegram_alert": false,
        "ldap_enable": false,
        "ldap_needtls": false,
        "old_frontend": false
 }

 > Is this correct? (yes/no): yes
 > Config output directory (default /opt/semaphore): /opt/semaphore
 >  Running: mkdir -p /opt/semaphore..
 >  Configuration written to /opt/semaphore/config.json..
 >  Pinging db..

 Running DB Migrations..
Checking DB migrations


 > Username: Admin
 > Email: youremail@something.com

 Welcome back, Semaphore Admin! (a user with this username/email is already set up..)

 Re-launch this program pointing to the configuration file

./semaphore -config /opt/semaphore/config.json

 To run as daemon:

nohup ./semaphore -config /opt/semaphore/config.json &

You can login with youremail@something.com or admin.

Run Semaphore application and access it from a browser

$ sudo semaphore -config /opt/semaphore/config.json

In the browser input http://semaphoresrv:3000/ to access the Semaphore.

User: Admin Password: semaphore

Run Semaphore as Service

$ sudo vim /etc/systemd/system/semaphore.service
$ cat /etc/systemd/system/semaphore.service
[Unit]
Description=Semaphore Ansible UI
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 -config /etc/semaphore/config.json
SyslogIdentifier=semaphore
Restart=always

[Install]
WantedBy=multi-user.target


$ sudo mkdir /etc/semaphore
$ sudo ln -s /opt/semaphore/config.json /etc/semaphore/config.json
$ sudo systemctl daemon-reload
$ sudo systemctl start semaphore
$ sudo systemctl status semaphore
# To make it auto start
$ sudo systemctl enable semaphore.service

Troubleshooting

How to check and resolve default authentication error in MySQL 8?

If we create the user without mysql_native_password we will got error below

mysql> CREATE USER 'semaphore'@'%' IDENTIFIED BY 'yourdbpasswd';
        ERROR when start semaphore:
        loginuser@semaphoresrv:~$ semaphore -config path/to/config.json
        Using config file: install/semaphore/config.json
        Semaphore v2.6.8
        Interface
        Port :3000
        MySQL semaphore@127.0.0.1:3306 semaphore
        Tmp Path (projects home) /home/loginuser/install/semaphore/playbook

         Have you run semaphore -setup?
        panic: this authentication plugin is not supported
    
        goroutine 1 [running]:
        main.main()
                        /go/src/github.com/ansible-semaphore/semaphore/cli/main.go:55 +0x845

We can check the default authentication-plugin for the user will command below.

        $ sudo mysql -uroot -p
        Enter password:
        Welcome to the MySQL monitor.  Commands end with ; or \g.
        Your MySQL connection id is 20772
        Server version: 8.0.23-0ubuntu0.20.04.1 (Ubuntu)

        Copyright (c) 2000, 2021, Oracle and/or its affiliates.
    
        Oracle is a registered trademark of Oracle Corporation and/or its
        affiliates. Other names may be trademarks of their respective
        owners.
    
        Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.
    
        mysql> use mysql
        Reading table information for completion of table and column names
        You can turn off this feature to get a quicker startup with -A
    
        Database changed
        mysql> select user, plugin from user;
        +------------------+-----------------------+
        | user             | plugin                |
        +------------------+-----------------------+
        | semaphore        | caching_sha2_password |
        | debian-sys-maint | caching_sha2_password |
        | mysql.infoschema | caching_sha2_password |
        | mysql.session    | caching_sha2_password |
        | mysql.sys        | caching_sha2_password |
        | root             | auth_socket           |
        | zabbix           | caching_sha2_password |
        +------------------+-----------------------+
        7 rows in set (0.01 sec)

As we can see the user semaphore authentication plugin is caching_sha2_password which is not supported by Semaphore v2.6.8

        ERROR when start semaphore:
        loginuser@semaphoresrv:~$ semaphore -config /opt/semaphore/config.json
        ...
         Have you run semaphore -setup?
        panic: this user requires mysql native password authentication.
        ...

How to resolve it?

We need to change the plugin to mysql_native_password by ALTER USER

mysql> ALTER USER 'semaphore'@'%' IDENTIFIED WITH mysql_native_password BY 'yourdbpasswd';

Try again, we can see it still not wor! If the MySQL 8.0 is used must update the mysqld.cnf to set the default authentication to mysql_native_password.

$ vim /etc/mysql/mysql.conf.d/mysqld.cnf
Add one line to set the default authentication to mysql_native_password.



    [mysqld]
    
    ...
    default-authentication-plugin=mysql_native_password
    ...
    

After restart the mysql service. It solves the issue. You need to redo the command below to complete the setup.

$ sudo semaphore -setup

The reason is that db connection error happens in the middle during setup, the setup is not completed yet.

After the setup success, we try to access the web portal we may still fail!

Check below to resolve it.

How to check and resolve the web portal not accessible issue?

The short answer update the config.json and left the web_host be blank.

"web_host":"",

Check the discussion, https://github.com/ansible-semaphore/semaphore/issues/426.

Try to get the Web page with curl and check what's wrong.

loginuser@semaphoresrv:/usr/bin$ curl http://localhost:3000
<!DOCTYPE html>
<html lang="en">
  <head>
    <base href="http://localhost:8010/">
    <meta charset="utf-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width,initial-scale=1.0">
    <link rel="icon" href="favicon.png">
    <title>Ansible Semaphore</title>
  <link href="/css/app.732af4fa.css" rel="preload" as="style"><link href="/css/chunk-vendors.0dc8d6a6.css" rel="preload" as="style"><link href="/js/app.7302c47a.js" rel="preload" as="script"><link href="/js/chunk-vendors.55b0185f.js" rel="preload" as="script"><link href="/css/chunk-vendors.0dc8d6a6.css" rel="stylesheet"><link href="/css/app.732af4fa.css" rel="stylesheet"></head>
  <body>
    <noscript>
      <strong>
          We're sorry but web2 doesn't work properly
          without JavaScript enabled. Please enable it to continue.
      </strong>
    </noscript>
    <div id="app"></div>
    <!-- built files will be auto injected -->
  <script type="text/javascript" src="/js/chunk-vendors.55b0185f.js"></script><script type="text/javascript" src="/js/app.7302c47a.js"></script></body>
</html>

The reason is that the base url is used But, there is no

    http://localhost:8010/css/app.732af4fa.css
    http://localhost:8010/css/js/app.7302c47a.js
    etc. on the server.

After we set it as blank, the web GUI works as expected.