Aller au contenu principal

Installation manuelle de Semaphore

Sommaire :

Cette documentation détaille la configuration de Semaphore lorsque vous utilisez les méthodes d'installation suivantes :

Le paquet logiciel Semaphore n'est qu'une partie de l'ensemble du système nécessaire pour exécuter Ansible avec succès.

L'environnement d'exécution Python3 et Ansible est tout aussi important !

REMARQUE : il existe des rôles Ansible Galaxy qui gèrent cette logique de configuration pour vous, ou qui peuvent servir de modèle de base pour votre propre rôle Ansible !

Utilisateur de service​

Semaphore n'a pas besoin d'être exécuté en tant qu'utilisateur root ; vous ne devriez donc pas le faire.

Avantages d'un utilisateur de service :

  • Il dispose de sa propre configuration utilisateur
  • Il dispose de son propre environnement
  • Ses processus sont facilement identifiables
  • Sécurité du système renforcée

Vous pouvez créer un utilisateur système soit manuellement avec adduser, soit avec le module ansible.builtin.user.

Dans cette documentation, nous supposerons que :

  • l'utilisateur de service créé s'appelle semaphore
  • son shell est /bin/bash
  • son répertoire personnel est /home/semaphore

Dépannage​

Si l'exécution d'Ansible par Semaphore échoue, vous devrez effectuer le dépannage dans le contexte de l'utilisateur de service.

Vous disposez de plusieurs options pour cela :

  • Basculer l'ensemble de votre session shell dans le contexte de l'utilisateur :

    sudo su --login semaphore

  • Exécuter une seule commande dans le contexte de l'utilisateur :

    sudo --login -u semaphore <command>

Python3​

Ansible est développé avec le langage de programmation Python3.

Une installation propre de celui-ci est donc essentielle au bon fonctionnement d'Ansible.

Tout d'abord, assurez-vous que les paquets python3 et python3-pip sont installés sur votre système !

Vous disposez de plusieurs options pour installer les modules Python requis :

  • Les installer dans le contexte de l'utilisateur de service
  • Les installer dans un environnement virtuel dédié au service

Prérequis​

Dans les deux cas, il est recommandé d'utiliser un fichier requirements.txt pour spécifier les modules à installer.

Nous supposerons que le fichier /home/semaphore/requirements.txt est utilisé.

Voici un exemple de son contenu :

ansible
# for common jinja-filters
netaddr
jmespath
# for common modules
pywinrm
passlib
requests
docker

REMARQUE : vous devriez également mettre à jour ces dépendances de temps en temps !

Une option pour le faire automatiquement est également présentée dans l'exemple de service ci-dessous.

Modules dans le contexte utilisateur​

Manuellement :

sudo --login -u semaphore python3 -m pip install --user --upgrade -r /home/semaphore/requirements.txt

Avec Ansible :

- name: Install requirements
  ansible.builtin.pip:
    requirements: '/home/semaphore/requirements.txt'
    extra_args: '--user --upgrade'
  become_user: 'semaphore'

Modules dans un virtualenv​

Nous supposerons que le virtualenv est créé dans /home/semaphore/venv

Assurez-vous que l'environnement virtuel est activé dans le service ! Cela est également illustré dans l'exemple de service ci-dessous.

Manuellement :

sudo su --login semaphore
python3 -m pip install --user virtualenv
python3 -m venv /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

Avec 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

Dépannage​

Si vous rencontrez des problèmes avec Python3 en utilisant un environnement virtuel, vous devrez basculer dans son contexte pour les diagnostiquer :

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

Il arrive aussi qu'un environnement virtuel soit cassé par une mise à niveau du système. Dans ce cas, il suffit généralement de supprimer l'environnement existant et de le recréer.

Collections et rôles Ansible​

Vous pouvez préinstaller les modules et rôles Ansible afin qu'ils n'aient pas à être installés à chaque exécution d'une tâche !

Prérequis​

Il est recommandé d'utiliser un fichier requirements.yml pour spécifier les modules à installer.

