Docker Composeでの並行運用移行

Docker Compose で運用しているドメインを、v1とv2を並行運用(同時起動)しながらv1からv2へ移行する手順です。

通常のCompose移行手順がv1を止めてv2へ切り替えるのに対し、こちらはHelmの concrnt2-migration チャートに相当する構成をComposeで実現します。v2の concrnt2 が公開エンドポイントとなり、/api/v1 や /ap などのレガシーパスは内部でv1の gateway へプロキシされます。移行期間中もv1のAPIやAPブリッジを動かし続けたい場合はこちらを利用してください。

Danger

作業を始める前に、必ずv1データベースのバックアップを取得してください。v1/_composeData ディレクトリごと退避しておくと安全です。

Caution

並行運用中、v1とv2のデータは同期されません。移行コマンドは一回限りのコピーであり、移行実行後にv1側へ書き込まれた新しいデータはv2へ反映されません。並行運用はあくまでレガシークライアントやAPブリッジの互換性を保つための過渡的な構成と考えてください。

前提

concrnt-compose リポジトリの dualstack/ にあるデュアルスタック構成を使います。この構成は設定ファイルとデータディレクトリとして v1/ と v2/ のものをそのまま参照するため、既存のv1構成を concrnt-compose の v1/ ディレクトリ構造で運用していることが前提です。

git clone https://github.com/concrnt/concrnt-compose

すでにクローン済みの場合は最新化してください。

Step 1. v2の設定を行う

v2/etc/config/config.yaml を編集します。v1の v1/etc/config/config.yaml を参照しながら、以下の値を設定してください。

Caution

concrnt.fqdn と concrnt.privatekey には、v1と同じ値を指定してください。ドメインの同一性を引き継ぐために必須です。

• concrnt.fqdn … v1と同じfqdn
• concrnt.privatekey … v1と同じ秘密鍵
• concrnt.layer … v1の concrnt.dimension と同じ値(通常 concrnt-mainnet)
• meta.* … サーバー名やメンテナ情報(お好みで)

続けて、同じファイルの services: にある net.concrnt.legacy ブロックのコメントを外します。これがレガシーパスをv1へプロキシする設定です。

  - name: net.concrnt.legacy
    host: gateway
    port: 8080
    paths:
      - /api/v1
      - /ap
      - /services
      - .well-known/webfinger
      - .well-known/nodeinfo
      - .well-known/host-meta
      - /storage
    preservePath: true

Step 2. v1を止めてデュアルスタックを起動する

v1スタックを停止し、代わりにデュアルスタック構成を起動します。データはバインドマウント(v1/_composeData)なので、コンテナを削除しても失われません。

docker compose -f v1/compose.yaml down
docker compose -f dualstack/compose.yaml up -d

v1側(gateway / api / webui など)とv2側(concrnt2 / world-app / v2db など)がまとめて起動します。ホストの 8080 を公開するのはv2の concrnt2 だけで、v1の gateway へは concrnt2 からの内部プロキシ経由でのみ到達します。hyperproxy はv1/v2共通のため1つだけ起動し、/summary や /image はv2側で直接処理されます。切り替えの間だけ短いダウンタイムが発生します。

Note

v1でAPブリッジ(apbridge)を有効にしていた場合は、dualstack/compose.yaml 内のコメントアウトを外して引き続き起動してください。/ap や /.well-known/webfinger はレガシーパスとしてv1へプロキシされるため、連合も継続します。

Step 3. 動作を確認する

ブラウザで自分のfqdnにアクセスし、v2のトップページ(CSID表示)が返ることを確認します。あわせて、レガシーパスがv1へ届いていることを確認してください。

curl https://example.tld/api/v1/domain

v1のドメイン情報(JSON)が返れば、プロキシは正常に機能しています。

Cloudflare Tunnel やリバースプロキシを利用している場合、v1と同じホストの 8080 を引き続き利用しているため、多くの場合は追加の変更は不要です。

Note

旧ダッシュボード(/web)はv2配下では配信されません(/ はworld-appが配信します)。これはHelmの移行チャートと同じ挙動です。

Step 4. データ移行を実行する

dualstack/compose.yaml の migration サービスの引数を、自分の環境に合わせて書き換えます。

    command:
      - conctl
      - migrate
      - v1-to-v2
      - --from-csid
      - <v1ドメインのCSID>      # ドメインのトップページに表示される ccs... の値
      - --from-dsn
      - postgres://postgres:postgres@db:5432/concrnt     # そのままでOK
      - --from-fqdn
      - example.tld            # v1と同じfqdn
      - --dest-dsn
      - postgres://postgres:postgres@v2db:5432/concrnt   # そのままでOK
      - --dest-fqdn
      - example.tld            # v1と同じfqdn
      # 移行対象から除外したいアカウントがあれば指定
      # - --ignore-ccids
      # - con1xxxx...

