UCIDM パッケージアップデート時の移行作業

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

1.10.0 (2026-07-27) から 1.11.0 (2026-xx-yy) へアップデートするときに必要となる作業

コンテナに渡す環境変数の名前とマウント先の変更

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

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

compose サービスを停止する

$ docker compose down

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

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

$ vi compose.yml

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

   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 のデータベースに置き、ファイルを読みません。テンプレートと画像の移し方はデザインのテンプレートと画像の移行を参照してください。

   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 のマウント先を変更します。

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

   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 サービスで同じように変更します。

   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 ログインを有効にしている場合は、次のように変更します。

   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 の署名に失敗してログインできなくなります。

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

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

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

compose サービスを起動する

$ docker compose up -d

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

デザインのテンプレートと画像の移行

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

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

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

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

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

画像を置き直す

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">) に書き換えてください。

見た目を確認する

ユーザープロファイル画面に、移したデザインとロゴが表示されていることを確認します。 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) へアップデートするときに必要となる作業

外部連携モジュール (consumer サービス) の移行

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

  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 連携管理画面の外部連携設定画面で設定するように変更となります。

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

  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) へアップデートするときに必要となる作業

MongoDB コンテナイメージの移行

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

$ 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

compose サービスを停止する

$ docker compose down

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

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

$ vi compose.yml

   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

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

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

移行後の 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

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

$ 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

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

compose サービスを再起動する

$ docker compose down
$ docker compose up -d

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

不要なデータを削除する

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

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

Agent サービスの環境変数 PROTOCOL の削除

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

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

$ vi compose.yml

   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) へアップデートするときに必要となる作業

コンテナの環境変数からデータベースのシステム設定への移行

UCIDM API と Agent モジュールのサービス設定の環境変数をシステム設定へ移行する必要があります。

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

RabbitMQ 接続設定の変更

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

UCIDM API と外部連携モジュールのサービス設定の環境変数を次のように変更する必要があります。

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

MongoDB コンテナイメージのリポジトリ変更

Upcoming changes to the Bitnami catalog (effective August 28th, 2025) により、MongoDB のコンテナイメージを取得するリポジトリを bitnamilegacy/mongodb へ変更する必要があります。

  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) へアップデートするときに必要となる作業

bind mounts volume ディレクトリ配下の owner/permission の変更

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

$ docker compose down

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

  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

#UCIDM パッケージ アップデート時の移行作業

#1.10.0 (2026-07-27) から 1.11.0 (2026-xx-yy) へアップデートするときに必要となる作業

#コンテナに渡す環境変数の名前とマウント先の変更

#デザインのテンプレートと画像の移行

#1.9.0 (2026-03-11) から 1.10.0 (2026-07-27) へアップデートするときに必要となる作業

#外部連携モジュール (consumer サービス) の移行

#1.8.0 (2025-10-14) から 1.9.0 (2026-03-11) へアップデートするときに必要となる作業

#MongoDB コンテナイメージの移行

#Agent サービスの環境変数 PROTOCOL の削除

#1.7.0 (2025-05-02) から 1.8.0 (2025-10-14) へアップデートするときに必要となる作業

#コンテナの環境変数からデータベースのシステム設定への移行

#RabbitMQ 接続設定の変更

#MongoDB コンテナイメージのリポジトリ変更

#1.5.0 (2025-01-10) から 1.7.0 (2025-05-02) へアップデートするときに必要となる作業

#bind mounts volume ディレクトリ配下の owner/permission の変更