Nous supposerons que le fichier /home/semaphore/requirements.yml est utilisé.

Voici un exemple de son contenu :

---

collections:
  - 'namespace.collection'
  # for common collections:
  - 'community.general'
  - 'ansible.posix'
  - 'community.mysql'
  - 'community.crypto'

roles:
  - src: 'namespace.role'

Voir aussi : Installation de collections, Installation de rôles

REMARQUE : vous devriez également mettre à jour ces dépendances de temps en temps !

Une option pour le faire automatiquement est également présentée dans l'exemple de service ci-dessous.

Installation dans le contexte utilisateur​

Manuellement :

sudo su --login semaphore
ansible-galaxy collection install --upgrade -r /home/semaphore/requirements.yml
ansible-galaxy role install --force -r /home/semaphore/requirements.yml

Installation avec un virtualenv​

Manuellement :

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

Proxy inverse​

Voir : Sécurité - Connexion chiffrée

Service Systemd étendu​

Voici le modèle de base du service systemd.

Ajoutez les paramètres supplémentaires sous leur section [PART] respective

Base​

[Unit]
Description=Semaphore UI
Documentation=https://semaphoreui.com/docs
Wants=network-online.target
After=network-online.target
ConditionPathExists=/usr/bin/semaphore
ConditionPathExists=/etc/semaphore/config.json

[Service]
ExecStart=/usr/bin/semaphore server --config /etc/semaphore/config.json
ExecReload=/bin/kill -HUP $MAINPID
Restart=always
RestartSec=10s

[Install]
WantedBy=multi-user.target

Utilisateur de service​

[Service]
User=semaphore
Group=semaphore

Modules Python​

Dans le contexte utilisateur​

[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"

Dans un virtualenv​

[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 server --config /etc/semaphore/config.json'

Collections et rôles Ansible​

Si Python3 est utilisé dans le contexte utilisateur​

[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'

Si Python3 est utilisé dans un virtualenv​

# 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'

Autres cas d'utilisation​

Utilisation d'un MariaDB local​

[Unit]
Requires=mariadb.service

Utilisation d'un Nginx local​

[Unit]
Wants=nginx.service

Envoi des journaux vers syslog​

[Service]
StandardOutput=journal
StandardError=journal
SyslogIdentifier=semaphore

Exemples complets​

Modules Python dans le contexte utilisateur​

[Unit]
Description=Semaphore UI
Documentation=https://semaphoreui.com/docs
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 server --config /etc/semaphore/config.json
ExecReload=/bin/kill -HUP $MAINPID

[Install]
WantedBy=multi-user.target

Modules Python dans un virtualenv​

[Unit]
Description=Semaphore UI
Documentation=https://semaphoreui.com/docs
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 server --config /etc/semaphore/config.json'
ExecReload=/bin/kill -HUP $MAINPID

[Install]
WantedBy=multi-user.target

Correctifs​

Si une langue système personnalisée est définie, vous pourriez rencontrer des problèmes qui peuvent être résolus en mettant à jour les variables d'environnement associées :

[Service]
Environment=LANG="en_US.UTF-8"
Environment=LC_ALL="en_US.UTF-8"

Dépannage​

Si un problème survient lors de l'exécution d'une tâche, il peut s'agir d'un problème d'environnement lié à votre installation, et non d'un problème de Semaphore lui-même !

Veuillez suivre ces étapes pour vérifier si le problème se produit en dehors de Semaphore :

  • Basculez dans le contexte de l'utilisateur :

    sudo su --login semaphore

  • Basculez dans le contexte du virtualenv si vous en utilisez un :

    source /home/semaphore/venv/bin/activate
    # verify we are using python3 from inside the venv
    which python3
    > /home/semaphore/venv/bin/python3

    # troubleshooting

    deactivate

  • Exécutez le playbook Ansible manuellement

    • S'il échoue => il y a un problème avec votre environnement
    • S'il fonctionne :
      • Revérifiez votre configuration dans Semaphore
      • Il peut s'agir d'un problème de Semaphore