Skip to content

docs(getting-started): document the MongoDB replica set required from v8.0 - #617

Merged
yuki-takei merged 2 commits into
masterfrom
docs/mongodb-replica-set-in-install-guides
Aug 3, 2026
Merged

docs(getting-started): document the MongoDB replica set required from v8.0#617
yuki-takei merged 2 commits into
masterfrom
docs/mongodb-replica-set-in-install-guides

Conversation

@ayaka0417

@ayaka0417 ayaka0417 commented Aug 3, 2026 •
edited by yuki-takei
Loading

Copy link
Copy Markdown
Contributor

Task

https://redmine.weseek.co.jp/issues/188315

概要

インストールガイドと Cookbook の MONGO_URI の記載例が standalone 構成の MongoDB を指していたため、レプリカセット構成の URI に改めました。あわせて、レプリカセット構成を有効化する手順をインストールガイドへ追加しています。

GROWI v8.0 以降は MongoDB の change stream を利用するため、レプリカセット構成が必須です（v8.0.x へのアップグレード 参照）。ガイドに従うと standalone 構成で構築され、MONGO_URI にもレプリカセットの指定がないため、そのままでは v8.0 以降を動かせない状態でした。

#604 のレビューで「MONGO_URI がレプリカセット運用の URL になっていない。元の記載も変える必要があるかも」とご指摘いただいた、その「元」に当たる修正です。

変更内容

レプリカセット構成の有効化手順を追加（MongoDB を起動した直後の節として挿入）

  • admin-guide/getting-started/ubuntu-server.md（日英）
  • admin-guide/getting-started/almalinux.md（日。英語版は存在しません）

/etc/mongod.conf への replSetName の追記 → mongod の再起動 → rs.initiate() による初期化 → PRIMARY になったことの確認、という流れです。レプリカセット名は growi-docker-compose と同じ rs0 を例にしています。

MONGO_URI の記載例を ?replicaSet=rs0 付きに変更

  • 上記 3 ファイルの「起動確認」
  • admin-guide/admin-cookbook/launch-with-systemd.md（日英）: systemd ユニットの Environment=
  • admin-guide/admin-cookbook/multi-app.md（日英）: 3 アプリ分の MONGO_URI（mongo サービス自体は growi-docker-compose の定義をそのまま使うため、そちらは既にレプリカセット構成です）

前提条件と Node.js / Elasticsearch の記載を v8.0 に追従（レビューでのご指摘を受けて追加）

インストールガイドは Node.js 18/20・MongoDB 4.4 以上を要求する記載のままで、そのまま従うと v8.0 を動かせない環境ができていました。GROWI v8.0 がサポートするのは Node.js v24 系のみ・Elasticsearch v8/v9 系のみで、MongoDB は v6.0 以上が必要です。

  • getting-started/ubuntu-server.md（日英）・almalinux.md（日）の前提条件を Node.js 24.x / npm 11.x / MongoDB 6.0 以上（レプリカセット必須）/ Elasticsearch 8.x or 9.x に更新
  • Node.js のインストールを setup_24.x に変更し、見出しとバージョン確認例（v24.14.0 / 11.9.0 / 11.1.1）も揃えました
  • turbo のグローバルインストール手順を削除。turbo は devDependencies に含まれるため pnpm install で導入されます。あわせて pnpm のバージョンは package.json の packageManager の宣言（v8.0.0 は pnpm@11.1.1）に合わせるよう明記
  • 起動時に ELASTICSEARCH_VERSION=8 を指定するよう追記。本ガイドは Elasticsearch 8.x をインストールしますが、GROWI 側の既定値は 9 なので、指定しないと全文検索の初期化に失敗します。admin-cookbook/launch-with-systemd.md（日英）の Environment の説明にも同じ注意を書きました

変更しなかったもの

  • admin-guide/getting-started/centos.md（日英）: MongoDB 3.6 / node.js 8.x をインストールするページで、そもそも v8.0 を動かせる構成ではありません。standalone 構成の記述として内部で一貫しているため、そのまま残しています。
  • admin-guide/admin-cookbook/env-vars.md の MONGO_URI の既定値（mongodb://localhost/growi）: GROWI 本体の既定値そのものなので変更しません。
  • admin-guide/downgrading/50x-to-45x.md、migration-guide/from-crowi-onpremise.md、upgrading/36x.md: v8.0 より前を対象とした記述です。

追従しなかった範囲（意図的）

ミドルウェアのインストール対象バージョンは据え置きにしています。Elasticsearch は 8.x、MongoDB は 6.0 のままで、どちらも GROWI v8.0 のサポート範囲内です。

  • Elasticsearch を 9.x へ引き上げていない理由: 本ガイドの「TLS の無効化」節は、8.x の既定 elasticsearch.yml に対する literal な unified diff です。9.x 用の同等の diff を実機確認なしに書き換えると、検証していない手順を載せることになります。代わりに ELASTICSEARCH_VERSION=8 の指定を明記して、8.x のままでも正しく動く形にしました。
  • MongoDB を 8.0 へ引き上げていない理由: 6.0 は v8.0 のサポート範囲内かつアップグレードガイドが示す下限です。リポジトリ URL・GPG キー・dnf / dpkg の出力例まで差し替える範囲になるため、別途としました。

いずれも「古いがサポート内」の状態なので、追従は別 PR で扱えます。今回直したのは「そのまま従うと v8.0 が動かない」部分（Node.js のバージョンと ELASTICSEARCH_VERSION の欠落）です。

確認事項

  • pnpm lint（textlint）クリーン。

🤖 Generated with Claude Code

@ayaka0417 @claude
docs(getting-started): document the MongoDB replica set required from…
b6f52fe 
… v8.0

The MONGO_URI examples in the install guides and cookbooks pointed at a
standalone MongoDB, which GROWI v8.0 cannot use because change streams are
only available on a replica set.

- Add a replica set setup step to the Ubuntu Server (JA/EN) and AlmaLinux
  (JA) guides, right after MongoDB is started
- Show ?replicaSet=rs0 in the MONGO_URI examples of those guides, of the
  systemd unit cookbook, and of the multi-app cookbook

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@ayaka0417 ayaka0417 mentioned this pull request Aug 3, 2026
Merged
@ayaka0417 @claude
docs(getting-started): bring the install guide prerequisites up to v8.0
6442931 
GROWI v8.0 supports only Node.js v24 and Elasticsearch v8/v9, and requires
MongoDB v6.0 or later, but the guides still asked for Node.js 18/20 and
MongoDB 4.4. Following them produced an environment that cannot run v8.0.

- Ubuntu Server (JA/EN) and AlmaLinux (JA): state Node.js 24.x, npm 11.x,
  MongoDB 6.0+ with a replica set and Elasticsearch 8.x/9.x, install Node.js
  from setup_24.x, and show the versions those produce
- Drop the global turbo install: turbo is in devDependencies, so pnpm install
  brings it in. Pin the pnpm version to what packageManager declares
- Set ELASTICSEARCH_VERSION=8 when starting against the Elasticsearch 8.x
  these guides install, since GROWI defaults to 9. Note the same in the
  systemd cookbook (JA/EN)

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@yuki-takei
yuki-takei merged commit 08f0b6b into master Aug 3, 2026
1 check passed
@yuki-takei
yuki-takei deleted the docs/mongodb-replica-set-in-install-guides branch August 3, 2026 11:51
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@ayaka0417 @yuki-takei