項目	説明
--from-csid	移行元(v1)ドメインのCSID。ドメインのトップページに表示される ccs... の値です。
--from-dsn	v1データベースへの接続文字列。同一プロジェクト内なのでホスト名 db のままで構いません(通常手順と異なり docker network connect は不要です)。
--from-fqdn / --dest-fqdn	どちらもv1と同じfqdnを指定します。
--dest-dsn	v2データベース(v2db)への接続文字列。そのままで構いません。
--ignore-ccids	移行対象から除外するアカウントのCCID。不要ならコメントアウトのままにします。

書き換えたら、migration サービスを単発で実行します(profiles: migration により通常の up では起動しません)。

docker compose -f dualstack/compose.yaml run --rm migration

Caution

データ量によっては時間がかかります。エラーなく完了することを確認してください。失敗した場合は原因を解消し、v2データベース(v2/_composeData/db)を初期化してからやり直してください。

Step 5. 移行結果を確認する

Webクライアント https://concrnt.world から既存のアカウントでログインし、過去のタイムラインやメッセージが表示されることを確認してください。

Step 6. ActivityPubブリッジを移行する(オプション)

Note

v1のActivityPubブリッジ(ccworld-ap-bridge)を運用していない場合、このステップは不要です。Step 7へ進んでください。

v2では新しいActivityPubブリッジ(concrnt/activitypub、イメージ ghcr.io/concrnt/activitypub)を使用します。移行は「並行デプロイ → データ移行 → 経路切り替え」の順で行います。データ移行が終わるまでは /ap や .well-known 系のパスは net.concrnt.legacy 経由でv1ブリッジが処理し続けるため、外部からの連合は途切れません。

6-1. ブリッジ用サービスアカウントを用意する

v2ブリッジはconcrnt上のサービスアカウントとして動作します。v1ブリッジで使っていたアカウント(apconfig.yaml の apConfig.proxyPriv に設定していた鍵)をそのまま引き継ぐことを推奨します。

このアカウントはv1上の通常のアカウントなので、Step 4の移行で(--ignore-ccids で除外していなければ)既にv2へ移行されています。その場合は新たに作成する必要はなく、その秘密鍵を6-2でそのまま使ってください。

もしv2に存在しない場合(移行時に除外した場合など)は、--privatekey で鍵を指定して登録できます。

docker compose -f dualstack/compose.yaml run --rm concrnt2 conctl operation create-account --privatekey <v1ブリッジの秘密鍵>

新しいアカウントを作る場合は --privatekey を付けずに実行し、出力される ccid と privatekey を控えてください(いずれの場合もアカウントはv2コアにローカル登録されます)。

6-2. v2ブリッジを並行デプロイする

v2/etc/ap/config.yaml を編集し、ブリッジの設定を行います。

• concrnt.domain … v2コアと同じfqdn
• concrnt.privateKey … 6-1で用意したアカウントの秘密鍵

CCIDの設定は不要です(秘密鍵から自動で導出されます)。database.url / redis.url はv2コアと共有の v2db / v2-redis を指しており、DB構成を変更していなければそのままで構いません。

次に dualstack/compose.yaml の activitypub サービスのコメントを外し、起動します。

docker compose -f dualstack/compose.yaml up -d activitypub

Caution

v2/etc/config/config.yaml の net.concrnt.activitypub はまだコメントのままにしてください。データ移行が完了する前に経路をv2へ切り替えると、外部サーバーからの /ap へのアクセスに空の応答が返ってしまいます(切り替えは6-5で行います)。

起動を確認します。初回起動時にv2ブリッジ用のテーブルが自動作成されます(これは6-4の移行コマンドの前提です)。

docker compose -f dualstack/compose.yaml logs activitypub

6-3. v2ブリッジを一時停止する

Caution

データ移行中にv2ブリッジが動いていると、移行中のフォローに対してFollowアクティビティをリモートサーバーへ再送してしまいます。必ず停止してから移行してください。

docker compose -f dualstack/compose.yaml stop activitypub

6-4. データを移行する

