Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
228 changes: 228 additions & 0 deletions docs/decisions/ADR-12_PostgreSQL_18_and_Data_Directory_Upgrade.md

Large diffs are not rendered by default.

186 changes: 186 additions & 0 deletions docs/decisions/ADR-13_Retiring_Elasticsearch_2_and_MongoDB.md

Large diffs are not rendered by default.

35 changes: 21 additions & 14 deletions docs/decisions/README.md
Original file line number Diff line number Diff line change
@@ -1,15 +1,16 @@
# Decision Records / 決定の記録

> **Summary:** Documents explaining why we chose one way and not another: integration repository placement, network model, staged security gate, AI autonomy and roles, the test IdP, and the wiki-frontend overlay. Each record captures the context, options considered, and final decision.
> **概要:** なぜその道を選び、ほかを選ばなかったかを説明する文書:統合リポジトリの置き場、ネットワーク方式、セキュリティ門の段階化、AI の自律度と役割、テスト IdP、wiki-frontend のオーバーレイ。各記録は文脈、検討した選択肢、最終決定を捉えます。
> **Summary:** Documents explaining why we chose one way and not another: integration repository placement, network model, staged security gate, AI autonomy and roles, the test IdP, the wiki-frontend overlay, native builds of EOL middleware, PostgreSQL 18 with its data upgrade, and the retirement of Elasticsearch 2 and MongoDB. Each record captures the context, options considered, and final decision.
> **概要:** なぜその道を選び、ほかを選ばなかったかを説明する文書:統合リポジトリの置き場、ネットワーク方式、セキュリティ門の段階化、AI の自律度と役割、テスト IdP、wiki-frontend のオーバーレイ、EOL ミドルウェアのネイティブビルド、PostgreSQL 18 とデータの更新、Elasticsearch 2 と MongoDB の退役。各記録は文脈、検討した選択肢、最終決定を捉えます。

