Semaphore の手動インストール

目次:

このドキュメントでは、次のインストール方法を使用する場合の Semaphore のセットアップ方法を詳しく説明します。

Semaphore のソフトウェアパッケージは、Ansible を正常に実行するために必要なシステム全体の一部にすぎません。

Python3 と Ansible の実行環境も非常に重要です!

注: このセットアップロジックを代わりに処理してくれる、または独自の Ansible ロールのベーステンプレートとして使用できる Ansible Galaxy ロールが既に存在します!

サービスユーザー

Semaphore を root ユーザーとして実行する必要はありません。そのため、root で実行すべきではありません。

サービスユーザーを使用する メリット:

独自のユーザー設定を持つ
独自の環境を持つ
プロセスを簡単に識別できる
システムのセキュリティが向上する

システムユーザーは、adduser を使用して手動で作成することも、ansible.builtin.user モジュールを使用して作成することもできます。

このドキュメントでは、次のことを前提とします。

作成するサービスユーザーの名前は semaphore
シェルとして /bin/bash が設定されている
ホームディレクトリは /home/semaphore

トラブルシューティング

Semaphore による Ansible の実行が失敗する場合は、サービスユーザーのコンテキストでトラブルシューティングを行う必要があります。

これには複数の方法があります。

シェルセッション全体をそのユーザーのコンテキストに切り替える:
```
sudo su --login semaphore
```
そのユーザーのコンテキストで単一のコマンドを実行する:
```
sudo --login -u semaphore <command>
```

Python3

Ansible は Python3 プログラミング言語で構築されています。

そのため、Ansible が正しく動作するには Python3 が正しくセットアップされていることが不可欠です。

まず、python3 と python3-pip パッケージがシステムにインストールされていることを確認してください!

必要な Python モジュールをインストールするには複数の方法があります。

サービスユーザーのコンテキストにインストールする
サービス専用の仮想環境にインストールする

Requirements

どちらの方法でも、インストールが必要なモジュールを requirements.txt ファイルで指定することをおすすめします。

ここでは /home/semaphore/requirements.txt ファイルを使用することを前提とします。

内容の例を次に示します。

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

注: これらの requirements も定期的に更新してください!

これを自動で行う方法は、後述のサービスの例でも示しています。

ユーザーコンテキストのモジュール

手動:

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

Ansible を使用:

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

virtualenv 内のモジュール

ここでは virtualenv が /home/semaphore/venv に作成されていることを前提とします。

サービス内で仮想環境が有効化されていることを確認してください! これも後述のサービスの例で示しています。

手動:

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

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

トラブルシューティング

仮想環境の使用中に Python3 の問題が発生した場合は、そのコンテキストに切り替えてトラブルシューティングを行う必要があります。

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

システムのアップグレードによって仮想環境が壊れることもあります。その場合は、既存の仮想環境を削除して再作成するだけで済むことがあります。

Ansible コレクションとロール

タスクを実行するたびにインストールする必要がないよう、Ansible のモジュールとロールを事前にインストールしておくとよいでしょう!

Requirements

インストールが必要なモジュールを requirements.yml ファイルで指定することをおすすめします。

ここでは /home/semaphore/requirements.yml ファイルを使用することを前提とします。

内容の例を次に示します。

---

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

roles:
  - src: 'namespace.role'

関連項目: コレクションのインストール、ロールのインストール

注: これらの requirements も定期的に更新してください!

これを自動で行う方法は、後述のサービスの例でも示しています。

ユーザーコンテキストへのインストール

手動:

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

virtualenv 使用時のインストール

手動:

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

リバースプロキシ

参照: セキュリティ - 暗号化された接続

Systemd サービスの詳細

systemd サービスの基本テンプレートを次に示します。

追加の設定は、それぞれの [PART] の下に追加してください

ベース

[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

サービスユーザー

[Service]
User=semaphore
Group=semaphore

Python モジュール

ユーザーコンテキストの場合

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

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'

Ansible コレクションとロール

ユーザーコンテキストの Python3 を使用する場合

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

virtualenv の Python3 を使用する場合

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

その他のユースケース

ローカルの MariaDB を使用する場合

[Unit]
Requires=mariadb.service

ローカルの Nginx を使用する場合

[Unit]
Wants=nginx.service

ログを syslog に送信する場合

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

完全な例

ユーザーコンテキストの Python モジュール

[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

virtualenv の Python モジュール

[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

修正

システムにカスタムの言語設定をしている場合、問題が発生することがあります。これは関連する環境変数を更新することで解決できます。

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

トラブルシューティング

タスクの実行中に問題が発生した場合、それは Semaphore 自体の問題ではなく、セットアップ環境の問題である可能性があります!

問題が Semaphore の外部で発生しているかどうかを確認するため、次の手順を実行してください。

ユーザーのコンテキストに切り替えます。
```
sudo su --login semaphore
```

virtualenv を使用している場合は、そのコンテキストに切り替えます。

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

# troubleshooting

deactivate

Ansible playbook を手動で実行します
- 失敗する 場合 => 環境に問題があります
- 成功する 場合:
  - Semaphore 内の設定を再確認してください
  - Semaphore の問題である可能性があります

サービスユーザー​

トラブルシューティング​

Python3​

Requirements​

ユーザーコンテキストのモジュール​

virtualenv 内のモジュール​

トラブルシューティング​

Ansible コレクションとロール​

Requirements​

ユーザーコンテキストへのインストール​

virtualenv 使用時のインストール​

リバースプロキシ​

Systemd サービスの詳細​

ベース​

サービスユーザー​

Python モジュール​

ユーザーコンテキストの場合​

virtualenv の場合​

Ansible コレクションとロール​

ユーザーコンテキストの Python3 を使用する場合​

virtualenv の Python3 を使用する場合​

その他のユースケース​

ローカルの MariaDB を使用する場合​

ローカルの Nginx を使用する場合​

ログを syslog に送信する場合​

完全な例​

ユーザーコンテキストの Python モジュール​

virtualenv の Python モジュール​

修正​

トラブルシューティング​

サービスユーザー

トラブルシューティング

Python3

Requirements

ユーザーコンテキストのモジュール

virtualenv 内のモジュール

トラブルシューティング

Ansible コレクションとロール

Requirements

ユーザーコンテキストへのインストール

virtualenv 使用時のインストール

リバースプロキシ

Systemd サービスの詳細

ベース

サービスユーザー

Python モジュール

ユーザーコンテキストの場合

virtualenv の場合

Ansible コレクションとロール

ユーザーコンテキストの Python3 を使用する場合

virtualenv の Python3 を使用する場合

その他のユースケース

ローカルの MariaDB を使用する場合

ローカルの Nginx を使用する場合

ログを syslog に送信する場合

完全な例

ユーザーコンテキストの Python モジュール

virtualenv の Python モジュール

修正

トラブルシューティング