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:
sudosu--loginsemaphorepython3-mpipinstall--uservirtualenvpython3-mvitualenv/home/semaphore/venv# activate the context of the virtual environmentsource/home/semaphore/venv/bin/activate# verify we are using python3 from inside the venvwhichpython3> /home/semaphore/venv/bin/python3python3-mpipinstall--upgrade-r/home/semaphore/requirements.txt# disable the context to the virtual environmentdeactivate
Using Ansible:
- name:Create virtual environment and install requirements into itansible.builtin.pip:requirements:'/home/semaphore/requirements.txt'virtualenv:'/home/semaphore/venv'state:present# or 'latest' to upgrade the requirements
Troubleshooting
If you encounter Python3 issues when using a virtual environment, you will need to change into its context to troubleshoot them:
sudosu--loginsemaphoresource/home/semaphore/venv/bin/activate# verify we are using python3 from inside the venvwhichpython3> /home/semaphore/venv/bin/python3# troubleshootingdeactivate
Sometimes a virtual environment also breaks on system upgrades. If this happens you might just remove the existing one and re-create it.
Ansible Collections & Roles
You might want to pre-install Ansible modules and roles, so they don't need to be installed every time a task runs!
Requirements
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'
sudosu--loginsemaphoresource/home/semaphore/venv/bin/activate# verify we are using python3 from inside the venvwhichpython3> /home/semaphore/venv/bin/python3ansible-galaxycollectioninstall--upgrade-r/home/semaphore/requirements.ymlansible-galaxyroleinstall--force-r/home/semaphore/requirements.ymldeactivate
Here is the basic template of the systemd service.
Add additional settings under their [PART]
Base
[Unit]Description=Ansible SemaphoreDocumentation=https://docs.ansible-semaphore.com/Wants=network-online.targetAfter=network-online.targetConditionPathExists=/usr/bin/semaphoreConditionPathExists=/etc/semaphore/config.json[Service]ExecStart=/usr/bin/semaphore server --config /etc/semaphore/config.jsonExecReload=/bin/kill -HUP $MAINPIDRestart=alwaysRestartSec=10s[Install]WantedBy=multi-user.target
Service user
[Service]User=semaphoreGroup=semaphore
Python Modules
In user-context
[Service]# to auto-upgrade python modules at service startupExecStartPre=/bin/bash -c 'python3 -m pip install --upgrade --user -r /home/semaphore/requirements.txt'# so the executables are foundEnvironment="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"
In virtualenv
[Service]# to auto-upgrade python modules at service startupExecStartPre=/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 server --config /etc/semaphore/config.json'
Ansible Collections & Roles
If using Python3 in user-context
[Service]# to auto-upgrade ansible collections and roles at service startupExecStartPre=/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'
If using Python3 in virtualenv
# to auto-upgrade ansible collections and roles at service startupExecStartPre=/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'
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:
sudosu--loginsemaphore
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