**Jump:** [English](#english) · [日本語](#japanese)

- Version / 版: 0.4 — 2026-11-06. **Learned:** a cold start turned an emulation cost into an architecture decision (ADR-07): EOL amd64-only middleware is built natively. / コールドスタートがエミュレーションのコストを設計判断(ADR-07)に変えた。amd64 のみの EOL ミドルウェアはネイティブで組む。
- Version / 版: 0.5 — 2026-11-10. **Learned:** a data-tier change is two records, not one: the PostgreSQL move is proposed with its proof (ADR-12), while the removal of Elasticsearch 2 and MongoDB still needs owner choices (ADR-13); ADR-08 to ADR-11 stay reserved or planned for records on other branches. / データ層の変更は一つでなく二つの記録になる。PostgreSQL の移行は証明つきで提案し(ADR-12)、Elasticsearch 2 と MongoDB の撤去はまだ所有者の選択を要する(ADR-13)。ADR-08〜ADR-11 は他のブランチの記録のために予約・予定のまま残す。
0.4 — 2026-11-06. **Learned:** a cold start turned an emulation cost into an architecture decision (ADR-07): EOL amd64-only middleware is built natively. / コールドスタートがエミュレーションのコストを設計判断(ADR-07)に変えた。amd64 のみの EOL ミドルウェアはネイティブで組む。
0.3 — 2026-11-06. **Learned:** a repository that cannot be built alone because its Dockerfile belongs to another tree is an architecture decision (overlay, not service) and needs its own record (ADR-06). / Dockerfile が別の木に属していて単独で組めないリポジトリは、サービスでなくオーバーレイという設計上の決定であり、独自の記録(ADR-06)が要ると分かった。
0.2 — 2026-11-06. **Learned:** a test fixture that logs people in is an architecture choice like any other service, so it needs its own record (ADR-05) rather than a note in a template. / 人をログインさせる試験用の部品も他のサービスと同じ設計上の選択であり、テンプレートの注記ではなく独自の記録(ADR-05)が要ると分かった。
0.1 — 2026-11-05. **Learned:** writing decisions as records turned subjective choices into objective, reviewable documents that explain the reasoning behind each rule. / 決定を記録として残すことで、主観的な選択を客観的でレビュー可能な文書にし、各ルールの背後にある推論を説明できるようになったと分かった。
- Normative for: [ADR-01 Integration Repository Placement](./ADR-01_Integration_Repository_Placement.md) through [ADR-07 Native Builds of EOL Middleware](./ADR-07_Native_Builds_of_EOL_Middleware.md).
- Normative for: [ADR-01 Integration Repository Placement](./ADR-01_Integration_Repository_Placement.md) through [ADR-07 Native Builds of EOL Middleware](./ADR-07_Native_Builds_of_EOL_Middleware.md), and [ADR-12 PostgreSQL 18 and Data Directory Upgrade](./ADR-12_PostgreSQL_18_and_Data_Directory_Upgrade.md) and [ADR-13 Retiring Elasticsearch 2 and MongoDB](./ADR-13_Retiring_Elasticsearch_2_and_MongoDB.md); ADR-08 to ADR-11 are reserved or planned.
- Related: [../README.md](../README.md) · [policy/](../policy/README.md) · [spec/](../spec/README.md) · [reference/REF-01_Glossary.md](./../reference/REF-01_Glossary.md)

---
Expand All @@ -32,14 +33,17 @@ A *decision record* (ADR) explains why we chose one way and not another. This fo
| ADR-05 | [ADR-05_Test_IdP_for_Shibboleth.md](./ADR-05_Test_IdP_for_Shibboleth.md) | Bundled test IdP for `--auth shibboleth`: our own SimpleSAMLphp image on `php:8.3-apache`, mock attributes prefixed `mock-`. |
| ADR-06 | [ADR-06_Wiki_Frontend_Overlay.md](./ADR-06_Wiki_Frontend_Overlay.md) | wiki-frontend is an overlay of osf.io (`overlay_of`): a bundle-builder image from the merged tree, tagged `<osf_sha12>-<wiki_sha12>`, run once by `wiki_assets` into the volume `wiki_static`; no `wiki` server. |
| ADR-07 | [ADR-07_Native_Builds_of_EOL_Middleware.md](./ADR-07_Native_Builds_of_EOL_Middleware.md) | EOL middleware that only ships amd64 images is built natively for both architectures from the official artefact on a digest-pinned base (`image_build`, MC-15); first Elasticsearch 2.4.6, which took 38 minutes to start under emulation and 5 seconds natively (real install run 19). | Proposed 2026-11-06 |
| ADR-12 | [ADR-12_PostgreSQL_18_and_Data_Directory_Upgrade.md](./ADR-12_PostgreSQL_18_and_Data_Directory_Upgrade.md) | PostgreSQL 9.6 → 18.6 (digest-pinned); md5 host auth until CAS has a SCRAM-capable JDBC driver; `grdm-dev db upgrade` dumps and restores with verification and keeps the old directory, `db rollback` puts it back, `up` refuses a mismatched major (exit 15). Status: Proposed. |
| ADR-13 | [ADR-13_Retiring_Elasticsearch_2_and_MongoDB.md](./ADR-13_Retiring_Elasticsearch_2_and_MongoDB.md) | Measured: osf.io search does not run on ES 6.8 or OpenSearch; search off needs a ~50-line patch; mongo serves only sharejs, whose file-page co-editing is what retirement removes. Retirement steps; owner decisions of 2026-11-10: ES 8 port with full-text search, file-page editor on y-websocket. Status: Proposed. |

Future decision records may cover:
Reserved or planned numbers (no record in this tree yet):

| Topic | Description |
| Number | Topic |
|---|---|
| ADR-07 | Repository branching strategy |
| ADR-08 | Tool version policy (Docker, Python, Node.js) |
| ADR-09 | Open source license compatibility |
| ADR-08 | Reserved: Per-OS Installer Entry Points (on a separate branch) |
| ADR-09 | Planned: repository branching strategy |
| ADR-10 | Planned: tool version policy (Docker, Python, Node.js) |
| ADR-11 | Planned: open source license compatibility |

### 2. Creating a new decision record

Expand Down Expand Up @@ -78,14 +82,17 @@ flowchart TD
| ADR-05 | [ADR-05_Test_IdP_for_Shibboleth.md](./ADR-05_Test_IdP_for_Shibboleth.md) | `--auth shibboleth` 用の同梱テスト IdP:`php:8.3-apache` 上の自前 SimpleSAMLphp イメージ、`mock-` 接頭辞の模擬属性。 |
| ADR-06 | [ADR-06_Wiki_Frontend_Overlay.md](./ADR-06_Wiki_Frontend_Overlay.md) | wiki-frontend は osf.io のオーバーレイ(`overlay_of`):重ねた木から束を組むイメージ(タグ `<osf の sha12>-<wiki の sha12>`)を `wiki_assets` が一度動かしてボリューム `wiki_static` へ写す。`wiki` サーバは無い。 |
| ADR-07 | [ADR-07_Native_Builds_of_EOL_Middleware.md](./ADR-07_Native_Builds_of_EOL_Middleware.md) | amd64 のイメージしか無い EOL ミドルウェアは、公式成果物からダイジェスト固定のベース上に両アーキテクチャ向けにネイティブで組む(`image_build`、MC-15)。まず Elasticsearch 2.4.6。エミュレーションでは起動に 38 分、ネイティブでは 5 秒(実機第 19 回)。 | 提案 2026-11-06 |
| ADR-12 | [ADR-12_PostgreSQL_18_and_Data_Directory_Upgrade.md](./ADR-12_PostgreSQL_18_and_Data_Directory_Upgrade.md) | PostgreSQL 9.6 → 18.6(ダイジェスト固定)。CAS が SCRAM に対応した JDBC ドライバーを持つまでホスト認証は md5。`grdm-dev db upgrade` は照合つきでダンプと復元を行い旧ディレクトリを残し、`db rollback` はそれを戻し、`up` は版の不一致を拒む(終了 15)。ステータス: 提案中。 |
| ADR-13 | [ADR-13_Retiring_Elasticsearch_2_and_MongoDB.md](./ADR-13_Retiring_Elasticsearch_2_and_MongoDB.md) | 測定: osf.io の検索は ES 6.8 でも OpenSearch でも動かない。検索を切るには約 50 行のパッチが要る。mongo は sharejs にしか使われず、退役で失うのはそのファイルページの共同編集である。退役の手順。2026-11-10 の所有者の判断: 全文検索を保つ ES 8 への移植、ファイルページのエディタの y-websocket への移行。ステータス: 提案中。 |

今後の決定記録として以下が考えられます:
予約済み・予定の番号(この木にはまだ記録が無い):

| トピック | 説明 |
| 番号 | トピック |
|---|---|
| ADR-07 | リポジトリのブランチ戦略 |
| ADR-08 | 道具版方針(Docker、Python、Node.js) |
| ADR-09 | オープンソースライセンスの互換性 |
| ADR-08 | 予約: OS ごとのインストーラーの入口(別ブランチ) |
| ADR-09 | 予定: リポジトリのブランチ戦略 |
| ADR-10 | 予定: 道具版方針(Docker、Python、Node.js) |
| ADR-11 | 予定: オープンソースライセンスの互換性 |

### 2. 新しい決定記録をつくるには

Expand Down
7 changes: 4 additions & 3 deletions docs/reference/REF-01_Glossary.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,8 @@

**Jump:** [English](#english) · [日本語](#japanese)

- Version / 版: 0.1 — 2026-11-05. **Learned:** listing every term in one place showed that about a third of them (CAS, SAML, IdP/SP, Shibboleth, GakuNin) belong to one topic — login — and that newcomers stumble there first, so the login terms were written to read as one connected story. / 全部の語を一か所に並べてみると、約三分の一(CAS、SAML、IdP/SP、Shibboleth、GakuNin)が「ログイン」という一つの話題に属し、新入社員はまずそこでつまずくと分かった。そこでログインの語は一つの続いた話として読めるように書いた。
- Version / 版: 0.2 — 2026-11-10. **Learned:** a glossary row that names a version goes stale with the first upgrade, so the PostgreSQL row now names the record that set the version (ADR-12). / 版を書いた用語の行は最初の更新で古くなるので、PostgreSQL の行は版を決めた記録(ADR-12)を示す。
0.1 — 2026-11-05. **Learned:** listing every term in one place showed that about a third of them (CAS, SAML, IdP/SP, Shibboleth, GakuNin) belong to one topic — login — and that newcomers stumble there first, so the login terms were written to read as one connected story. / 全部の語を一か所に並べてみると、約三分の一(CAS、SAML、IdP/SP、Shibboleth、GakuNin)が「ログイン」という一つの話題に属し、新入社員はまずそこでつまずくと分かった。そこでログインの語は一つの続いた話として読めるように書いた。
- Applies to: every document in this repository. Documents still add a short note on first use and link here ([SPEC-06 §3](../spec/06_documentation_conventions.md)). `grdm-dev docs check` uses the **Term** column of the English table as its word list.
- Related: [docs/README.md](../README.md) · [SPEC-00 Overview](../spec/00_overview.md) · [SPEC-01 Manifest](../spec/01_manifest.md) · [SPEC-02 Installer CLI](../spec/02_installer_cli.md) · [SPEC-03 Security Gate](../spec/03_security_gate.md) · [SPEC-04 Acceptance Tests](../spec/04_acceptance_tests.md) · [SPEC-05 Upstream Tracking](../spec/05_upstream_tracking.md) · [POL-01](../policy/POL-01_Developer_Environment_2027_Position.md) · [ADR-01](../decisions/ADR-01_Integration_Repository_Placement.md) · [ADR-02](../decisions/ADR-02_Network_Model.md) · [ADR-03](../decisions/ADR-03_Staged_Security_Gate.md) · [ADR-04](../decisions/ADR-04_AI_Autonomy_and_Roles.md)

Expand Down Expand Up @@ -121,7 +122,7 @@
| rdmcp / MCP | A way for AI assistants to talk to GRDM through a standard plug. | Model Context Protocol server for GRDM (`RDM-rdmcp-private`). | [SPEC-00](../spec/00_overview.md) |
| AIPF | A GRDM data connector for the AI platform (private). | `RDM-aipf_mcp_data_grdm-private`, an MCP data source for GRDM. | [SPEC-00](../spec/00_overview.md) |
| Elasticsearch | The search engine inside GRDM. | ES 2 and 6.3.1 today; consolidated on ES 8 in M5. | [POL-01 §4](../policy/POL-01_Developer_Environment_2027_Position.md) |
| PostgreSQL | The main database where GRDM keeps its records. | PostgreSQL 9.6 today; 15 or later in M5. | [POL-01 §4](../policy/POL-01_Developer_Environment_2027_Position.md) |
| PostgreSQL | The main database where GRDM keeps its records. | PostgreSQL 18 (ADR-12); it was 9.6 until 2026-11. | [POL-01 §4](../policy/POL-01_Developer_Environment_2027_Position.md) |
| MongoDB | An older database GRDM still uses for a few things. | MongoDB 3.4 (sharejs); retired in M5. | [POL-01 §4](../policy/POL-01_Developer_Environment_2027_Position.md) |
| RabbitMQ | The message queue: a line where jobs wait for a worker. | AMQP broker used by Celery workers in osf.io. | [SPEC-00](../spec/00_overview.md) |
| Redis | A very fast memory store used for caching and sessions. | In-memory key-value store used by osf.io and wb/mfr. | [SPEC-00](../spec/00_overview.md) |
Expand Down Expand Up @@ -251,7 +252,7 @@
| rdmcp / MCP | AI アシスタントが標準の差し込み口で GRDM と話す仕組み。 | GRDM 向けの Model Context Protocol サーバ(`RDM-rdmcp-private`)。 | [SPEC-00](../spec/00_overview.md) |
| AIPF | AI 基盤向けの GRDM データ接続部品(非公開)。 | `RDM-aipf_mcp_data_grdm-private`。GRDM の MCP データソース。 | [SPEC-00](../spec/00_overview.md) |
| Elasticsearch | GRDM の中の検索エンジン。 | 現在は ES 2 と 6.3.1。M5 で ES 8 に集約。 | [POL-01 §4](../policy/POL-01_Developer_Environment_2027_Position.md) |
| PostgreSQL | GRDM が記録を保存する主なデータベース。 | 現在は PostgreSQL 9.6。M5 で 15 以降。 | [POL-01 §4](../policy/POL-01_Developer_Environment_2027_Position.md) |
| PostgreSQL | GRDM が記録を保存する主なデータベース。 | PostgreSQL 18(ADR-12)。2026-11 までは 9.6。 | [POL-01 §4](../policy/POL-01_Developer_Environment_2027_Position.md) |
| MongoDB | GRDM が一部でまだ使っている古いデータベース。 | MongoDB 3.4(sharejs 用)。M5 で廃止。 | [POL-01 §4](../policy/POL-01_Developer_Environment_2027_Position.md) |
| RabbitMQ | メッセージの待ち行列。仕事が作業者を待つ列。 | osf.io の Celery ワーカーが使う AMQP ブローカー。 | [SPEC-00](../spec/00_overview.md) |
| Redis | キャッシュやセッションに使う、とても速いメモリの保管庫。 | osf.io と wb/mfr が使うインメモリのキー値ストア。 | [SPEC-00](../spec/00_overview.md) |
Expand Down
Loading
Loading