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

# UCIDM パッケージ アップデート時の移行作業 \{#ucidm-package-update-tasks}

UCIDM パッケージ のアップデート時に必要となる作業について記載しています。

### 1.10.0 (2026-07-27) から 1.11.0 (2026-xx-yy) へアップデートするときに必要となる作業 \{#from-1-10-0-to-1-11-0}

#### コンテナに渡す環境変数の名前とマウント先の変更 \{#rename-environment-variables-and-mount-targets}

1.11.0 では、各モジュールのコンテナが読む環境変数の名前と、データを読み書きするコンテナ内のパスが変わりました。
1.11.0 のコンテナイメージは変更前の名前とパスを読まないので、コンテナイメージを更新するときに compose.yml も合わせて変更します。

変更するのは compose.yml の `environment` のキー (コンテナに渡す変数名) と `volumes` の `target` (コンテナ内のマウント先) です。
ucidm.env に定義している変数名と、ホスト側のディレクトリ (`source`) は変わりません。
ホスト上のデータを移動する作業もありません。
ただし、ユーザープロファイル画面のデザインは UCIDM API のデータベースへ移すため、compose サービスを停止する前に [デザインのテンプレートと画像の移行](#migrate-designs-to-database) の手順 1 を行ってください。

1. compose サービスを停止する

```
$ docker compose down
```

2. compose.yml の各サービスの設定を変更する

次の diff を参考に設定を変更します。

```
$ vi compose.yml
```

ID 連携管理画面 (admin-ui サービス) は、環境変数の名前を変更します。
`PUBLIC_UCIDM_API_SERVER` は廃止となり、コンテナが `API_HOST` と `API_PORT` から UCIDM API の URL を組み立てます。

```diff
   admin-ui:
     ...
     environment:
       PORT: "${ADMIN_NODE_PORT}"
-      PUBLIC_UCIDM_API_SERVER: "http://${API_HOST}:${API_PORT}"
-      JWT_ACCESS_SECRET: "${ADMIN_UI_JWT_ACCESS_SECRET}"
+      API_HOST: "${API_HOST}"
+      API_PORT: "${API_PORT}"
+      ADMIN_UI_JWT_ACCESS_SECRET: "${ADMIN_UI_JWT_ACCESS_SECRET}"
       SESSION_MAX_AGE: "${SESSION_MAX_AGE}"
```

ユーザープロファイル画面 (ucidm-ui サービス) は、環境変数の名前を変更し、デザインファイルのマウントを外します。
1.11.0 のユーザープロファイル画面は、デザインのテンプレート (ヘッダー、フッター、パスワードポリシー、アカウント通知書の HTML) と画像を UCIDM API のデータベースに置き、ファイルを読みません。
テンプレートと画像の移し方は [デザインのテンプレートと画像の移行](#migrate-designs-to-database) を参照してください。

```diff
   ucidm-ui:
     ...
     environment:
       PORT: "${UCIDM_NODE_PORT}"
-      PUBLIC_UCIDM_API_SERVER: "http://${API_HOST}:${API_PORT}"
-      PUBLIC_ENABLE_SELF_PASSWORD_RESET: "${ENABLE_SELF_PASSWORD_RESET}"
-      JWT_ACCESS_SECRET: "${UCIDM_UI_JWT_ACCESS_SECRET}"
+      API_HOST: "${API_HOST}"
+      API_PORT: "${API_PORT}"
+      UCIDM_UI_ENABLE_SELF_PASSWORD_RESET: "${ENABLE_SELF_PASSWORD_RESET}"
+      UCIDM_UI_JWT_ACCESS_SECRET: "${UCIDM_UI_JWT_ACCESS_SECRET}"
       SESSION_MAX_AGE: "${SESSION_MAX_AGE}"
-      DEFAULT_LANGUAGE: "${DEFAULT_LANGUAGE}"
+      UCIDM_UI_DEFAULT_LANGUAGE: "${DEFAULT_LANGUAGE}"
       BODY_SIZE_LIMIT: "Infinity"
     ...
-    volumes:
-      - type: bind
-        source: ./ucidm-ui/designs
-        target: /designs
-        bind:
-          create_host_path: false
-      - type: bind
-        source: ./ucidm-ui/images
-        target: /images
-        bind:
-          create_host_path: false
```

UCIDM API (api サービス) と外部連携モジュール (consumer サービス) は、`./server-data` のマウント先を変更します。

```diff
   api:
     ...
     volumes:
       - type: bind
         source: ./server-data
-        target: /ucidm
+        target: /var/opt/osstech/lib/ucidm/data
         bind:
           create_host_path: false
```

```diff
   consumer:
     ...
     volumes:
       - type: bind
         source: ./server-data
-        target: /ucidm
+        target: /var/opt/osstech/lib/ucidm/data
         bind:
           create_host_path: false
```

Agent モジュール (agent-ldap、agent-ad、agent-meid サービス) は、`RELOAD_INTERVAL` の名前を変更します。
次の diff は agent-ldap サービスの例です。
compose.yml に設定しているすべての Agent サービスで同じように変更します。

```diff
   agent-ldap:
     ...
     environment:
       TZ: "${TZ}"
       #SSL_CERT_FILE: "${SSL_CERT_FILE}"
       PAGE_KEY_PATH: "${AGENT_PAGE_KEY_PATH}"
-      RELOAD_INTERVAL: "${AGENT_RELOAD_INTERVAL}"
+      AGENT_RELOAD_INTERVAL: "${AGENT_RELOAD_INTERVAL}"
       API_HOST: "${API_HOST}"
```

上記の diff にない環境変数を compose.yml に追加している場合は、次の表に従ってその変数名も変更します。
表にない環境変数の名前は変わりません。

| サービス     | 変更前の名前                      | 変更後の名前                          |
| :------- | :-------------------------- | :------------------------------ |
| admin-ui | PUBLIC_HTTP_REQUEST_TIMEOUT | ADMIN_UI_HTTP_REQUEST_TIMEOUT   |
| ucidm-ui | PUBLIC_HTTP_REQUEST_TIMEOUT | UCIDM_UI_HTTP_REQUEST_TIMEOUT   |
| ucidm-ui | PUBLIC_ADMIN_UI_URL         | UCIDM_UI_ADMIN_UI_URL           |
| ucidm-ui | PUBLIC_ENABLE_SAML_LOGIN    | UCIDM_UI_ENABLE_SAML_LOGIN      |
| ucidm-ui | PUBLIC_ENABLE_SP_INIT_SLO   | UCIDM_UI_ENABLE_SP_INIT_SLO     |
| ucidm-ui | PUBLIC_TOTP_REGISTER_URL    | UCIDM_UI_TOTP_REGISTER_URL      |
| ucidm-ui | PUBLIC_PASSKEY_REGISTER_URL | UCIDM_UI_PASSKEY_REGISTER_URL   |
| consumer | ENABLE_SCRIPT_PASSWORD      | CONSUMER_ENABLE_SCRIPT_PASSWORD |

たとえば ucidm-ui サービスで SAML ログインを有効にしている場合は、次のように変更します。

```diff
   ucidm-ui:
     ...
     environment:
-      PUBLIC_ENABLE_SAML_LOGIN: "${ENABLE_SAML_LOGIN}"
+      UCIDM_UI_ENABLE_SAML_LOGIN: "${ENABLE_SAML_LOGIN}"
```

> \[!WARNING]
> 変更前の名前のまま 1.11.0 のコンテナを起動すると、変数が設定されていないものとして扱われます。
> たとえば ucidm-ui サービスは `UCIDM_UI_DEFAULT_LANGUAGE` がないと起動に失敗し、admin-ui サービスは JWT の署名に失敗してログインできなくなります。

3. compose.yml の構文をチェックする

compose.yml の変更後に構文チェックをしてエラーが発生しないことを確認します。

```
$ docker compose config 1>/dev/null
$ echo $?
0
```

4. compose サービスを起動する

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

サービス起動後、ID 連携管理画面とユーザープロファイル画面にログインできることを確認します。
続けて [デザインのテンプレートと画像の移行](#migrate-designs-to-database) の手順 2 以降を行います。

#### デザインのテンプレートと画像の移行 \{#migrate-designs-to-database}

1.11.0 のユーザープロファイル画面は、デザインのテンプレート (ヘッダー、フッター、パスワードポリシー、アカウント通知書) と画像 (ロゴ、ファビコン、テンプレートに載せる画像) を UCIDM API のデータベースに置き、`ucidm-ui/designs` と `ucidm-ui/images` のファイルを読みません。
1.11.0 に上げると、データベースには製品の標準のテンプレートが入ります。編集したテンプレートと画像は、次の手順で移します。

1. 1.10.0 のまま、テンプレートをエクスポートする (compose サービスを停止する前に行います)

ユーザープロファイル画面に system-superadmin のアカウントでログインし、各種設定の「設定の入出力」の「エクスポート」タブで「デザイン設定」を選んでエクスポートします。

2. 1.11.0 に上げたあと、テンプレートをインポートする

ユーザープロファイル画面の「設定の入出力」の「インポート」タブで、手順 1 のファイルを選び、「デザイン設定」をインポートします。

3. 画像を置き直す

1.10.0 の設定のエクスポートには画像が含まれないので、デザイン設定の「画像」の画面から置き直します。

| 1.10.0 のファイル                        | 1.11.0 で置く場所                    |
| :---------------------------------- | :------------------------------ |
| `ucidm-ui/images/header/logo.png`   | 「ロゴ」                            |
| `ucidm-ui/images/favicon/favicon.*` | 「ファビコン」                         |
| テンプレートが参照しているそのほかの画像                | 「テンプレートの画像」に、テンプレートが参照している名前で置く |

テンプレートが `<img src="header/banner.png">` のように `/` を含むパスで画像を参照している場合は、画像を置いた名前だけ (`<img src="banner.png">`) に書き換えてください。

4. 見た目を確認する

ユーザープロファイル画面に、移したデザインとロゴが表示されていることを確認します。
1.10.0 の CSS ファイル (`custom-design.css`) のうち、移るのは背景色だけです。
罫線などそのほかの宣言は適用されないので、必要であればテンプレートの HTML の `style` 属性か `<style>` 要素に書き直してください。ヘッダーの上下の罫線は製品の固定の見た目になりました。

確認できたら、`ucidm-ui/designs` と `ucidm-ui/images` は使われません。削除してもかまいません。

### 1.9.0 (2026-03-11) から 1.10.0 (2026-07-27) へアップデートするときに必要となる作業 \{#from-1-9-0-to-1-10-0}

#### 外部連携モジュール (consumer サービス) の移行 \{#migrate-multiple-consumers}

次のように compose.yml に1つの consumer サービスのみを設定します。複数の外部連携設定を1つのサービスが扱うようになりました。

```yml
  consumer:
    depends_on:
      mongo:
        condition: service_healthy
      rabbitmq:
        condition: service_healthy
    container_name: consumer
    image: docker.io/osstech/ucidm-consumer:latest
    logging: *default-logging
    volumes:
      - type: bind
        source: ./server-data
        target: /ucidm
        bind:
          create_host_path: false
    entrypoint:
      - ./bin/consumer
      - -jsonl
    environment:
      TZ: "${TZ}"
      MONGO_USER: "${MONGO_USER}"
      MONGO_PASSWORD: "${MONGO_PASSWORD}"
      MONGO_HOSTS: "${MONGO_HOSTS}"
      MONGO_REPLICA_SET: "${MONGO_REPLICA_SET}"
      RABBITMQ_USER: "${RABBITMQ_USER}"
      RABBITMQ_PASSWORD: "${RABBITMQ_PASSWORD}"
      RABBITMQ_HOST: "${RABBITMQ_HOST}"
    ports:
      - 127.0.0.1:7099:7099
    restart: "always"
```

またこれまで環境変数として設定していた外部サービスとの接続情報はすべて [ID 連携管理画面の外部連携設定画面](/resource/ucidm/docs/on-premise/dev/administration/admin-ui/index.md#external-federation-settings) で設定するように変更となります。

例えば consumer-ad-001 サービスの場合、次の3つの環境変数の設定を外部連携設定画面に移行する必要があります。

```yml
  consumer-ad-001:
    ...
    environment:
      LDAP_URL: "${AD_URL}"
      LDAP_BIND_DN: "${AD_BIND_DN}"
      LDAP_BIND_PASSWORD: "${AD_BIND_PASSWORD}"
```

### 1.8.0 (2025-10-14) から 1.9.0 (2026-03-11) へアップデートするときに必要となる作業 \{#from-1-8-0-to-1-9-0}

#### MongoDB コンテナイメージの移行 \{#migrate-osstech-mongodb-image}

1. 既存データをバックアップする

```
$ docker compose exec mongo sh -c 'mongodump \
  --authenticationDatabase=admin \
  --port=$MONGODB_PORT_NUMBER \
  --username="$MONGODB_ROOT_USER" \
  --password="$MONGODB_ROOT_PASSWORD" \
  --db=ucidm \
  --archive' > $(date +%Y%m%d)-mongodb.dump
```

2. compose サービスを停止する

```
$ docker compose down
```

3. compose.yml の mongo サービスの設定を変更する

次の diff を参考に設定を変更します。移行前とデータが永続化される bind mounts volumes ディレクトリの場所が変更になっています。

```
$ vi compose.yml
```

```diff
   mongo:
     container_name: mongo
-    image: docker.io/bitnamilegacy/mongodb:8.0.3
+    image: docker.io/osstech/mongodb:8.2.4
     logging: *default-logging
     volumes:
       - type: bind
-        source: ./mongodb
-        target: /bitnami/mongodb
+        source: ./mongodb/db
+        target: /data/db
         bind:
           create_host_path: false
     environment:
@@ -302,12 +302,9 @@ services:
       MONGODB_ROOT_USER: "${MONGO_USER}"
       MONGODB_ROOT_PASSWORD: "${MONGO_PASSWORD}"
       MONGODB_PORT_NUMBER: "27017"
-      MONGODB_INITIAL_PRIMARY_PORT_NUMBER: "27017"
       MONGODB_ADVERTISED_HOSTNAME: "${MONGO_HOSTNAME}"
       MONGODB_REPLICA_SET_NAME: "${MONGO_REPLICA_SET}"
-      MONGODB_REPLICA_SET_MODE: "primary"
       MONGODB_REPLICA_SET_KEY: "my/replication/common/key123"
-      MONGODB_SYSTEM_LOG_VERBOSITY: 0
     hostname: "${MONGO_HOSTNAME}"
```

compose.yml の変更後に構文チェックをしてエラーが発生しないことを確認します。

```
$ docker compose config 1>/dev/null
$ echo $?
0
```

4. bind mounts volumes ディレクトリを作成する

```
$ rootlesskit mkdir -p mongodb/db/.mongodb
$ rootlesskit chown -R 999:999 mongodb/db
```

5. 移行後の mongodb コンテナイメージで mongo サービスを起動する

```
$ docker compose up -V mongo
```

mongo サービスの初回起動時のみ、次のようなログを確認できます。

```
[HACK] start MongoDB for INITIALIZATION: --bind_ip 127.0.0.1 --port 27017 --tlsMode disabled --logpath /proc/1/fd/1 --logappend --pidfilepath /tmp/docker-entrypoint-temp-mongod.pid --fork

[HACK] original arguments for MongoDB: --bind_ip 127.0.0.1 --port 27017 --tlsMode disabled --logpath /proc/1/fd/1 --logappend --pidfilepath /tmp/docker-entrypoint-temp-mongod.pid --shutdown

[HACK] start MongoDB for initiating Replica Set: --fork --syslog --auth --bind_ip_all --port 27017 --replSet myrs --keyFile /keyfile

[HACK] start MongoDB for PRODUCTION USE: --auth --bind_ip_all --port 27017 --replSet myrs --keyFile /keyfile
```

6. バックアップしたデータをリストアする

```
$ docker compose exec --interactive --no-TTY mongo bash -c 'mongorestore \
  --authenticationDatabase=admin \
  --port=$MONGODB_PORT_NUMBER \
  --username="$MONGODB_ROOT_USER" \
  --password="$MONGODB_ROOT_PASSWORD" \
  --nsInclude="ucidm.*" \
  --archive' < ./YYYYMMDD-mongodb.dump
```

データをリストアした後にコレクションのインデックスを設定します。インデックス作成がエラーになっていないかを確認します。エラーになった場合は別途インデックスの作成作業が必要になります。

7. compose サービスを再起動する

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

サービス起動後、ID 連携管理画面でログインして既存データを確認します。

8. 不要なデータを削除する

データ移行を正常に行えたことを確認した後、移行前のデータとバックアップデータを削除します。

```
$ rootlesskit rm -rf mongodb/data/
$ rm -f YYYYMMDD-mongodb.dump
```

#### Agent サービスの環境変数 PROTOCOL の削除 \{#drop-protocol-environment-variable}

compose サービスを停止した状態で compose.yml の Agent サービスの設定から PROTOCOL の環境変数を削除します。

次の diff を参考にしてください。

```
$ vi compose.yml
```

```diff
   agent-ldap:
     ...
     environment:
       TZ: "${TZ}"
       #SSL_CERT_FILE: "${SSL_CERT_FILE}"
-      PROTOCOL: "syncrepl"
       PAGE_KEY_PATH: "${AGENT_PAGE_KEY_PATH}"
       RELOAD_INTERVAL: "${AGENT_RELOAD_INTERVAL}"
       API_HOST: "${API_HOST}"
```

### 1.7.0 (2025-05-02) から 1.8.0 (2025-10-14) へアップデートするときに必要となる作業 \{#from-1-7-0-to-1-8-0}

#### コンテナの環境変数からデータベースのシステム設定への移行 \{#migrate-environment-variables}

[UCIDM API](/resource/ucidm/docs/on-premise/dev/configuration/ucidm-api.md) と [Agent モジュール](/resource/ucidm/docs/on-premise/dev/configuration/agent/index.md) のサービス設定の環境変数をシステム設定へ移行する必要があります。

詳細は弊社のサポート担当者にご確認ください。

#### RabbitMQ 接続設定の変更 \{#migrate-rabbitmq-env}

コンテナをアップグレードするときに compose サービスが停止した状態で compose.yml (ucidm.env) の環境変数を移行します。

[UCIDM API](/resource/ucidm/docs/on-premise/dev/configuration/ucidm-api.md) と [外部連携モジュール](/resource/ucidm/docs/on-premise/dev/configuration/id-federation-client.md) のサービス設定の環境変数を次のように変更する必要があります。

```diff
    environment:
-      AMQP_URL: "${AMQP_URL}"
+      RABBITMQ_USER: "${RABBITMQ_USER}"
+      RABBITMQ_PASSWORD: "${RABBITMQ_PASSWORD}"
+      RABBITMQ_HOST: "${RABBITMQ_HOST}"
```

#### MongoDB コンテナイメージのリポジトリ変更 \{#migrate-mongodb-repo}

[Upcoming changes to the Bitnami catalog (effective August 28th, 2025)](https://github.com/bitnami/containers/issues/83267) により、[MongoDB](/resource/ucidm/docs/on-premise/dev/configuration/mongodb.md) のコンテナイメージを取得するリポジトリを `bitnamilegacy/mongodb` へ変更する必要があります。

```diff
  mongo:
-   image: docker.io/bitnami/mongodb:8.0.3
+   image: docker.io/bitnamilegacy/mongodb:8.0.3
```

### 1.5.0 (2025-01-10) から 1.7.0 (2025-05-02) へアップデートするときに必要となる作業 \{#from-1-5-0-to-1-7-0}

#### bind mounts volume ディレクトリ配下の owner/permission の変更 \{#migrate-bind-mounts-volume}

compose サービスを停止します。

```
$ docker compose down
```

compose.yml の mongo サービスから `user: root` を削除する。

```diff
  mongo:
    container_name: mongo
-   user: root
    image: docker.io/bitnamilegacy/mongodb:8.0.3
```

コンテナ内のアプリケーションを uid=1001 のユーザーが実行するように変更されたため、そのホスト上でのディレクトリやファイルの owner/permission を変更する必要があります。

subuid の設定を確認します。

```
$ cat /etc/subuid
ucidm:100000:65536
```

subuid が 100000 からマッピングする設定の場合はホスト上では uid=101000 (100000 + 1001 - 1) としてマッピングされます。compose.yml を配置している次の3つのディレクトリの owner/permission を変更します。

- mongodb
- agent-data
- server-data

```
$ rootlesskit chown -R 1001:0 mongodb server-data agent-data
```

compose サービスを開始して正常に動作することを確認します。

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