> For AI agents: the complete documentation index is available at /resource/ucidm/docs/on-premise/1.8.0/llms.txt, the full documentation bundle is available at /resource/ucidm/docs/on-premise/1.8.0/llms-full.txt.

# Compose サービスの運用

UCIDM は [Docker Compose](https://docs.docker.com/compose/) を使い、複数のアプリケーションやミドルウェアのコンテナを起動して、それぞれのサービスが協調してシステムを構成しています。

## ucidm ユーザーでログインしないときのユーザーの切り替え \{#switch-ucidm}

systemd のユーザーモード、ならびに docker の rootless モードを使うには ucidm ユーザーでログインしたときに設定される環境変数が必要になります。直接 ucidm ユーザーでログインできないときは machinectl を使ってユーザーを切り替えるようにしてください。

machinectl コマンドを使うには systemd-container パッケージをインストールする必要があります。

```bash
$ sudo dnf install -y systemd-container
```

sudo の実行権限をもつユーザーで次のように machinectl コマンドを実行してください。


```bash
$ sudo machinectl shell ucidm@
```

ucidm ユーザーにスイッチした後に次の環境変数が適切に設定されていることを確認します。

```bash
$ env | egrep "(DBUS_|XDG_)"
...
XDG_RUNTIME_DIR=/run/user/992
DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/992/bus
```

## コンテナとアプリケーションを実行するユーザー／グループ \{#uidgid-compose}

コンテナ内のアプリケーションは non-root ユーザーで実行されます。これはコンテナのセキュリティを向上させることに寄与します。

このときそれぞれのコンテナがマウントする volume ディレクトリ配下に作成されるディレクトリやファイルのオーナー／権限は次のようになります。

| コンテナ     | コンテナ内 UID:GID |  ホスト上 UID:GID |
| :------- | :-----------: | :-----------: |
| rabbitmq |    999:999    | 100998:100998 |
| admin-ui |     1000:0    |  100999:ucidm |
| ucidm-ui |     1000:0    |  100999:ucidm |
| mongo    |     1001:0    |  101000:ucidm |
| api      |     1001:0    |  101000:ucidm |
| agent    |     1001:0    |  101000:ucidm |
| consumer |     1001:0    |  101000:ucidm |

ホスト上から作成したファイルに対して適切な UID:GID をマッピングするには [rootlesskit](https://github.com/rootless-containers/rootlesskit) コマンドを使って操作します。

例えば、(rabbitmq を除く) ホスト上で作成したファイルにコンテナからアクセスできるオーナー／権限を設定するには次のコマンドを実行します。

```
$ rootlesskit chown -R ${UID}:0 path/to/dir
```

- $\{UID} はコンテナ内の UID にあわせて 1000, 1001 を設定する

実際にホスト上で作成した ucidm:ucidm オーナーのディレクトリとファイルをコンテナ内から UID=1001 で作成したようにオーナー／権限を設定するコマンド例を次に示します。

```
$ mkdir mydir
$ ls -ld mydir
drwxr-xr-x. 2 ucidm ucidm 20 Apr  4 17:51 mydir
$ touch mydir/sample
$ ls -l mydir/sample
-rw-r--r--. 1 ucidm ucidm 0 Apr  4 17:51 mydir/sample

$ rootlesskit chown -R 1001:root mydir

$ ls -ld mydir
drwxr-xr-x. 2 101000 ucidm 20 Apr  4 17:51 mydir
$ ls -l mydir/sample
-rw-r--r--. 1 101000 ucidm 0 Apr  4 17:51 mydir/sample
```

### ホスト上にあるファイルを volume ディレクトリ配下に移動する \{#uidgid-compose-mv}

ユーザープロファイル画面で使うロゴ画像を管理するコマンド例を次に示します。

ucidm-ui は UID=1000 で作成したようにオーナー／権限を設定します。

```
$ rootlesskit mv ~/mylogo.png ucidm-ui/images/
$ rootlesskit chown 1000:root ucidm-ui/images/mylogo.png
$ ls -l ucidm-ui/images/
合計 24
-rw-rw-r--. 1 100999 ucidm  4409  4月  8 14:17 mylogo.png
```

## 安全な停止手順 \{#stop-compose}

[オンプレミス版 UCIDM は冗長構成をサポートしない](/resource/ucidm/docs/on-premise/1.8.0/faq/system.md#redundant-system) ため、原則としてメンテナンスなどで Compose サービスを停止するときは LDAP サーバーに対して更新を行わない、また ID 連携処理の途中段階で停止しないように運用してください。

次の手順で Compose サービスを停止してください。

1. LDAP サーバーに更新を行わないようアクセスを遮断する
2. 「ジョブ進捗概要」や「実行中ジョブ」画面で処理中のエントリーが大量にないかを確認する
3. compose サービスを停止する

```bash
$ docker compose stop
```

作業にあわせて各種ドキュメントを確認してください。

- [コンテナイメージのバージョンアップ](/resource/ucidm/docs/on-premise/1.8.0/operation/upgrade-version.md)

LDAP サーバーから ID 連携の処理が途中の状態で Compose サービスを停止するとエラーが発生します。エラーが発生しても、なるべく起動後に再処理するように振る舞います。どのような状況であっても完全に再処理できることは保証できませんが、多くのケースで自動的に再処理されます。起動後に少し待って履歴をご確認ください。

もし履歴から再処理できていなければ [ID 情報の再同期](/resource/ucidm/docs/on-premise/1.8.0/operation/resync.md) を行ってください。

### LDAP サーバー -> Agent モジュール -> UCIDM API の処理 \{#stop-compose-ldap-agent-api}

- ユーザー／グループエントリーの追加・更新
  - 停止時にエラーは発生するが、エラーが発生したところから再処理する
- グループメンバーの追加／削除
  - 同じグループへのメンバー追加／削除の順序は入れ替わるが、再処理する
- ユーザー／グループエントリーの削除
  - Agent モジュールの停止中に削除されたエントリーは再処理できない
  - [運用ツールにより不整合ユーザーを削除してください](/resource/ucidm/docs/on-premise/1.8.0/operation/resync.md#resync-delete)

### UCIDM API -> 外部連携モジュールの処理 \{#stop-compose-api-consumer}

- エントリーの追加・更新・削除
  - 正常にメッセージキューサービスを停止できていれば未処理のメッセージは永続化される
  - 起動後に永続化されているメッセージを再処理する

## Compose サービスのコンテナや環境の再作成 \{#down-compose}

Compose サービスのコンテナや環境をクリーンに再作成する (永続化されているデータは消えません) ときは前節で安全に停止させた後に削除します。

```bash
$ docker compose down
```

down を実行したときにもしネットワークを削除できない状態になる場合があります。

```
✘ Network ucidm_default  Error
```

そのときは docker サービスを再起動してから down を実行してください。

```bash
$ systemctl --user restart docker
$ docker compose down
```

次のようなエラーが発生するときは DBUS_SESSION_BUS_ADDRESS の環境変数が適切に設定されているかを確認してください。

```bash
$ echo $DBUS_SESSION_BUS_ADDRESS
```

```
Failed to connect to bus: No medium found
```

適切に設定されていない場合は次のようにユーザー情報にあわせて設定します。

```bash
$ export DBUS_SESSION_BUS_ADDRESS="unix:path=/run/user/$(id -u)/bus"
```

## 環境変数の設定変更 \{#update-compose-env}

デフォルトでは `.env` ファイルに Compose サービスが参照する環境変数を設定します。サービス稼働後に環境変数を変更したい場合は `.env` ファイルを更新した後にコンテナを再作成する必要があります。

たとえば、次の手順で `api` サービスの環境変数を変更します。

```bash
$ vi .env
# 環境変数の値を変更して保存する
$ docker compose stop api
$ docker compose rm api
$ docker compose up -d api
```

複数サービスの環境変数を変更するときは [Compose サービスを停止](#stop-compose) させた後に [Compose サービスの環境を再作成](#down-compose) すると確実に反映できます。

## Compose サービスの起動 \{#up-compose}

次の手順で Compose サービスを起動してください。

```
$ docker compose up -d
```