migration サービスのコンテナで conctl migrate ap-v1-to-v2 を実行します。Step 4と異なり compose.yaml の書き換えは不要で、run の引数でコマンドを上書きします(migration サービスを使うのは、v1データベースへ到達でき、かつv2の設定がマウントされている——認証トークンの自動生成に必要——ためです)。まずは --dry-run で内容を確認します。

docker compose -f dualstack/compose.yaml run --rm migration conctl migrate ap-v1-to-v2 \
  --from-dsn "host=db user=postgres password=postgres dbname=concrnt port=5432 sslmode=disable" \
  --dest-dsn "postgres://postgres:postgres@v2db:5432/concrnt" \
  --dest-fqdn <あなたのfqdn> \
  --ap-ccid <6-1で用意したアカウントのCCID> \
  --dry-run

項目	説明
--from-dsn	v1データベースへの接続文字列。v1ブリッジはv1コアとデータベースを共有しているため、ホスト名は db のままで構いません。
--dest-dsn	v2ブリッジのデータベースへの接続文字列。v2db(v2コアと共有)のままで構いません。
--dest-fqdn	移行先(v2)ドメインのfqdn。
--ap-ccid	6-1で用意したブリッジ用サービスアカウントのCCID。v1のアカウントを引き継いだ場合は、v1でブリッジ用ボットとして使っていたアカウントのCCIDです。

問題なければ --dry-run を外して再実行します。v1の ap_entities(アカウントと鍵)とフォロー・フォロワー情報がv2へ移行されます。

Note

フォロー情報は内部接続ではなく、公開URL(https://<fqdn>/api/v2/repository)へのPOSTで移行されます。コンテナから自分のfqdnへHTTPSで到達できる必要があります(Cloudflare Tunnel利用時は通常問題ありません)。

Caution

以下は移行されません。

• 各ユーザーのlisten対象タイムライン設定はリセットされます(ユーザーによる再設定が必要です)
• 既存投稿とActivityPubオブジェクトの対応関係(ap_object_references)は引き継がれません
• also_known_as の設定は引き継がれません
• 鍵はPEMからJWKへ変換されます。変換に失敗したアカウントには新しい鍵が発行され、署名の連続性が失われます(リモートサーバーからの見え方に影響する場合があります)

6-5. ブリッジを再開し、経路を切り替える

v2ブリッジを再開します。ブリッジは起動時に移行済みのフォロー情報を読み込みます。

docker compose -f dualstack/compose.yaml up -d activitypub

ログにエラーがないことを確認したら、v2/etc/config/config.yaml を編集して経路をv1ブリッジからv2ブリッジへ切り替えます。

1. net.concrnt.activitypub ブロックのコメントを外します
2. net.concrnt.legacy ブロックの paths から /ap・.well-known/webfinger・.well-known/nodeinfo・.well-known/host-meta の4つを削除します(残しておくとv1側へのプロキシが優先されます)

編集したら concrnt2 を再起動して設定を反映します。

docker compose -f dualstack/compose.yaml restart concrnt2

動作を確認します。

curl "https://<fqdn>/.well-known/webfinger?resource=acct:<ユーザー名>@<fqdn>"
curl "https://<fqdn>/ap/test"

問題なければv1ブリッジは不要です。停止したうえで、dualstack/compose.yaml の apbridge をコメントアウトに戻してかまいません。

docker compose -f dualstack/compose.yaml stop apbridge

Step 7. 純v2構成へ切り替える

並行運用期間を終えたら、v1を撤去して純v2構成へ移行します。

まず v2/etc/config/config.yaml の net.concrnt.legacy ブロックをコメントアウトに戻します(v2単独構成には gateway が存在しないため、残しておくとレガシーパスへのアクセスがエラーになります)。Step 6でActivityPubブリッジを移行した場合、net.concrnt.activitypub は残したままにし、v2/compose.yaml 側でも activitypub サービスのコメントを外しておきます(ブリッジの設定 v2/etc/ap/config.yaml はそのまま引き継がれます)。そのうえでデュアルスタックを停止し、v2単独構成を起動します。

docker compose -f dualstack/compose.yaml down
docker compose -f v2/compose.yaml up -d

v2のデータ(v2/_composeData)はデュアルスタックと共有しているため、そのまま引き継がれます。

Note

v1/_composeData はしばらく削除せず、バックアップとして保全しておくことをおすすめします。問題がないことを十分に確認してから削除してください。

以降はv2単独での運用となります。招待コードの発行など、日常的な運用コマンドはv2では以下のように実行します。

docker compose -f v2/compose.yaml run --rm concrnt2 conctl generate invite