Comment on page
Manual Installation
Content:
This documentation goes into the details on how to set-up Semaphore when using these installation methods:
The Semaphore software-package is just a part of the whole system needed to successfully run Ansible with it.
The Python3- and Ansible-Execution-Environment are also very important!
NOTE: There are existing Ansible-Galaxy Roles that handle this setup-logic for you or can be used as a base-template for your own Ansible Role!
Semaphore does not need to be run as user
root
- so you shouldn't.Benefits of using a service user:
- Has its own user-config
- Has its own environment
- Processes easily identifiable
- Gained system security
You can create a system user either manually by using
adduser
or using the ansible.builtin.user module.In this documentation we will assume:
- the service user creates is named
semaphore
- it has the shell
/bin/bash
set - its home directory is
/home/semaphore
If the Ansible execution of Semaphore is failing - you will need to troubleshoot it in the context of the service user.
You have multiple options to do so:
- Change your whole shell session to be in the user's context:sudo su --login semaphore
- Run a single command in the user's context:sudo --login -u semaphore <command>
So its clean setup is essential for Ansible to work correctly.
First - make sure the packages
python3
and python3-pip
are installed on your system!You have multiple options to install required Python modules:
- Installing them in the service user's context
Either way - it is recommended to use a
requirements.txt
file to specify the modules that need to be installed.We will assume the file
/home/semaphore/requirements.txt
is used.Here is an example of its content:
ansible
# for common jinja-filters
netaddr
jmespath
# for common modules
pywinrm
passlib
requests
docker
NOTE: You should also update those requirements from time to time!
An option for doing this automatically is also shown in the service example below.
Manually:
sudo --login -u semaphore python3 -m pip install --user --upgrade -r /home/semaphore/requirements.txt
Using Ansible:
- name: Install requirements
ansible.builtin.pip:
requirements: '/home/semaphore/requirements.txt'
extra_args: '--user --upgrade'
become_user: 'semaphore'
We will assume the virtualenv is created at
/home/semaphore/venv
Make sure the virtual environment is activated inside the Service! This is also shown in the service example below.
Manually:
sudo su --login semaphore
python3 -m pip install --user virtualenv
python3 -m vitualenv /home/semaphore/venv
# activate the context of the virtual environment
source /home/semaphore/venv/bin/activate
# verify we are using python3 from inside the venv
which python3
> /home/semaphore/venv/bin/python3
python3 -m pip install --upgrade -r /home/semaphore/requirements.txt
# disable the context to the virtual environment
deactivate
Using Ansible:
- name: Create virtual environment and install requirements into it
ansible.builtin.pip:
requirements: '/home/semaphore/requirements.txt'
virtualenv: '/home/semaphore/venv'
state: present # or 'latest' to upgrade the requirements
If you encounter Python3 issues when using a virtual environment, you will need to change into its context to troubleshoot them:
sudo su --login semaphore
source /home/semaphore/venv/bin/activate
# verify we are using python3 from inside the venv
which python3
> /home/semaphore/venv/bin/python3
# troubleshooting
deactivate
Sometimes a virtual environment also breaks on system upgrades. If this happens you might just remove the existing one and re-create it.
You might want to pre-install Ansible modules and roles, so they don't need to be installed every time a task runs!
It is recommended to use a
requirements.yml
file to specify the modules that need to be installed.We will assume the file
/home/semaphore/requirements.yml
is used.Here is an example of its content:
---
collections:
- 'namespace.collection'
# for common collections:
- 'community.general'
- 'ansible.posix'
- 'community.mysql'
- 'community.crypto'
roles:
- src: 'namespace.role'
NOTE: You should also update those requirements from time to time!
An option for doing this automatically is also shown in the service example below.
Manually:
sudo su --login semaphore
ansible-galaxy collection install --upgrade -r /home/semaphore/requirements.yml
ansible-galaxy role install --force -r /home/semaphore/requirements.yml
Manually:
sudo su --login semaphore
source /home/semaphore/venv/bin/activate
# verify we are using python3 from inside the venv
which python3
> /home/semaphore/venv/bin/python3
ansible-galaxy collection install --upgrade -r /home/semaphore/requirements.yml
ansible-galaxy role install --force -r /home/semaphore/requirements.yml
deactivate
Here is the basic template of the systemd service.
Add additional settings under their
[PART]
[Unit]
Description=Ansible Semaphore
Documentation=https://docs.ansible-semaphore.com/
Wants=network-online.target
After=network-online.target
ConditionPathExists=/usr/bin/semaphore
ConditionPathExists=/etc/semaphore/config.json
[Service]
ExecStart=/usr/bin/semaphore service --config /etc/semaphore/config.json
ExecReload=/bin/kill -HUP $MAINPID
Restart=always
RestartSec=10s
[Install]
WantedBy=multi-user.target
[Service]
User=semaphore
Group=semaphore
[Service]
# to auto-upgrade python modules at service startup
ExecStartPre=/bin/bash -c 'python3 -m pip install --upgrade --user -r /home/semaphore/requirements.txt'
# so the executables are found
Environment="PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/home/semaphore/.local/bin"
# set the correct python path. You can get the correct path with: python3 -c "import site; print(site.USER_SITE)"
Environment="PYTHONPATH=/home/semaphore/.local/lib/python3.10/site-packages"
[Service]
# to auto-upgrade python modules at service startup
ExecStartPre=/bin/bash -c 'source /home/semaphore/venv/bin/activate \
&& python3 -m pip install --upgrade -r /home/semaphore/requirements.txt'
# REPLACE THE EXISTING 'ExecStart'
ExecStart=/bin/bash -c 'source /home/semaphore/venv/bin/activate \
&& /usr/bin/semaphore service --config /etc/semaphore/config.json'
[Service]
# to auto-upgrade ansible collections and roles at service startup
ExecStartPre=/bin/bash -c 'ansible-galaxy collection install --upgrade -r /home/semaphore/requirements.yml'
ExecStartPre=/bin/bash -c 'ansible-galaxy role install --force -r /home/semaphore/requirements.yml'
# to auto-upgrade ansible collections and roles at service startup
ExecStartPre=/bin/bash -c 'source /home/semaphore/venv/bin/activate \
&& ansible-galaxy collection install --upgrade -r /home/semaphore/requirements.yml \
&& ansible-galaxy role install --force -r /home/semaphore/requirements.yml'
[Unit]
Requires=mariadb.service
[Unit]
Wants=nginx.service
[Service]
StandardOutput=journal
StandardError=journal
SyslogIdentifier=semaphore
[Unit]
Description=Ansible Semaphore
Documentation=https://docs.ansible-semaphore.com/
Wants=network-online.target
After=network-online.target
ConditionPathExists=/usr/bin/semaphore
ConditionPathExists=/etc/semaphore/config.json
[Service]
User=semaphore
Group=semaphore
Restart=always
RestartSec=10s
Environment="PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:~/.local/bin"
ExecStartPre=/bin/bash -c 'ansible-galaxy collection install --upgrade -r /home/semaphore/requirements.yml'
ExecStartPre=/bin/bash -c 'ansible-galaxy role install --force -r /home/semaphore/requirements.yml'
ExecStartPre=/bin/bash -c 'python3 -m pip install --upgrade --user -r /home/semaphore/requirements.txt'
ExecStart=/usr/bin/semaphore service --config /etc/semaphore/config.json
ExecReload=/bin/kill -HUP $MAINPID
[Install]
WantedBy=multi-user.target
[Unit]
Description=Ansible Semaphore
Documentation=https://docs.ansible-semaphore.com/
Wants=network-online.target
After=network-online.target
ConditionPathExists=/usr/bin/semaphore
ConditionPathExists=/etc/semaphore/config.json
[Service]
User=semaphore
Group=semaphore
Restart=always
RestartSec=10s
ExecStartPre=/bin/bash -c 'source /home/semaphore/venv/bin/activate \
&& python3 -m pip install --upgrade -r /home/semaphore/requirements.txt'
ExecStartPre=/bin/bash -c 'source /home/semaphore/venv/bin/activate \
&& ansible-galaxy collection install --upgrade -r /home/semaphore/requirements.yml \
&& ansible-galaxy role install --force -r /home/semaphore/requirements.yml'
ExecStart=/bin/bash -c 'source /home/semaphore/venv/bin/activate \
&& /usr/bin/semaphore service --config /etc/semaphore/config.json'
ExecReload=/bin/kill -HUP $MAINPID
[Install]
WantedBy=multi-user.target
If you have a custom system language set - you might run into problems that can be resoled by updating the associated environmental variables:
[Service]
Environment=LANG="en_US.UTF-8"
Environment=LC_ALL="en_US.UTF-8"
If there is a problem while executing a task it might be an environmental issue with your setup - not an issue with Semaphore itself!
Please go through these steps to verify if the issue occurs outside Semaphore:
- Change into the context of the user:sudo su --login semaphore
- Change into the context of the virtualenv if you use one:source /home/semaphore/venv/bin/activate# verify we are using python3 from inside the venvwhich python3> /home/semaphore/venv/bin/python3# troubleshootingdeactivate
- Run the Ansible Playbook manually
- If it fails => there is an issue with your environment
- If it works:
- Re-check your configuration inside Semaphore
- It might be an issue with Semaphore
Last modified 2mo ago