Skip to content

Latest commit

 

History

History
541 lines (443 loc) · 124 KB

02_installer_cli.md

File metadata and controls

541 lines (443 loc) · 124 KB

SPEC-02 Installer CLI / むンストヌラヌ CLI

Summary: The contract of the optional per-OS prerequisite scripts and of the two entry points that install the GakuNin RDM developer environment: the thin bootstrap installer/install.sh and the Python command grdm-dev with its subcommands, profiles, flags, exit codes, and directory layout. 抂芁: 任意の OS ごずの前提条件スクリプトず、GakuNin RDM 開発環境を導入する二぀の入口、薄い起動スクリプト installer/install.sh ず Python コマンド grdm-dev の契玄。サブコマンド、プロファむル、フラグ、終了コヌド、ディレクトリ構成を定める。

Jump: English · 日本語

  • Version / 版: 0.36 — 2026-11-14. Learned: the two workflows of §10 arrive in their own change, pushed by a token with the workflow scope, so the paragraph that called them pending is removed with it.  §10 の二぀のワヌクフロヌは、workflow スコヌプを持぀トヌクンで push する独立の倉曎で入るので、保留䞭ず曞いた段萜もその倉曎で消す。 0.35 — 2026-11-14. Learned: a guard is only as useful as the moment it runs: the volume check of up was correct on the amd64 VM but fired after a 10 h 45 min build, so install now runs the same read-only check as soon as the Compose file is rendered (DEMO-22 0.7).  怜査が圹に立぀かは、それがい぀動くかで決たる。up のボリュヌムの怜査は amd64 の VM で正しく働いたが、10 時間 45 分の build の埌だった。そこで install は、Compose のファむルを render した盎埌に同じ読み取りだけの怜査を行うDEMO-22 0.7。 0.34 — 2026-11-14. Learned: a health check is a time budget the template fixes, and a slow host can spend all of it on a healthy start: Elasticsearch 8 took 8 min 10 s to start under full-system amd64 emulation while the check allowed 2.5 minutes, so up stopped with exit 40 although nothing was wrong, and up --timeout could not help because it bounds the wait, not the container's own check; the window is now 17 to 26 minutes, ending inside the default 1800 s health wait of up (DEMO-22 0.7).  ヘルスチェックはテンプレヌトが固定した時間の予算で、遅い機械は健党な起動でそれを䜿い切りうる。機械党䜓を amd64 で゚ミュレヌションする環境で Elasticsearch 8 の起動に 8 分 10 秒かかったのに、チェックの蚱容は 2.5 分で、䜕も壊れおいないのに up が終了 40 で止たった。up --timeout は埅ちの䞊限であっおコンテナ自身のチェックではないので助けにならない。窓は 17〜26 分になり、up の既定の健康の埅ち 1800 秒の内に終わるDEMO-22 0.7。 0.33 — 2026-11-13. Learned: a Docker named volume remembers the directory it was bound to on the day it was created, and Compose reuses it without comparing, so a second checkout of the same project opened the first one's data with its own new secrets and osf_init failed on a password after 8 minutes of up; up now compares the rendered bindings with the existing volumes before starting anything (DEMO-21 0.5, run 4).  Docker の名前付きボリュヌムは、䜜られた日に結び付けたディレクトリを芚えおいお、Compose は比べずに再利甚する。そのため同じプロゞェクトの二぀目のチェックアりトは、䞀぀目のデヌタを自分の新しい秘密で開き、osf_init は up の 8 分埌にパスワヌドで倱敗した。up は䜕かを起動する前に、render した結び付けず既存のボリュヌムを比べるようになったDEMO-21 0.5、第 4 回。 0.32 — 2026-11-13. Learned: a command that exists in the code has to be in the contract, or the documents recommend the wrong one: secrets init --missing (add only the absent keys, change nothing live) was implemented for upgrades but the table named only rotate, so ADR-14 told installations to rotate before rendering, which changes every credential and recreates containers from a stale Compose file (PR #56 review r1 R1-02).  コヌドにあるコマンドは契玄にも曞かなければ、文曞が間違ったコマンドを勧める。secrets init --missing足りないキヌだけを足し、皌働䞭のものは䜕も倉えないは曎新のために実装されたが、衚には rotate しかなく、ADR-14 は render の前に rotate を求めおしたった。rotate はすべおの資栌情報を替え、叀い Compose ファむルのたたコンテナを再䜜成するPR #56 レビュヌ r1 R1-02。 0.31 — 2026-11-12. Learned: replacing a component also replaces the contracts around it: Elasticsearch 8 brings a CA, two passwords and a one-shot, retiring sharejs and mongo removes a port, two volumes, a secret and a hardening exception, and osf.io's mandatory sign-in (ENABLE_PUBLIC_ACCESS) becomes a setting of compose render that every osf.io process must share, so the floors, the ports table and the profiles table were all recomputed from the templates instead of edited by hand (ADR-13 §6, ADR-14).  郚品を入れ替えるず、その呚りの玄束も替わる。Elasticsearch 8 は CA、二぀のパスワヌド、䞀回きりの手順を持ち蟌み、sharejs ず mongo の退圹はポヌト䞀぀、ボリュヌム二぀、秘密䞀぀、堅牢化の䟋倖䞀぀を消し、osf.io の必須サむンむンENABLE_PUBLIC_ACCESSは osf.io のすべおのプロセスが共有しなければならない compose render の蚭定になった。そのため䞋限、ポヌトの衚、プロファむルの衚は手で盎さず、テンプレヌトから蚈算し盎したADR-13 §6、ADR-14。 0.30 — 2026-11-11. Learned: a memory requirement inherits the reason it was set for: the 24 GiB for core came from the prebuilt ember-osf-web image rebuilding its bundle at every start under emulation with an 8 GiB floor, so once ember became a static nginx image built from source (128 MiB floor) the figure had to be recomputed from the floors (8320 MiB, about 11.6 GiB) and stated as a computed lower bound, not a measured peak (RDM-ember-osf-web-dev2027 PR #2 review r1 R1-03).  メモリの芁件は、それを決めた理由を匕き継ぐ。core の 24 GiB は、事前ビルド枈みの ember-osf-web のむメヌゞが起動のたびに゚ミュレヌション䞋で䞋限 8 GiB のもず束を組み盎したこずから来おいた。ember が゜ヌスから組む静的な nginx のむメヌゞ䞋限 128 MiBになったので、数字を䞋限の合蚈8320 MiB、玄 11.6 GiBから蚈算し盎し、実枬の最倧倀ではなく蚈算䞊の䞋限ずしお曞く必芁があったRDM-ember-osf-web-dev2027 PR #2 レビュヌ r1 R1-03。 0.29 — 2026-11-12. Learned: a review of PR #50 showed that a number is only as good as its label: the compile-time ratio is an observation, "a working day" is an extrapolation, and --timeout belongs to up alone, so it neither shortens nor extends build; and a report key that "is absent" on macOS must be absent from the report, not empty (PR #50 review r1 R2, R6).  PR #50 のレビュヌで、数字は札の付け方次第だず分かった。コンパむル時間の比は芳察、「1 営業日」は倖挿であり、--timeout は up だけのもので build を短くも長くもしない。たた macOS で「無い」報告のキヌは、空ではなく報告から無くなっおいなければならないPR #50 レビュヌ r1 R2・R6。 0.28 — 2026-11-12. Learned: a fully emulated amd64 machine compiled osf.io's scientific Python about ten times slower than Rosetta did (one RUN step: 55 minutes there, not finished after 5 h 12 min here), so a slow host can need a way to wait longer in up, and a report that says nothing about emulation on amd64 cannot be told from one that did not check: install --timeout goes to up, and doctor prints amd64_emulation (DEMO-22).  amd64 を党䜓゚ミュレヌションする機械は、osf.io の科孊蚈算の Python のコンパむルが Rosetta の玄 10 倍遅かった䞀぀の RUN 手順が Rosetta では 55 分、ここでは 5 時間 12 分埌も未完。そこで遅い機械には up の埅ちを延ばす手段が芁りうる。たた、amd64 で゚ミュレヌションに䜕も觊れない報告は、確かめおいない報告ず区別できない。install --timeout が up に枡り、doctor が amd64_emulation を出すDEMO-22。 0.27 — 2026-11-10. Learned: decoding is not enough if the result passes through $(...), which drops trailing newlines: a mount named host\012 was checked as host, so the decoded name is kept in a variable (PR #44 review r2 R2-01).  埩号しおも結果が $(...) を通るず末尟の改行が萜ちる。host\012 ずいう mount が host ずしお調べられたので、埩号した名前は倉数に保぀PR #44 レビュヌ r2 R2-01。 0.26 — 2026-11-10. Learned: a path check must read the path the way the system means it: the kernel escapes spaces in mount points (\040) and a symlink can carry a checkout onto the Windows disk, so the shared-folder check decodes mount fields and the WSL checks compare physical paths (pwd -P) (PR #44 review r1 R1, R2).  パスの怜査は、システムが意味するずおりにパスを読たなければならない。カヌネルは mount 先の空癜を \040 ず゚スケヌプし、シンボリックリンクはチェックアりトを Windows のディスクぞ運びうる。そこで共有フォルダの怜査は mount の欄を埩号し、WSL の怜査は実䜓のパスpwd -Pで比べるPR #44 レビュヌ r1 R1・R2。 0.25 — 2026-11-10. Learned: a change can be blocked by the permission needed to publish one part of it: the token that pushes this repository may not change .github/workflows/, so the two workflows of §10 wait on branch feat/per-os-installers while the scripts, fixes and records land now.  倉曎の䞀郚を公開する暩限が無いために党䜓が止たるこずがある。このリポゞトリに push するトヌクンは .github/workflows/ を倉えられないので、§10 の二぀のワヌクフロヌはブランチ feat/per-os-installers で埅ち、スクリプト・修正・蚘録は先に入れる。 0.24 — 2026-11-10. Learned: a real Linux run disproves what a dry run cannot: Ubuntu 24.04's own qemu-user-static crashes inside an amd64 build after 48 minutes, QEMU builds ember about twice as slowly as Rosetta so the 1800 s wait stops a healthy install, and the cloud image lacks a library Playwright's driver needs; so emulation comes from a digest-pinned image, doctor refuses the measured-bad emulator, up waits longer on Linux arm64, and the accept hint names the Linux packages (DEMO-21).  実際の Linux での実行は dry run には分からないこずを芆す。Ubuntu 24.04 自身の qemu-user-static は 48 分埌に amd64 のビルドの䞭で萜ち、QEMU は ember の組み立おに Rosetta のおよそ 2 倍かかるので 1800 秒の埅ちは健党な導入を止め、クラりドむメヌゞには Playwright のドラむバヌが芁るラむブラリが無い。そこで゚ミュレヌションはダむゞェストで固定したむメヌゞから入れ、doctor は萜ちるず実枬した゚ミュレヌタヌを拒み、up は Linux arm64 では長く埅ち、accept の案内は Linux のパッケヌゞを瀺すDEMO-21。 0.23 — 2026-11-10. Learned: a prerequisite is whatever the whole install sequence needs, not only its first step: Trivy and gitleaks are missing on a fresh host and stop an otherwise good install with exit 51 at scan, so the per-OS scripts of §2.3 provide them (ADR-08).  前提条件ずは最初の段ではなく䞀連の導入党䜓に芁るものである。新しいホストには Trivy ず gitleaks が無く、ほかが良くおも scan で終了 51 になるため、§2.3 の OS ごずのスクリプトがそれらを甚意するADR-08。 0.22 — 2026-11-10. Learned: a lock that only the db commands take does not stop up from starting the server between their checks and their renames, so up and reset take it too (PR #42 review r2).  db のコマンドだけが取るロックでは、その確認ず改名の間に up がサヌバヌを起動するのを止められないので、up ず reset も同じロックを取るPR #42 レビュヌ r2。 0.21 — 2026-11-10. Learned: a command that renames data directories needs a journal, a lock and a recovery path that every later command runs, not only checks before it starts (PR #42 review r1).  デヌタディレクトリを改名するコマンドには、始める前の確認だけでなく、操䜜蚘録・ロック・埌続のすべおのコマンドが通る埩旧の道が芁るPR #42 レビュヌ r1。 0.20 — 2026-11-10. Learned: a new database major needs a command, not a note: a server refuses a data directory of another major, so up now says so with exit 15 and db upgrade moves the data by a verified dump and restore that never writes the old directory (ADR-12).  デヌタベヌスの新しい版には泚蚘でなくコマンドが芁る。サヌバヌは別の版のデヌタディレクトリを拒むので、up はそれを終了 15 で告げ、db upgrade は旧ディレクトリに䞀床も曞かない、照合぀きのダンプず埩元でデヌタを移すADR-12。 0.19 — 2026-11-10. Learned: a fixed client is only as good as the address and trust anchor it is given: osf.io's mongo URL was never rendered and fell back to PostgreSQL's host and port, so osf.env now names the TLS URL and the CA file.  盎したクラむアントも、枡される接続先ず信頌の起点しだいである。osf.io の mongo の URL は䞀床も描画されず、PostgreSQL のホストずポヌトに萜ちおいたので、osf.env に TLS の URL ず CA ファむルを曞くこずにした。 0.18 — 2026-11-10. Learned: a build record says what was built, not what should run: after the pin of osf.io moved, compose render ran before build and the stack silently ran the old image, so render now trusts the record only when it equals the manifest pin and otherwise renders the pin and warns with the fix.  ビルドの蚘録は䜕を組んだかを瀺すだけで、䜕を動かすべきかは瀺さない。osf.io の固定が動いた埌、build より前に compose render を実行したため、スタックは叀いむメヌゞを黙っお動かした。そこで render は蚘録が manifest の固定ず䞀臎するずきだけそれを信じ、違うずきは固定を曞いお察凊を添えお譊告するこずにした。 0.17 — 2026-11-10. Learned: a flag that changes what a server will serve belongs in the operating contract, not only in a template and a PR body, so the admin app's --insecure is now stated as a development-only, loopback-only exception (PR #40 review r1 R1-02).  サヌバヌが配信するものを倉えるフラグは、テンプレヌトや PR 本文だけでなく運甚の契玄に曞く。そのため管理画面の --insecure を、開発専甚でルヌプバック限定の䟋倖ずしお明蚘したPR #40 レビュヌ r1 R1-02。 0.16 — 2026-11-10. Learned: the browser opens the wiki and file-editor sockets itself, so y_websocket and sharejs need loopback ports like any other page the browser loads.  wiki ずファむル線集の゜ケットはブラりザが自分で開くため、y_websocket ず sharejs にも、ブラりザが読む他のペヌゞず同じくルヌプバックのポヌトが芁る。 0.15 — 2026-11-10. Learned: a byte count does not make a key usable by its consumer: a manually written key may be 43 ! or 32 quoted spaces, so every CAS key must also be in the base64url alphabet, must not be a published default, and the TGC encryption key must decode canonically to 32 bytes (PR #39 review r1 R1-01).  バむト数だけでは、鍵が䜿う偎で䜿えるずは蚀えない。手で曞いた鍵は感嘆笊 43 個や匕甚笊で囲んだ空癜 32 個でありうる。そこで CAS の鍵はすべお base64url の文字に限り、公開された既定倀を拒み、TGC の暗号鍵は 32 バむトぞ正準に埩号できなければならないPR #39 レビュヌ r1 R1-01。 0.14 — 2026-11-10. Learned: a key name that nothing reads looks exactly like a working secret, and a service that fails closed turns a wrong length into a stopped stack, so the keys now carry the names the image reads and compose render refuses a wrong length before anything starts (ADR-07 §7).  誰も読たないキヌの名前は、効いおいる秘密ずたったく同じに芋える。たた閉じお倱敗するサヌビスでは長さの誀りがスタックの停止になる。そこでキヌにはむメヌゞが読む名前を䜿い、compose render が起動前に誀った長さを拒むようにしたADR-07 §7。
  • Version / 版: 0.13 — 2026-11-10. Learned: a writable root says nothing about what lies beneath it, and a probe must never reuse a name that may already exist: the access check walks existing data as the real uid and creates its file exclusively (PR #36 review r3).  ルヌトに曞けおも䞋のものに぀いおは䜕も分からず、確認甚のファむルは既にあるかもしれない名前を䜿っおはならない。そこでアクセス確認は実際の uid で既存のデヌタを蟿り、ファむルは排他的に䜜るず分かったPR #36 レビュヌ r3。
  • Version / 版: 0.12 — 2026-11-10. Learned: a path check expires when the path changes and sees only what it looks at, and a command that exits 0 has not proved its effect: so reset revalidates at each step using the mount table, ownership is read back, and only a write as the real uid shows that a volume is usable (PR #36 review r2).  パスの怜蚌はパスが倉われば叀くなり、芋たものしか分からない。たた終了 0 のコマンドは効果を蚌明しない。そこで reset は段ごずに mount 衚で再怜蚌し、所有者は読み返し、ボリュヌムが䜿えるこずは実際の uid での曞き蟌みだけが瀺すず分かったPR #36 レビュヌ r2。
  • Version / 版: 0.11 — 2026-11-10. Learned: a root process without capabilities still obeys file permissions, a container path does not confine the host path behind its bind mount, and a repair that trusts its top directory cannot finish a partial one; so volume paths are validated on the host, unoconv holds DAC_OVERRIDE for the shared directory, ownership is re-walked every time, and availability questions are asked of the filesystem or the engine rather than guessed from a path (PR #36 review r1).  capability を陀いた root もファむル暩限に埓い、コンテナ内のパスは bind 元のホストパスを限定せず、䞀番䞊のディレクトリを信甚する修埩は途䞭で止たった修埩を完了できない。そこでボリュヌムのパスはホスト偎で怜蚌し、unoconv は共有ディレクトリのために DAC_OVERRIDE を持ち、所有者は毎回党䜓を蟿り、可吊はパスから掚枬せずファむルシステムや゚ンゞンに問うず分かったPR #36 レビュヌ r1。
  • Version / 版: 0.10 — 2026-11-10. Learned: a check that fails after a 30-minute build teaches nothing, so doctor must prove every prerequisite up front: private repositories, scanners, memory floors, emulation and a checkout path Docker can see; and a fresh bind directory belongs to the host user, so ownership is one generic step derived from the writers instead of one init container per volume, while reset needs a container to delete what containers own (cross-OS audit, 2026-11-10; on Colima a bind mount from /private/tmp was measured to be silently empty).  30 分のビルドの埌で倱敗する怜査は䜕も教えない。だから doctor が非公開リポゞトリ、スキャナヌ、メモリの䞋限、゚ミュレヌション、Docker から芋える配眮先をすべお先に蚌明しなければならない。たた新しい bind ディレクトリはホストの利甚者の所有なので、所有者の蚭定はボリュヌムごずの init コンテナではなく曞き手から導く䞀぀の汎甚の段にたずめ、reset はコンテナが所有するものをコンテナで消さねばならないず分かったOS 暪断の監査、2026-11-10。Colima では /private/tmp からの bind mount が黙っお空になるこずを実枬。 0.9 — 2026-11-10. Learned: a retired credential key stays in runtime/.env forever unless it is dropped explicitly, and a Compose file rendered before the key was retired still refers to it, so compose render must run before secrets rotate or a recreate after an upgrade (PR #35 review r1).  廃止した資栌情報のキヌは明瀺的に消さなければ runtime/.env に残り続け、廃止前に生成した Compose ファむルはそのキヌを参照し続ける。曎新埌は secrets rotate や再䜜成の前に compose render が必芁ず分かったPR #35 レビュヌ r1。 0.8 — 2026-11-06. Learned: a stack that builds is not a stack that starts: a fresh database needs a one-shot initialisation (osf_init), Compose's short tmpfs is root-only, the memory budget must respect the Docker VM, and a prebuilt SPA must be built once into a volume rather than at every start under emulation (real install runs 9–13).  組めるスタックは起動するスタックではない。新しいデヌタベヌスには䞀回限りの初期化osf_initが芁り、Compose の短い tmpfs は root 専甚で、メモリ予算は Docker VM を尊重しなければならず、prebuilt の SPA ぱミュレヌション䞋で毎回組むのではなくボリュヌムぞ䞀床組む実機第 9〜13 回。 0.7 — 2026-11-06. Learned: a service row in the profile table must correspond to a process that exists, so the overlay repository wiki-frontend is represented by a one-shot wiki_assets that fills a named volume and its readers wait with condition: service_completed_successfully (ADR-06), while a template command must have $ escaped as $$ for Compose (PR #30 review r1); and, independently, a glossary term is only explained for the reader when its note and REF-01 link sit at the first prose use, counting lower-case and plural forms, so first-use notes with links were added in both halves (SPEC-06 §3).  プロファむル衚のサヌビス行は実圚するプロセスに察応しおいなければならないため、オヌバヌレむである wiki-frontend は名前付きボリュヌムを満たす䞀回限りの wiki_assets で衚し、それを読むサヌビスは condition: service_completed_successfully で埅぀ADR-06。たたテンプレヌトの command は Compose 向けに $ を $$ に゚スケヌプするPR #30 レビュヌ r1。たた別に、甚語泚ず REF-01 ぞのリンクは、小文字や耇数圢も含めた本文の初出に眮かなければ読者に届かないず分かったため、英和䞡方の初出にリンク付きの甚語泚を補ったSPEC-06 §3。
  • Version / 版: 0.6 — 2026-11-06. Learned: a command in a template is written for the container shell, but Compose interpolates $VAR in every string of the file first, so the renderer must escape $ as $$ and a test must run the rendered file through Compose's own parser; and a fresh bind volume belongs to the host user, so a non-root writer needs an owner step (PR #30 review r1).  テンプレヌトの command はコンテナのシェル向けに曞くが、Compose はファむル䞭の党文字列の $VAR を先に展開する。だから出力偎で $ を $$ に゚スケヌプし、詊隓は出力ファむルを Compose 自身の解析噚に通さねばならない。たた新しい bind ボリュヌムはホストの利甚者の所有なので、非 root の曞き手には所有者を決める段が芁るPR #30 レビュヌ r1。 0.5 — 2026-11-06. Learned: a service row in the profile table must correspond to a process that exists: wiki had none, because the wiki-frontend repository is an overlay whose image only builds a webpack bundle (real install run 4, ADR-06); the honest row is a one-shot wiki_assets that fills a named volume, and the services that read the volume must wait for it with condition: service_completed_successfully.  プロファむル衚のサヌビス行は実圚するプロセスに察応しおいなければならないず分かった。wiki には無かった。wiki-frontend リポゞトリは webpack の束を組むだけのむメヌゞを持぀オヌバヌレむだからである実機第 4 回、ADR-06。正盎な行は名前付きボリュヌムを満たす䞀回限りの wiki_assets で、ボリュヌムを読むサヌビスは condition: service_completed_successfully でそれを埅たねばならない。
  • Version / 版: 0.5 — 2026-11-06. Learned: a glossary term is only explained for the reader when its note and REF-01 link sit at the first prose use, counting lower-case and plural forms, so first-use notes with links were added in both halves (SPEC-06 §3).  甚語泚ず REF-01 ぞのリンクは、小文字や耇数圢も含めた本文の初出に眮かなければ読者に届かないず分かったため、英和䞡方の初出にリンク付きの甚語泚を補ったSPEC-06 §3。 0.4 — 2026-11-06. Learned: an operational failure that only a module docstring describes is invisible to the shell wrapper and to the Japanese message table, so every new failure cause of a subcommand needs its own row in messages.tsv and in this table before the code may return it (PR #23 review r1, U4: upstream returned 1 with no canonical entry).  モゞュヌルの docstring にしか曞かれおいない運甚䞊の倱敗は、シェルの包み玙にも日本語の文蚀衚にも芋えない。サブコマンドの新しい倱敗原因は、コヌドがその番号を返す前に messages.tsv ずこの衚に行を持たなければならないず分かったPR #23 レビュヌ r1、U4: upstream が正本に無い 1 を返しおいた。 0.3 — 2026-11-05. Learned: secrets rotate had to become a coordinated database-password change plus container recreation, because restart keeps the old environment and leaves the captured credential valid (PR #21 review r1).  restart は旧い環境を保぀ため、捕られた資栌情報が有効なたた残る。secrets rotate は DB パスワヌドの倉曎ずコンテナ再䜜成を束ねた手順にする必芁があるず分かったPR #21 レビュヌ r1。 0.2 — 2026-11-05. Learned: a profile table and the acceptance criteria that depend on it must change together, and a TOON row whose text contains a comma or a colon must be quoted or the parser sees extra columns.  プロファむル衚ず、それに䟝存する受入基準は同時に倉えなければならず、カンマやコロンを含む TOON の行は匕甚笊で囲たないず列が増えお解析に倱敗するず分かった。
  • Version / 版: 0.1 — 2026-11-05. Learned: keeping the shell part to a bootstrap and putting every decision in one Python command is the only way to make the OS differences, the manifest check, and the reports testable with unittest.  シェルは起動だけに留め、刀断をすべお䞀぀の Python コマンドに集めないず、OS の違い・manifest の敎合・報告曞を unittest で詊隓できないず分かった。
  • Normative for: installer/install.sh, installer/install-ubuntu.sh, installer/install-macos.sh, installer/install-windows.ps1, installer/prereq-lib.sh, .github/workflows/installer-prereq-lint.yml, .github/workflows/installer-full.yml, .github/scripts/Test-PowerShellSyntax.ps1, installer/grdm_dev/, installer/tests/, runtime/.
  • Related: SPEC-00 Overview · SPEC-01 Manifest · SPEC-03 Security Gate · SPEC-04 Acceptance Tests · SPEC-05 Upstream Tracking · SPEC-06 Documentation Conventions · ADR-02 Network Model · ADR-03 Staged Security Gate · ADR-08 Per-OS Installer Entry Points · POL-01 Position · docs/README.md

English

→ 日本語版ぞ

1. Scope and goal

The installer turns a fresh checkout of this repository into a running GakuNin RDM (GakuNin is Japan's academic network for logging in with a university account; see REF-01) developer environment with one command, on the hosts listed in §8. install.sh and grdm-dev never need sudo (a way to run a command as the computer's administrator), never change network settings on the host, and can be run again at any time without harm. Everything they create lives under runtime/, which is ignored by Git. The optional prerequisite scripts of §2.3 prepare the host beforehand and may use sudo, but only after showing the change and receiving consent (ADR-08).

Glossary notes. An installer is a program that prepares other programs so they can run. A CLI (command line interface) is a program you drive by typing commands. A container is a box that holds one program and everything it needs, so it runs the same on any computer. Docker (the tool that builds images and runs containers; see REF-01) and its companion Docker Compose (see REF-01) run them; Compose is the tool that starts many containers together from one description file. A manifest is the list that says exactly which version of each source repository we use (SPEC-01).

2. Entry points

There are two entry points that install the environment (§2.1, §2.2), and optional scripts that prepare a host for them (§2.3).

2.1 installer/install.sh — thin bootstrap

install.sh does four things and nothing else:

  1. Runs with the bash that ships with macOS (version 3.2), so it uses no feature newer than that: no associative arrays, no mapfile, no ${var,,}.
  2. Finds python3 and checks that it is 3.11 or newer. If not, it prints how to install one for the detected OS and exits with code 10.
  3. Creates a virtual environment (a private folder of Python and its libraries, separate from the system) at .venv/ and installs the installer/ package into it with pip install -e installer[scan] (the scan extra brings Semgrep, which grdm-dev scan runs locally — SPEC-03 §4.2, real install run 17; GRDM_WITHOUT_SCAN=1 leaves it out, GRDM_WITH_ACCEPT=1 adds Playwright).
  4. Hands every argument to .venv/bin/grdm-dev install "$@" and exits with that command's exit code.

OS differences are not written in install.sh. They live in installer/grdm_dev/host.py. User-facing messages come from installer/grdm_dev/messages.tsv (one line per code, English and Japanese columns) so that the script and the Python command say the same thing.

flowchart TD
  A[./installer/install.sh --yes] --> B{python3 >= 3.11?}
  B -- no --> X10[exit 10: how to install Python]
  B -- yes --> C[create .venv/ and pip install -e installer[scan]]
  C --> D[grdm-dev doctor]
  D -- unsupported host --> X10b[exit 10]
  D -- Docker missing --> X11[exit 11]
  D -- prerequisite missing --> X13[exit 13]
  D -- scanner missing --> X51[exit 51]
  D --> E[grdm-dev plan]
  E -- manifest invalid --> X20[exit 20]
  E --> F[grdm-dev secrets init]
  F --> G[grdm-dev compose render]
  G --> H[grdm-dev build]
  H -- failed --> X30[exit 30]
  H --> I[grdm-dev up]
  I --> J[grdm-dev health --network]
  J -- failed --> X40[exit 40]
  J --> K[grdm-dev scan]
  K -- gate failed --> X50[exit 50]
  K --> L[grdm-dev report]
  L --> Z[exit 0 and print URL http://127.0.0.1:5000]
Loading

2.2 grdm-dev — the Python command

grdm-dev is the package installer/grdm_dev/, exposed as a console script. Rules:

  • Standard library first. The command itself has no third-party dependency. The manifest is JSON (read with json), the host is read with platform, shutil, socket, and subprocess, and the generated Compose file is written as JSON, which Docker Compose accepts because JSON is valid YAML (a plain-text data format that uses indentation; see REF-01). PyYAML is therefore not required.
  • Optional extra accept. pip install -e "installer[accept]" adds pytest, pytest-playwright, and playwright. Only grdm-dev accept imports them (SPEC-04).
  • External tools are called as subprocesses and checked by doctor: docker (27 or newer) with the Compose plugin (v2 or newer) and buildx (Docker's helper that builds one image for several kinds of computer; see REF-01), trivy, gitleaks, and semgrep for scan, the OWASP ZAP (a tool that pokes at a running website the way an attacker would; see REF-01) container image for scan --dynamic, and mkdocs for docs. A missing scanner makes scan exit 51 (SPEC-03 §8).
  • Every subcommand supports --json, which prints the same report as machine-readable JSON instead of TOON (a compact text form of JSON, see SPEC-06 §4).

2.3 Per-OS prerequisite scripts

These scripts prepare a host and then run install.sh. The reason for them is in ADR-08. They hold no installation logic, so install.sh and grdm-dev still make every decision.

Script Host What it can provide
installer/install-ubuntu.sh Ubuntu 24.04 amd64 or arm64; Ubuntu 24.04 inside WSL2 apt packages (git, Python, python3-venv, curl, gnupg), Docker Engine with the Compose and buildx plugins from Docker's signed apt repository, docker group membership, amd64 emulation on arm64 (QEMU registered from the digest-pinned tonistiigi/binfmt image, replacing Ubuntu's qemu-user-static 8.2.2, which crashed in a real build: DEMO-21), Trivy and gitleaks in ~/.local/bin, and libatomic1 when GRDM_WITH_ACCEPT=1. Inside WSL2 it skips Docker Engine and requires Docker Desktop.
installer/install-macos.sh macOS on Apple Silicon Homebrew formulae ([email protected], git, Trivy, gitleaks); starts an installed Docker Desktop. It detects Docker Desktop, OrbStack and Colima, and installs neither a Docker runtime nor Homebrew.
installer/install-windows.ps1 Windows 11 amd64 WSL2 and the Ubuntu-24.04 distribution; checks Docker Desktop and its WSL integration; clones this repository under the WSL home directory, never /mnt/c; then runs install-ubuntu.sh inside WSL.

Rules that every script keeps:

  • It shows what it will change, and asks before any sudo or administrator action. Joining the docker group is asked separately.
  • --yes (-Yes in PowerShell, which also accepts --yes) gives consent. Without a terminal and without --yes it stops with exit 2, as in §7.
  • --dry-run (-DryRun) detects and prints the plan and changes nothing.
  • It can be run again: a prerequisite that is already present is skipped.
  • It stops with a clear message on failure and uses only the exit codes 2, 10 and 11 of §6.
  • A download is accepted only through a signed source or a pinned checksum, and nothing is piped into a shell.
  • It never asks for, reads or stores a token. It only says how to give git access to the private integration repositories.
  • Its last action is installer/install.sh, with every other argument passed unchanged.

3. Subcommands

Subcommand Contract Touches Docker
doctor Detects OS (macOS, Ubuntu, WSL2), CPU (arm64, amd64), memory, free disk, Docker ≥ 27, Compose plugin (v2 or newer), buildx, and proves what install needs so a problem appears before the long build: git; read access to the profile's private integration repositories, with git ls-remote that can never prompt (its output is never printed, a URL can hold a token); trivy, gitleaks and semgrep; the profile's memory floors against the smaller of the host and the Docker VM (--memory-gib turns this into a warning, a knowing overcommit); amd64 emulation (binfmt) on Linux arm64 only, printing the command that enables it, and the report line amd64_emulation (not needed (host is amd64) on amd64, ready (...) on Linux arm64 with a working handler, absent on macOS), and refusing an emulator build measured to crash (Ubuntu 24.04's qemu-user-static 8.2.2, read from the registered interpreter's --version), printing the command that replaces it; a checkout Docker can use: on WSL2 a filesystem that keeps a chmod 0600 read back from a test file (a Windows drive cannot hold runtime/.env at 0600); on macOS one the engine can see, asked by bind-mounting it read-only into the postgres image that up needs (the only image this subcommand may pull; a mount the engine refuses or that comes up empty is exit 13, a probe that could not run is a warning) because a bind mount from a path the Docker VM does not share is silently empty, with GRDM_DOCKER_SHARED=1 to skip the question when it cannot be run. Prints a TOON report. Exit 10 if the host is unsupported or the memory floors do not fit, 11 if Docker is missing or not running, 13 if a prerequisite is missing, 51 if a scanner is missing. read-only
plan Resolves manifest + profile and prints which images would be built and which services started, with the published ports (§4). Changes nothing. Exit 20 if the manifest fails SPEC-01 checks. no
secrets init / secrets rotate init writes random secrets (database passwords, Django secret key, CAS keys) into runtime/.env with file mode 0600. Never writes a default or example password. Refuses to overwrite an existing file unless --force. init --missing is the upgrade for a runtime/.env that predates a new key (ELASTIC8_PASSWORD, ELASTIC8_OSF_PASSWORD, ADR-14): it keeps every existing value (passwords that live data depends on stay valid), adds only the absent keys, drops retired keys, changes no live password and needs no running stack; it cannot be combined with --force. rotate is not an upgrade step. It regenerates every secret, changes the live PostgreSQL and RabbitMQ passwords, recreates the containers so they receive the new environment, and verifies that the old credentials are rejected; any failure restores the previous runtime/.env and exits 40. init --force and rotate drop retired credential keys. After an upgrade, run compose render before rotate or any recreate, because a previously rendered Compose file still refers to retired keys. Four keys have lengths the CAS image needs: TGC_ENCRYPTION_KEY is 43 characters, TGC_SIGNING_KEY is 86 characters, OSF_API_INSTITUTIONS_AUTH_JWESECRET is exactly 32 bytes and OSF_API_INSTITUTIONS_AUTH_JWTSECRET is at least 32 bytes; the last two are also osf.io's JWE_SECRET and JWT_SECRET (ADR-07 §7). All four use only the base64url characters A–Z, a–z, 0–9, - and _ (no whitespace, quotes or padding), must not be a published default, and TGC_ENCRYPTION_KEY must decode canonically to 32 bytes. Used after a red-team capture (SPEC-03 §6). no / yes
compose render Exits 2, naming the keys only, when runtime/.env lacks a generated key or holds a CAS key that CAS cannot use: wrong length, characters outside base64url, or a published default (a missing key: secrets init --missing; an unusable CAS key: secrets rotate). Writes runtime/docker-compose.yml from manifest + profile: the internal network grdm plus the publishing-only grdm-edge (--egress <services> attaches more, recorded in runtime/.env; SPEC-03 §3.2), per-component platform: from the manifest's build_platform, ports published only on 127.0.0.1 (§4), non-root user: for every service, read_only, cap_drop, and resource limits (mem_limit, cpus, pids_limit) scaled from the smaller of the host memory doctor detected and the Docker engine's VM memory (docker info; on Docker Desktop the VM is a fraction of the host, real install run 10), where a template's mem_min_mb floor takes its share first and the others divide the rest, and from the CPU count the engine reports (docker info; the host's only when that is unknown), with per-service exceptions from manifest/hardening.json (SPEC-03 §3.3), platform: chosen from doctor, named volumes mapped under runtime/volumes/, every tmpfs entry mounted with mode=1777 (Compose's short form gives root-only 0755, real install run 11), and the placeholders {{HOST_PORT:<service>}}, {{CONTAINER_PORT:<service>}} and {{AUTH_URL}} (fakecas's published URL, or web's when --auth shibboleth replaces fakecas) resolved in template values. The image: of a built component carries the tag of the last build (runtime/reports/build_latest.json) only when it equals the tag the manifest pins; a recorded build that differs from the pin is stale (the pin moved after the last build), so the pinned tag is rendered instead, the report lists the component under stale_build_tags (component, pinned, recorded, image), and stderr prints a warning block whose fix is grdm-dev build, then grdm-dev up. Render still exits 0 because install renders before it builds; an image that was never built makes up fail instead of running the old one. A component the manifest does not pin keeps the recorded tag. osf.env names osf.io's connection to Elasticsearch 8 (ELASTIC_URI=https://elasticsearch8:9200, ELASTIC_CA_CERTS=/es-ca/ca.crt; the user grdm_osf and its password come from the service environment), its internal URL for y-websocket (Y_WEBSOCKET_INTERNAL_URL) and ENABLE_PUBLIC_ACCESS; web, api, admin, worker and osf_init mount elasticsearch8_ca (only the public certificate) read-only. `--public-access true false(default:GRDM_ENABLE_PUBLIC_ACCESSinruntime/.env, else false) sets ENABLE_PUBLIC_ACCESSfor every osf.io process (RDM-osf.io-dev2027 PR #8):falserequires authentication for every data route (anonymous requests get a redirect to the login or 401; signed WaterButler and MFR callbacks, webhooks and the like keep working),trueallows anonymous viewing of public projects; the choice is recorded inruntime/.envand kept on later renders, like--egress`. Follows ADR-02.
build Builds images with docker buildx. The platform is, in order of precedence, --platform, the component's build_platform in the manifest (for example linux/amd64 for components whose EOL base cannot be built for arm64, run under emulation), otherwise the host platform; the image is loaded locally. A component with prebuilt_image (SPEC-01) is not built: the digest-pinned image is pulled once per requested platform and reported as prebuilt (pull-failed → exit 30). With --push a prebuilt image is never re-published to ghcr.io/rcosdp (it is a third party's artefact); the row is reported as prebuilt-not-pushed with pushed: false. --push pushes the multi-arch manifest to ghcr.io/rcosdp/<name> (private). Exit 30 on failure. yes
up / down / reset up first finishes or rolls back an interrupted db operation, then stops with exit 15 when runtime/volumes/postgres_data was written by another PostgreSQL major than the rendered image or its major cannot be read (ADR-12), otherwise starts the profile and waits for health. Before the database check, up stops with exit 13 when a volume grdm-dev_<name> of the rendered file already exists in Docker and is bound to another directory than this checkout's runtime/volumes/<name> (a new clone or a moved directory of the same project: Docker keeps the options of the day the volume was created and Compose reuses it without comparing, so this checkout would open the other one's data with its own new secrets); nothing is started or deleted, and the message names the volumes and the commands that release them (grdm-dev down in the other checkout, then docker volume rm <names>, which leaves the files on disk). down stops containers and keeps volumes; reset stops and deletes runtime/volumes/ after a confirmation (skipped by --yes), emptying it through a root container with only DAC_OVERRIDE and FOWNER, because on Linux the files belong to the containers' uids and the host user cannot remove them. Before anything is stopped or deleted the paths are validated on the host: a symlinked runtime/ or volumes root, a root that resolves outside the checkout, a symlinked volume, or any mount at runtime/, at the volumes root or at any depth inside it (read from the host mount table, so same-filesystem bind mounts count; an unreadable table also refuses) stops with exit 14. reset repeats this after down and after the wipe, and stops if the volumes root has become a different directory. compose render and up apply the same validation with exit 13, because the owner step also runs as root against these paths. These are snapshots: Docker resolves the bind later and no check can close that window, so the checkout is assumed not to be changed concurrently by another user or process. yes
db status / db upgrade / db rollback / db recover status prints the PostgreSQL major of runtime/volumes/postgres_data and of the rendered postgres image and changes nothing. upgrade (all services stopped, after a confirmation that --yes skips) moves the data to the rendered major by dump and restore: the old major runs on the old directory with no network, the new major's pg_dumpall writes runtime/backups/postgres-<old>-to-<new>-<timestamp>/, a new directory is initialised and restored with ON_ERROR_STOP, every table's row count and sequence value is compared, and only then is the old directory renamed postgres_data.pg<old>-<timestamp> beside the new one. rollback puts that directory back. Both hold an exclusive lock, which up and reset also take for their checks and their start or deletion, and write a durable journal (runtime/db-operation.json) before they create or rename anything; recover, and first every later db command, reset and up, finish or roll back an operation that a crash or an interrupt left behind, and a free-disk estimate is checked before the old server starts. Exit 15 on failure, with the old or the new cluster usable, or with the journal kept when a compensating rename also failed. See ADR-12. yes
health Checks every service's health endpoint: an HTTP GET on the published loopback port (/ for most services; /login/ for web, because osf.io's / proxies to ember and answered 500 while the former prebuilt ember was still building — real install run 14; /healthz for ember_osf_web, where only HTTP 200 counts); a one-shot counts as healthy once it has exited 0. With --network, also lists listening sockets on the host and fails (exit 40) if any container port is bound to a non-loopback address, or if a wildcard listener on a project port has no visible owner (fail closed). A named host program that is not Docker on a project port (macOS AirPlay Receiver on *:5000, real install run 16) is reported as a foreign-listener warning, not a failure: it is not our leak, and GRDM_PORT_<SERVICE> in runtime/.env moves our port. read-only
scan Runs the whole security gate of SPEC-03: baseline controls, Trivy SBOM (software bill of materials: the list of all parts inside an image) and CVE list, gitleaks, Semgrep, and OWASP ZAP; writes runtime/reports/scan_<date>.json plus TOON, and diffs findings against manifest/allowlist.json and manifest/allowlist.baseline.json for the milestone in manifest/milestone.json. Gate per ADR-03: M1–M3 report only, M4 exit 50 on HIGH, M5 exit 50 on CRITICAL or HIGH. Flags --baseline, --secrets, --dynamic run one part only. Exit 51 if a scanner cannot run, 52 if --dynamic was asked for while services are unhealthy. read-only
redteam preflight Verifies, before an AI red-team run, that the attacker container of the red-team Compose project is isolated (proved with a reachable canary, see SPEC-03 §6), that only the containers named in manifest/redteam-targets.json are attached, and that the approval record is present and current. Exit 53 if either check fails. See SPEC-03 §6. yes (starts and removes a canary container and network for the probe)
accept Runs the Playwright Python acceptance suite in the same .venv/. --only <scenario> runs one scenario; --seed creates the disposable test users. Exit 60 on any failing test. See SPEC-04. read-only
upstream mirror / upstream integrate Runs the daily mirror or the weekly integration of SPEC-05 by hand. Needs Git credentials for the private -dev2027 repositories; never run in this repository's CI. Exit 70 when a fetch was refused or failed, a push failed, or a merge conflicted; the report is written in every case. no (Git only)
manifest check / manifest toon check validates manifest/upstreams.json (SPEC-01 §5) and verifies that every TOON excerpt in docs/ and manifest/upstreams.toon agree with it. Exit 20 on mismatch. toon prints the excerpt that upstreams.toon must equal. no
docs build / docs check build runs MkDocs into site/. check enforces SPEC-06 §8: anchors, Jump line, relative links, TOON consistency, Version line. no
report Bundles the latest reports of doctor, plan, health, scan, and accept into runtime/reports/<timestamp>.toon and .json. no
install The sequence shown in the flowchart. Stops at the first non-zero step. Right after compose render it runs the read-only volume check of up (exit 13 when Docker volumes of the project were created by another checkout), so that case stops before build, not after it. yes

4. Profiles and published ports

profiles[3]{name,services,note}:
  minimum,"osf_init volume_owner_init volume_access_check_1000 web api postgres elasticsearch8 elasticsearch8_setup rabbitmq fakecas",smallest set that shows a login and a project page
  core,"minimum + admin worker wb wb_worker mfr unoconv ember_osf_web cas wiki_assets elasticsearch6 redis y_websocket volume_access_check_999","the six core repositories with their infrastructure, plus y_websocket for Wiki collaborative editing; wiki_assets is a one-shot that copies the wiki editor bundle into the volume wiki_static (ADR-06)"
  full,"core + rdmcp aipf_mcp_data_grdm oasys shibboleth_sp test_idp",everything; shibboleth_sp replaces fakecas

Service names follow the upstream docker-compose.yml of RDM-osf.io so that existing guides keep working, and they are the services[] values of the manifest (SPEC-01 §3). The wiki-frontend component is an overlay of osf.io (overlay_of, ADR-06): its service is a one-shot (a container that runs once and exits, restart: "no") on the bundle-builder image grdm-dev/wiki-frontend:<osf_sha12>-<wiki_sha12>: after volume_owner_init has handed the fresh volume wiki_static to uid 1000, wiki_assets copies the webpack output /code/website/static/public/js/ into it and exits; web, api, admin and worker mount that volume read-only at /code/website/static/public/js/wiki/ and depend on it with condition: service_completed_successfully, so up starts them only after the bundle is in place. health counts a one-shot as healthy once it has exited with code 0. The shibboleth Compose profile and the fakecas service are mutually exclusive: compose render --profile full --auth shibboleth removes fakecas and adds shibboleth_sp and test_idp; the default for full is fakecas. y_websocket belongs to core, not full, because Wiki collaborative editing is an M2 acceptance scenario (C4 in SPEC-04 §4); the manifest's profile for the y-websocket component is core accordingly (SPEC-01 §3).

elasticsearch8 runs the image grdm-dev/elasticsearch8:<tag> that build makes from installer/images/elasticsearch8 (manifest image_build: the official Elasticsearch 8.19.24 pinned by digest plus the two Japanese-analysis plugins) as uid 1000 on a read-only root with TLS, authentication and scripts off, and publishes no port (its health check allows 30 s plus 100 tries, 10 s apart and up to 5 s each, so 17 to 26 minutes, because a start took 8 min 10 s under full-system amd64 emulation, where the earlier 12 tries marked a healthy start unhealthy and up stopped with exit 40, DEMO-22 0.7; a start that is up passes at once, and the window stays inside the default up wait of 1800 s); elasticsearch8_setup is a one-shot that creates the role and user grdm_osf, limited to the website* indices, that osf.io searches with (ADR-14); the former elasticsearch (Elasticsearch 2, ADR-07) is retired together with mongo and sharejs (ADR-13 §6), and y_websocket keeps the drafts of file-page rooms in the volume y_websocket_data (YPERSISTENCE, prefix file-). The one-shot volume_owner_init (the postgres image, for its GNU tools, as explicit root with CAP_CHOWN only, one exception in manifest/hardening.json) hands every writable bind volume to the user: of the services that mount it writable, because a fresh directory belongs to the host user and a PR #33 tree to uid 101: on a Linux or WSL2 host whose uid differs, a non-root writer (redis is uid 999, the others 1000) could otherwise not use it. Services that keep root never decide an owner: postgres and rabbitmq set their own, while unoconv shares wb_tmp with its uid-1000 writers and holds DAC_OVERRIDE (a bounded exception, because root without it obeys file permissions and LibreOffice could not write there). All writers wait with condition: service_completed_successfully. Migration and retry contract. Requires GNU find and chown. Every up walks each volume with no marker and no shortcut, so a stopped run is finished by the next one and a correct top directory cannot hide wrong descendants. With only CAP_CHOWN the step reaches another uid's private directory by taking ownership of it first, hands files to the target uid, verifies that none was missed, and hands directories over last. It does not follow symlinks or leave the volume. A failure, such as a directory with mode 000, stops the step, naming the path, and writers do not start; run up again or reset. A chown that has no effect stops the step (results are read back, directories included), except on the VM shares that present every path as root:root (virtiofs measured on Colima; fakeowner, fuse.grpcfuse, fuse.sshfs, 9p). There and everywhere else, the one-shots volume_access_check_1000 and volume_access_check_999 run as the writer's own uid: each creates a uniquely named file exclusively (mktemp, which never follows a symlink or touches existing data) and removes only that file, then walks the existing tree and refuses any directory the uid cannot enter, list or write and any file it cannot read, changing nothing. Writers do not start unless that works. osf_init (component osf.io, profile minimum) is another one-shot: on the osf.io image, as uid 1000, it runs the steps the upstream README lists for a new database — manage.py migrate, scripts.populate_institutions -e test -a and scripts.register_oauth_scopes — retrying migrate every 10 s for up to 5 minutes until postgres accepts connections, running invoke search_ensure_index (creates the Elasticsearch (the search engine inside GRDM; see REF-01) index website_v1 and its alias with the full mapping) before the institution import, and exits 0; it also applies the migrations of the admin two-step sign-in (addons_twofactor 0006 and 0007), because the admin project runs none itself; web, api, admin and worker wait for it with condition: service_completed_successfully. All three steps are idempotent, so the service runs at every up (real install run 12: without it a fresh database made web answer 500 with relation "osf_institution" does not exist, and each such error leaked one postgres connection of the development server). ember_osf_web runs the static image that build makes from RDM-ember-osf-web-dev2027: its Dockerfile runs the ember-cli production build in a Node stage on the build host's own platform (the output is platform-independent, so neither amd64 (the CPU type of ordinary PCs and servers; see REF-01) nor arm64 emulates it) and serves the result with nginx-unprivileged as uid 101 on port 4200, on a read-only root with only /tmp (tmpfs) writable, with no volume and no depends_on. The image reads only OSF_URL, OSF_API_URL, OSF_RENDER_URL, OSF_FILE_URL, OSF_HELP_URL, CAS_URL = {{AUTH_URL}}, OSF_COOKIE_DOMAIN, CSP_MODE (enforce) and the optional CSP_EXTRA_SOURCES. At start its entrypoint writes the URLs into index.html under /tmp, exits 1 on a value that is not a plain http(s) URL (a host name for the cookie domain), refuses to serve if the Google Analytics adapter is in the page, sets the Content-Security-Policy from those origins and starts nginx, so a start takes seconds; there is no ember serve and no live reload. Its Compose health check is a wget of /healthz (the image has no curl).

Published ports. This table is the only place where default host ports are defined; ADR-02, SPEC-03, and REF-01 point here. Every port is published on 127.0.0.1 only.

ports[8]{service,host_port,profile,url}:
  web,5000,minimum,http://127.0.0.1:5000
  api,8000,minimum,http://127.0.0.1:8000
  admin,8001,core,http://127.0.0.1:8001
  wb,7777,core,http://127.0.0.1:7777
  mfr,7778,core,http://127.0.0.1:7778
  fakecas,8080,minimum,http://127.0.0.1:8080
  ember_osf_web,4200,core,http://127.0.0.1:4200
  y_websocket,1234,core,http://127.0.0.1:1234

All other services (cas, volume_owner_init, wiki_assets, the subsystems, test_idp, databases and queues) are reached only inside the Compose network; when one of them needs a browser-facing port, compose render assigns it and plan prints it. compose render writes every chosen host port to runtime/.env as GRDM_PORT_<SERVICE> (upper case), which the acceptance tests read (SPEC-04 §1). If a default port is already in use (macOS AirPlay on 5000 is the known case), compose render takes the next free port and records the change in the install report; exit 12 is returned only when no free port is found.

The admin service runs Django's development server as manage.py runserver 0.0.0.0:8001 --insecure, and api runs manage.py runserver 0.0.0.0:8000, both threaded: --nothreading (which invoke apiserver and invoke adminserver add) stalls under Django 2.2 (RDM-osf.io-dev2027 PR #13), because the 2.2 development server keeps a connection open for the next request and a single-threaded server then waits on a browser's idle second connection for 30 s while every other client times out; DEBUG_MODE stays True for both, so api/base/wsgi.py does not monkey-patch gevent and each thread opens its own database connection. With DEBUG = False (the generated admin_local.py, which keeps debug_toolbar out), runserver serves no static files, so the admin pages would load without their style sheets, scripts and icon fonts; --insecure makes runserver serve them from the app's static directories. This is a development-only exception: the port is published only on 127.0.0.1 like every other port in this table (ADR-02), the server is not a production web server, and a deployment must serve the admin app's static files through its own web server (for example after collectstatic) instead of this flag. A unit test keeps every published port on the loopback address.

5. Flags

Flag Meaning
--yes Answer every question with its default. Required when no terminal is attached.
--profile minimum|core|full Default core. Saved in runtime/.env as GRDM_PROFILE and reused on later runs.
--platform linux/arm64,linux/amd64 Override the platforms for build. Default: host platform only.
--memory-gib <GiB> doctor, compose render and install: scale the limits from this size instead of the detected one, a knowing overcommit when the profile's floors do not fit.
--public-access true|false compose render and install: ENABLE_PUBLIC_ACCESS of every osf.io process. Default false (authentication required); saved in runtime/.env as GRDM_ENABLE_PUBLIC_ACCESS.
--timeout <seconds> up and install (passed to up only; it does not change build, which has no time limit): how long to wait for health. An explicit 0 is passed on. Default 1800, or 5400 on Linux arm64 when the profile has amd64 services; raise it on a slow, fully emulated host.
--no-open Do not open the browser after up.
--json Print reports as JSON instead of TOON.

6. Exit codes

exit_codes[17]{code,meaning}:
  0,success
  2,"usage error: unknown flag or bad value"
  10,"host unsupported: OS, CPU, memory, or Python too old"
  11,"Docker missing, not running, or Compose / buildx plugin absent"
  12,a required port on 127.0.0.1 is in use and no free alternative was found
  13,"install prerequisite missing: git, repository access, amd64 emulation, or a checkout path Docker cannot use"
  14,reset could not delete runtime/volumes/
  15,"PostgreSQL data directory needs `grdm-dev db upgrade`, or the upgrade or rollback failed (the old directory is kept)"
  20,manifest invalid or TOON excerpt disagrees with JSON
  30,image build failed
  40,"health check failed, or a port listens on a non-loopback address"
  50,security scan gate failed for the current milestone
  51,"scanner could not run: tool missing or vulnerability database download failed"
  52,"services not healthy, so scan --dynamic could not run"
  53,"red-team preflight failed: egress reachable or a target outside redteam-targets.json"
  60,acceptance test failed
  70,"upstream mirror or integrate failed: fetch refused, push failed, or merge conflict"

Numbers are never reused for a new meaning; a new cause gets a new number. The canonical table is installer/grdm_dev/messages.tsv, and this TOON block must agree with it (manifest check verifies). Codes 50–53 are described in detail in SPEC-03 §8; code 70 in SPEC-05 §2–§4.

7. Behavior rules

  • Non-interactive. When stdin is not a terminal and --yes is absent, every question is answered "no" and the command exits 2 with a hint to add --yes.
  • Idempotent. Running any subcommand twice gives the same result. secrets init keeps existing secrets, compose render overwrites only the generated file, build uses the buildx cache, up is a no-op for healthy services.
  • No secrets in Git. runtime/ is in .gitignore. docs check and the CI secret scan fail if a file under runtime/ or a value that looks like a secret is committed.
  • No host network changes. The loopback alias 192.168.168.167 from the old guide is not created; compose render rewrites the upstream local.py and .docker-compose.*.env settings to use service names inside the Compose network and 127.0.0.1 for the browser (ADR-02).
  • First start is slow, later starts are not. up waits up to 1800 s (--timeout) for health. The first up runs osf_init, which leaves its result in named volumes, so a second up is healthy within a minute or two. The default was set when the first up also built ember-osf-web (the newer web pages of GRDM; see REF-01) under emulation on Apple Silicon (the chips Apple puts in its Macs since 2020; see REF-01), which took 13–25 minutes (real install runs 10–18). ember-osf-web is now built by build into a static image and starts in seconds; the default stays until a cold start without that build is measured. On Linux arm64 the emulation is QEMU, where the former first ember build took 44 minutes on one core, so there the default is 5400 s when the profile has amd64 services (still mfr) (DEMO-21); --timeout still overrides it, and install --timeout passes it to up, which a fully emulated amd64 machine can need: there the first ember build (under emulation, before ember became a static image) took 1 h 46 min and up 2 h 19 min (DEMO-22).
  • No -private code here. The installer clones the integration repositories by name and SHA (the fingerprint of one commit; see REF-01) from the manifest at run time; this public repository holds no code from them (POL-01).

8. Supported hosts

Memory. compose render budgets 70 % of the smaller of the host memory and the Docker engine's VM memory and refuses (exit 10) a profile whose per-service floors do not fit, naming the required size; --memory-gib overrides the detection and is a knowing overcommit (PR #33 review r1 R1-04). doctor applies the same arithmetic first and names the remedy for the host: Docker Desktop's Resources page or colima start --memory on macOS, .wslconfig on WSL2 (the Resources page has no memory control under the WSL 2 backend). The floors (mem_min_mb of the service templates, including the one-shots) of the core profile add up to 8512 MiB, so core needs at least 8512 / 0.7 / 1024 ≈ 11.9 GiB of detected memory, that is a Docker VM of 12 GiB (full: 9536 MiB, about 13.3 GiB, with fakecas; 9856 MiB, about 13.7 GiB, with --auth shibboleth). This is a lower bound computed from the floors, not a measured peak: it does not cover build, whose Node stage for ember-osf-web needs several GiB of engine memory while it runs. The former figure of about 24 GiB came from the prebuilt ember-osf-web image, which rebuilt its bundle at every start under emulation with an 8 GiB floor; the static image has a 128 MiB floor. minimum fits in 8 GiB.

Host CPU Support
macOS 14 or newer with Docker Desktop arm64 official (M2 acceptance runs here)
Ubuntu 24.04 with Docker Engine amd64, arm64 official
Windows 11 with WSL2 (Ubuntu 24.04) and Docker Desktop amd64 required to work; CI parses and dry-runs install-windows.ps1 only, and a real run needs owner hardware (ADR-08 §5)
Other Linux, macOS on Intel any best-effort; doctor warns and continues

9. Directory layout

layout:
  installer/install.sh: bash 3.2 bootstrap
  installer/install-ubuntu.sh: Ubuntu 24.04 and WSL2 prerequisites (§2.3)
  installer/install-macos.sh: macOS prerequisites (§2.3)
  installer/install-windows.ps1: Windows 11 prerequisites and WSL2 hand-over (§2.3)
  installer/prereq-lib.sh: helpers shared by the two bash prerequisite scripts
  installer/pyproject.toml: package metadata, console script grdm-dev, extra accept
  installer/grdm_dev/:
    cli.py: argument parsing, subcommand dispatch, exit codes
    host.py: OS, CPU, memory, disk, Docker detection
    manifest.py: load and validate manifest/upstreams.json, TOON comparison
    secrets.py: random secret generation, runtime/.env with mode 0600
    compose.py: render runtime/docker-compose.yml from manifest and profile
    database.py: PostgreSQL data directory status, upgrade by dump and restore, rollback (ADR-12)
    build.py: buildx wrapper, platform list, optional push
    health.py: service health and loopback-only check
    scan.py: baseline controls, Trivy SBOM and CVE, gitleaks, Semgrep, ZAP, allow-list diff, staged gate (SPEC-03)
    redteam.py: red-team preflight (SPEC-03 §6)
    upstream.py: mirror and integrate (SPEC-05)
    accept.py: run pytest-playwright in the same venv
    docs.py: MkDocs build and SPEC-06 checks
    report.py: bundle TOON and JSON reports
    messages.tsv: exit code, English message, Japanese message
  installer/tests/: unittest, files named test_*.py
  installer/acceptance/: Playwright Python, see SPEC-04
  manifest/:
    upstreams.json: canonical manifest (SPEC-01)
    upstreams.toon: excerpt generated by grdm-dev manifest toon (SPEC-01)
    allowlist.json: accepted findings (SPEC-03 §5.1)
    allowlist.baseline.json: allow-list count at the last milestone exit, owner-maintained (SPEC-03 §5.1)
    milestone.json: current milestone, owner-maintained (SPEC-03 §5.2)
    hardening.json: per-service exceptions to read-only root and cap_drop, with reasons (SPEC-03 §3.3)
    redteam-targets.json: container names the AI red team may touch (SPEC-03 §6)
  runtime/: generated, git-ignored (.env, docker-compose.yml, volumes/, reports/, backups/, db-operation.json and .lock)

10. Tests

python3 -m unittest discover -s installer/tests must pass on every PR (pull request: a proposed change waiting for review; see REF-01). Each module has a test_<module>.py that covers at least one success case and one rejection case, and every rejection case asserts the exit code from §6. Docker is never required by unit tests: host.py and build.py take an injectable runner so tests pass fake docker output. Integration and acceptance tiers are defined in SPEC-04.

The prerequisite scripts of §2.3 are checked on every PR by installer-prereq-lint.yml: bash -n, shellcheck, the PowerShell parser on windows-latest, and a dry run on each OS. Unit tests run them only with --dry-run or --help, under a PATH of stubs. installer-full.yml, started by hand, does a full minimum install on ubuntu-24.04 and ubuntu-24.04-arm and needs the repository secret GRDM_INTEGRATION_READ_TOKEN. What these runners cannot prove is listed in ADR-08 §5.


日本語

→ To English

1. 範囲ず目的

むンストヌラヌは、このリポゞトリを取り出した盎埌の状態から、§8 に挙げたホストで、コマンド䞀぀で GakuNin RDMGakuNin孊認。倧孊のアカりントでログむンするための日本の孊術ネットワヌク。REF-01の開発環境を動かすものです。install.sh ず grdm-dev は sudoコンピュヌタの管理者ずしおコマンドを動かす仕組みを䜿わず、ホストのネットワヌク蚭定を倉えず、䜕床やり盎しおも壊れたせん。䜜られるものはすべお runtime/ の䞋にあり、Git は無芖したす。任意の前提条件スクリプト§2.3は事前にホストを準備し、sudo を䜿うこずがありたすが、倉曎を瀺しお同意を埗た埌に限りたすADR-08。

甚語泚。 「むンストヌラヌ」は、ほかのプログラムが動くように準備するプログラムです。「CLI」コマンドラむンむンタヌフェヌスは、文字でコマンドを打っお䜿うプログラムです。「コンテナ」は、䞀぀のプログラムず必芁なものを䞀箱に入れ、どのコンピュヌタでも同じように動かすための箱です。「Docker」むメヌゞを䜜りコンテナを動かす道具。REF-01ずその盞棒の「Docker Compose」REF-01がコンテナを動かしたす。Compose は䞀枚の蚭定ファむルから倚くのコンテナをたずめお起動する道具です。「manifest」は、どの゜ヌスリポゞトリのどの版を䜿うかを正確に曞いた䞀芧ですSPEC-01。

2. 入口

環境を導入する入口は二぀です§2.1、§2.2。そのためにホストを準備する任意のスクリプトがありたす§2.3。

2.1 installer/install.sh — 薄い起動スクリプト

install.sh がするこずは次の四぀だけです。

  1. macOS 暙準の bash版 3.2で動く。そのため連想配列、mapfile、${var,,} のような新しい機胜は䜿わない。
  2. python3 を探し、3.11 以䞊かを確かめる。足りなければ、刀定した OS に合わせた導入方法を衚瀺しお終了コヌド 10 で終わる。
  3. 「仮想環境」システムずは別の、Python ずラむブラリだけの私甚フォルダを .venv/ に䜜り、pip install -e installer[scan] で installer/ パッケヌゞを入れる远加 scan は grdm-dev scan がロヌカルで動かす Semgrep を含む。SPEC-03 §4.2、実機第 17 回。GRDM_WITHOUT_SCAN=1 で倖し、GRDM_WITH_ACCEPT=1 で Playwright を加える。
  4. 匕数をすべお .venv/bin/grdm-dev install "$@" に枡し、その終了コヌドで終わる。

OS の違いは install.sh には曞きたせん。installer/grdm_dev/host.py に閉じ蟌めたす。利甚者向けの文蚀は installer/grdm_dev/messages.tsvコヌドごずに䞀行、英語ず日本語の列から出し、スクリプトず Python コマンドが同じ蚀葉を話すようにしたす。

flowchart TD
  A[./installer/install.sh --yes] --> B{python3 は 3.11 以䞊?}
  B -- いいえ --> X10[終了 10: Python の導入方法を衚瀺]
  B -- はい --> C[.venv/ を䜜り pip install -e installer]
  C --> D[grdm-dev doctor]
  D -- 察象倖のホスト --> X10b[終了 10]
  D -- Docker が無い --> X11[終了 11]
  D -- 前提が䞍足 --> X13[終了 13]
  D -- スキャナヌが無い --> X51[終了 51]
  D --> E[grdm-dev plan]
  E -- manifest 䞍正 --> X20[終了 20]
  E --> F[grdm-dev secrets init]
  F --> G[grdm-dev compose render]
  G --> H[grdm-dev build]
  H -- 倱敗 --> X30[終了 30]
  H --> I[grdm-dev up]
  I --> J[grdm-dev health --network]
  J -- 倱敗 --> X40[終了 40]
  J --> K[grdm-dev scan]
  K -- 門で䞍合栌 --> X50[終了 50]
  K --> L[grdm-dev report]
  L --> Z[終了 0。URL http://127.0.0.1:5000 を衚瀺]
Loading

2.2 grdm-dev — Python コマンド

grdm-dev はパッケヌゞ installer/grdm_dev/ を、コン゜ヌルスクリプトずしお公開したものです。芏則は次のずおりです。

  • 暙準ラむブラリ優先。 コマンド本䜓は倖郚ラむブラリに䟝存したせん。manifest は JSONjson で読む、ホストは platform・shutil・socket・subprocess で読み、生成する Compose ファむルは JSON で曞き出したす。JSON は YAML字䞋げでデヌタを曞く文字の圢。REF-01ずしお正しいので Docker Compose がそのたた読めたす。したがっお PyYAML は芁りたせん。
  • 任意の远加 accept。 pip install -e "installer[accept]" で pytest・pytest-playwright・playwright が入りたす。これらを読み蟌むのは grdm-dev accept だけですSPEC-04。
  • 倖郚の道具 はサブプロセスずしお呌び、doctor が有無を確かめたす。docker27 以䞊ず Compose プラグむンv2 以䞊・buildx䞀぀のむメヌゞを䜕皮類かの蚈算機向けに䜜る Docker の助手。REF-01、scan 甚の trivy・gitleaks・semgrep、scan --dynamic 甚の OWASP ZAP動いおいる Web サむトを攻撃者のやり方で぀぀く道具。REF-01のコンテナむメヌゞ、docs 甚の mkdocs です。スキャナヌが無いず scan は終了 51 で終わりたすSPEC-03 §8。
  • すべおのサブコマンドは --json を受け付け、TOONJSON を短く曞いた文字圢匏。SPEC-06 §4の代わりに機械が読む JSON で同じ報告を出したす。

2.3 OS ごずの前提条件スクリプト

これらのスクリプトはホストを準備しおから install.sh を実行したす。理由は ADR-08 にありたす。導入の刀断は持たず、すべおの刀断は匕き続き install.sh ず grdm-dev が行いたす。

スクリプト ホスト 甚意できるもの
installer/install-ubuntu.sh Ubuntu 24.04 の amd64・arm64、WSL2 の䞭の Ubuntu 24.04 apt パッケヌゞgit、Python、python3-venv、curl、gnupg、Docker の眲名付き apt リポゞトリからの Docker Engine ず Compose・buildx プラグむン、docker グルヌプぞの远加、arm64 での amd64 ゚ミュレヌションダむゞェストで固定した tonistiigi/binfmt むメヌゞから QEMU を登録する。実際のビルドで萜ちた Ubuntu の qemu-user-static 8.2.2 は眮き換える。DEMO-21、~/.local/bin の Trivy ず gitleaks、GRDM_WITH_ACCEPT=1 のずきの libatomic1。WSL2 の䞭では Docker Engine を飛ばし、Docker Desktop を求める。
installer/install-macos.sh Apple Silicon の macOS Homebrew の formula[email protected]、git、Trivy、gitleaks。入っおいる Docker Desktop を起動する。Docker Desktop・OrbStack・Colima を怜出し、Docker の実行基盀も Homebrew も入れない。
installer/install-windows.ps1 Windows 11 の amd64 WSL2 ず Ubuntu-24.04 のディストリビュヌション。Docker Desktop ず WSL 連携を確認する。このリポゞトリを WSL のホヌムの䞋に clone し/mnt/c には決しお眮かない、WSL の䞭で install-ubuntu.sh を実行する。

どのスクリプトも次を守りたす。

  • 䜕を倉えるかを瀺し、sudo や管理者の操䜜の前に尋ねる。docker グルヌプぞの远加は別に尋ねる。
  • --yesPowerShell では -Yes。--yes も受け付けるで同意する。端末が無く --yes も無ければ、§7 のずおり終了 2 で止たる。
  • --dry-run-DryRunは刀定しお予定を衚瀺し、䜕も倉えない。
  • 再実行できる。既にある前提条件は飛ばす。
  • 倱敗したら分かりやすい文蚀で止たり、§6 の終了コヌド 2・10・11 だけを䜿う。
  • ダりンロヌドは眲名された配垃元か固定したチェックサムでだけ受け入れ、シェルぞ流し蟌たない。
  • トヌクンを尋ねず、読たず、保存しない。非公開の統合リポゞトリぞの暩限を git に䞎える方法を案内するだけである。
  • 最埌に installer/install.sh を実行し、ほかの匕数はそのたた枡す。

3. サブコマンド

サブコマンド 契玄 Docker に觊れるか
doctor OSmacOS・Ubuntu・WSL2、CPUarm64・amd64、メモリ、空き容量、Docker 27 以䞊、Compose プラグむンv2 以䞊、buildx を刀定し、長いビルドの前に問題が分かるよう install に芁るものを確かめる。git、プロファむルの非公開統合リポゞトリの読み取り暩限端末で問い合わせない git ls-remote で確かめ、URL にトヌクンが含たれ埗るので出力は衚瀺しない、trivy・gitleaks・semgrep、Docker VM ずホストの小さい方に察するプロファむルのメモリ䞋限--memory-gib で譊告に倉わる。承知の䞊の過剰割圓、amd64 ゚ミュレヌションbinfmt は Linux arm64 に限る。報告に amd64_emulation の行も出す。amd64 では not needed (host is amd64)、動く handler のある Linux arm64 では ready (...)、macOS では出さない有効にするコマンドを衚瀺し、萜ちるず実枬した゚ミュレヌタヌUbuntu 24.04 の qemu-user-static 8.2.2。登録枈みむンタヌプリタヌの --version で刀定は拒んで眮き換えるコマンドを衚瀺、Docker が䜿える配眮先WSL2 では詊隓ファむルの chmod 0600 を読み返しお確かめ、モヌドを保持するファむルシステムであるこず。Windows のドラむブは runtime/.env を 0600 に保おない。macOS でぱンゞンから芋えるこず。up が䜿う postgres むメヌゞにリポゞトリを読み取り専甚で bind しお問い合わせる。このサブコマンドが取埗しおよいむメヌゞはこれだけ。゚ンゞンが mount を拒むか䞭身が空なら終了 13、問い合わせ自䜓ができなければ譊告。Docker VM が共有しおいない堎所からの bind mount は黙っお空になるため。問い合わせができないずきは GRDM_DOCKER_SHARED=1 で省ける。TOON で報告する。察象倖のホストかメモリ䞋限が収たらないずきは終了 10、Docker が無い・動いおいないずきは 11、前提が䞍足なら 13、スキャナヌが無ければ 51。 読むだけ
plan manifest ずプロファむルを解決し、どのむメヌゞを䜜りどのサヌビスを起こすか、公開ポヌト§4ずずもに衚瀺する。䜕も倉えない。manifest が SPEC-01 の怜査に萜ちれば終了 20。 觊れない
secrets init / secrets rotate init は乱数の秘密DB パスワヌド、Django の秘密鍵、CAS の鍵を runtime/.env にモヌド 0600 で曞く。既定倀や䟋のパスワヌドは決しお曞かない。既存ファむルは --force がなければ䞊曞きしない。init --missing は、新しいキヌELASTIC8_PASSWORD、ELASTIC8_OSF_PASSWORD。ADR-14より前に䜜られた runtime/.env のための曎新で、既存の倀をすべお保ち実デヌタが䟝存するパスワヌドは有効なたた、足りないキヌだけを足し、廃止したキヌを消し、皌働䞭のパスワヌドは倉えず、皌働䞭のスタックも芁らない。--force ずは䜵甚できない。rotate は曎新の手順ではない。すべおの秘密を䜜り盎し、皌働䞭の PostgreSQL ず RabbitMQ のパスワヌドを倉曎し、新しい環境を受け取るようコンテナを再䜜成し、旧い資栌情報が拒吊されるこずを確かめる。どこかで倱敗したら以前の runtime/.env に戻しお 40 で終わる。init --force ず rotate は廃止した資栌情報のキヌを消す。曎新埌は、rotate や再䜜成の前に compose render を実行する。以前に生成した Compose ファむルは廃止したキヌを参照し続けるからである。四぀のキヌには CAS のむメヌゞが芁する長さがある。TGC_ENCRYPTION_KEY は 43 文字、TGC_SIGNING_KEY は 86 文字、OSF_API_INSTITUTIONS_AUTH_JWESECRET はちょうど 32 バむト、OSF_API_INSTITUTIONS_AUTH_JWTSECRET は 32 バむト以䞊で、埌の二぀は osf.io の JWE_SECRET ず JWT_SECRET でもあるADR-07 §7。四぀ずも base64url の文字A–Z、a–z、0–9、-、_。空癜・匕甚笊・パディングは䞍可だけを䜿い、公開された既定倀であっおはならず、TGC_ENCRYPTION_KEY は 32 バむトぞ正準に埩号できなければならない。レッドチヌムに秘密を取られた埌に䜿うSPEC-03 §6。 觊れない / 觊れる
compose render runtime/.env に生成すべきキヌが無いずき、たたは CAS のキヌが䜿えないずき長さの誀り、base64url 以倖の文字、公開された既定倀は、キヌの名前だけを瀺しお終了 2 で止たるキヌが無いずきは secrets init --missing、CAS のキヌが䜿えないずきは secrets rotate で盎す。manifest ずプロファむルから runtime/docker-compose.yml を曞く。内郚ネットワヌク grdm ず公開専甚の grdm-edge--egress <services> で远加接続し runtime/.env に蚘録。SPEC-03 §3.2、郚品ごずの platform: は manifest の build_platform から、ポヌトは 127.0.0.1 にだけ公開§4、党サヌビスに非 root の user:、read_only・cap_drop・資源制限mem_limit・cpus・pids_limit。doctor が怜出したホストのメモリず Docker ゚ンゞンの VM メモリdocker info。Docker Desktop では VM はホストの䞀郚。実機第 10 回の小さい方に応じお決め、テンプレヌトの䞋限 mem_min_mb が先に取り分を確保し、残りを他が分け合う。CPU ぱンゞンが報告する数docker info。䞍明なずきだけホストの数から決める、サヌビスごずの䟋倖は manifest/hardening.json からSPEC-03 §3.3、platform: は doctor の結果から遞ぶ、名前付きボリュヌムは runtime/volumes/ の䞋、tmpfs の各項目は mode=1777 で mountCompose の短い蚘法は root 専甚の 0755 になる。実機第 11 回、テンプレヌト倀のプレヌスホルダ {{HOST_PORT:<service>}}・{{CONTAINER_PORT:<service>}}・{{AUTH_URL}}fakecas の公開 URL。--auth shibboleth で fakecas が倖れるずきは web の URLを解決する。組み立おる郚品の image: に最埌のビルドruntime/reports/build_latest.jsonのタグを䜿うのは、manifest が固定するタグず同じずきだけである。蚘録されたビルドが固定ず違うずきは叀い最埌の build の埌で固定が動いたずみなし、代わりに固定のタグを曞き、報告の stale_build_tagscomponent・pinned・recorded・imageに茉せ、暙準゚ラヌに譊告の囲みを出しお察凊grdm-dev build を実行しおから grdm-dev upを瀺す。install は組む前に render するので、終了コヌドは 0 のたたである。䞀床も組んでいないむメヌゞは叀いものを動かす代わりに up を倱敗させる。manifest が固定しない郚品は蚘録されたタグを䜿う。osf.env には osf.io から Elasticsearch 8 ぞの接続ELASTIC_URI=https://elasticsearch8:9200、ELASTIC_CA_CERTS=/es-ca/ca.crt。利甚者 grdm_osf ずそのパスワヌドはサヌビスの環境から来る、y-websocket ぞの内郚 URLY_WEBSOCKET_INTERNAL_URL、ENABLE_PUBLIC_ACCESS を曞き、web・api・admin・worker・osf_init は elasticsearch8_ca公開の蚌明曞だけを読み取り専甚でマりントする。`--public-access true false既定は runtime/.envのGRDM_ENABLE_PUBLIC_ACCESS、なければ falseは osf.io のすべおのプロセスの ENABLE_PUBLIC_ACCESS を決めるRDM-osf.io-dev2027 PR #8。false はすべおのデヌタ経路で認蚌を芁求し匿名の芁求はログむンぞの転送か 401。眲名぀きの WaterButler・MFR の呌び戻しや Webhook などは動き続ける、trueは公開プロゞェクトの匿名閲芧を蚱す。遞択はruntime/.env に蚘録し、--egress` ず同じく次回以降の render でも保぀。ADR-02 に埓う。
build docker buildx でむメヌゞを䜜る。プラットフォヌムは優先順に --platform、manifest の郚品の build_platform䟋: EOL ベヌスで arm64 に組めない郚品は linux/amd64 にしお゚ミュレヌションで動かす、それもなければホストず同じ。むメヌゞはロヌカルに読み蟌む。prebuilt_imageSPEC-01を持぀郚品は組たず、ダむゞェスト固定のむメヌゞを芁求された platform ごずに取埗しお prebuilt ず報告するpull-failed は終了 30。--push でも prebuilt のむメヌゞは ghcr.io/rcosdp に再公開しない第䞉者の成果物であるため。行は prebuilt-not-pushed、pushed: false ず報告する。--push で multi-arch の manifest を ghcr.io/rcosdp/<name>非公開ぞ送る。倱敗は終了 30。 觊れる
up / down / reset up は䞭断された db の操䜜をたず完了か巻き戻しし、runtime/volumes/postgres_data が生成枈みのむメヌゞず別の PostgreSQL の版で曞かれおいるか版を読めなければ終了 15 で止たりADR-12、そうでなければプロファむルを起動し健康になるたで埅぀。デヌタベヌスの確認の前に、render したファむルのボリュヌム grdm-dev_<名前> が Docker に既にあり、このチェックアりトの runtime/volumes/<名前> ず別のディレクトリに結び付いおいれば、up は終了 13 で止たる同じプロゞェクトの新しい clone や移したディレクトリ。Docker はボリュヌムを䜜った日のオプションを芚え、Compose は比べずに再利甚するので、このチェックアりトは別のチェックアりトのデヌタを自分の新しい秘密で開いおしたう。䜕も起動も削陀もせず、メッセヌゞはそのボリュヌムず、解攟するコマンドもう䞀方のチェックアりトで grdm-dev down、続けお docker volume rm <名前>。ファむルはディスクに残るを瀺す。down はコンテナを止めボリュヌムを残す。reset は止めたうえで確認の埌に runtime/volumes/ を消す--yes で確認を省く。Linux ではファむルがコンテナの uid の所有でホストの利甚者には消せないので、DAC_OVERRIDE ず FOWNER だけを持぀ root のコンテナで䞭身を空にする。䜕かを止めたり消したりする前にホスト偎でパスを怜蚌し、シンボリックリンクの runtime/ やボリュヌムのルヌト、リポゞトリの倖ぞ解決されるルヌト、シンボリックリンクのボリュヌム、runtime/ やボリュヌムのルヌトやその䞋の任意の深さの mountホストの mount 衚から読むので同じファむルシステムの bind mount も含む。衚が読めないずきも拒むは終了 14 で止たる。reset は down の埌ず消去の埌にも繰り返し、ボリュヌムのルヌトが別のディレクトリに倉わっおいれば止たる。compose render ず up も、所有者蚭定の段が同じパスに root で働くので、同じ怜蚌を終了 13 で行う。これらは時点の確認であり、Docker は埌で bind を解決するのでこの隙間はどの怜査でも塞げない。リポゞトリを他の利甚者やプロセスが同時に倉曎しないこずを前提ずする。 觊れる
db status / db upgrade / db rollback / db recover status は runtime/volumes/postgres_data ず生成枈みの postgres むメヌゞの PostgreSQL の版を衚瀺し、䜕も倉えない。upgrade党サヌビス停止䞭、--yes で省ける確認の埌はダンプず埩元でデヌタを生成枈みの版ぞ移す。旧版をネットワヌクなしで旧ディレクトリの䞊に動かし、新版の pg_dumpall が runtime/backups/postgres-<旧>-to-<新>-<時刻>/ に曞き、新しいディレクトリを初期化しお ON_ERROR_STOP で埩元し、党衚の行数ずシヌケンスの倀を突き合わせ、その埌で初めお旧ディレクトリを新しいものの隣の postgres_data.pg<旧>-<時刻> に改名する。rollback はそのディレクトリを戻す。どちらも䜕かを䜜るか改名する前に排他ロックup ず reset も確認ず起動・削陀の間に取るを取り、氞続的な操䜜蚘録runtime/db-operation.jsonを曞く。recover、そしお埌続のすべおの db コマンド・reset・up は、クラッシュや䞭断が残した操䜜を最初に完了か巻き戻しする。旧サヌバヌの起動前に空き容量の芋積りを確かめる。倱敗すれば旧か新のクラスタが䜿える状態で終了 15。補償の改名たで倱敗したずきは操䜜蚘録を残しお終了 15。ADR-12 を参照。 觊れる
health 各サヌビスの健康確認甚の URL を調べる。公開したルヌプバックのポヌトぞの HTTP GET倚くは /。web は /login/。osf.io の / は ember ぞ転送し、以前の事前ビルド枈みの ember がビルド䞭は 500 を返した。実機第 14 回。ember_osf_web は /healthz で、HTTP 200 だけを健康ず数えるで、䞀回限りのサヌビスは 0 で終了しおいれば健康ず数える。--network を付けるず、ホストで埅ち受けおいる゜ケットも䞀芧し、コンテナのポヌトがルヌプバック以倖の番地に結び付いおいるか、プロゞェクトのポヌト䞊のワむルドカヌドの埅ち受けの所有者が芋えなければ終了 40安党偎に倱敗。Docker でない名前の分かるホストのプログラムがプロゞェクトのポヌトにいる堎合macOS の AirPlay レシヌバヌの *:5000。実機第 16 回は foreign-listener の譊告ずしお報告し、倱敗にはしない。我々の挏れではなく、runtime/.env の GRDM_PORT_<SERVICE> で我々のポヌトを移せる。 読むだけ
scan SPEC-03 のセキュリティ門を党郚動かす。基本察策、Trivy の SBOM゜フトりェア郚品衚。むメヌゞに入っおいる郚品の䞀芧ず CVE の䞀芧、gitleaks、Semgrep、OWASP ZAP。runtime/reports/scan_<日付>.json ず TOON を曞き、manifest/milestone.json の節目に合わせお manifest/allowlist.json ず manifest/allowlist.baseline.json ず差分を取る。門は ADR-03 どおり、M1〜M3 は報告のみ、M4 は HIGH で終了 50、M5 は CRITICAL か HIGH で終了 50。フラグ --baseline・--secrets・--dynamic は䞀郚だけを動かす。スキャナヌが動かなければ終了 51、サヌビスが健党でないのに --dynamic を求めたら終了 52。 読むだけ
redteam preflight AI レッドチヌムの実行前に、レッドチヌム甚 Compose プロゞェクトの攻撃偎コンテナが隔離されおいるこず届くはずのカナリアで蚌明する。SPEC-03 §6、manifest/redteam-targets.json に名前のあるコンテナだけが接続しおいるこず、承認蚘録があり新しいこずを確かめる。どちらかが倖れれば終了 53。詳现は SPEC-03 §6。 觊れる怜査甚のカナリアのコンテナずネットワヌクを䜜っお消す
accept Playwright Python の受入詊隓を同じ .venv/ で実行する。--only <シナリオ> で䞀぀だけ、--seed で䜿い捚おの詊隓利甚者を䜜る。䞀件でも倱敗すれば終了 60。詳现は SPEC-04。 読むだけ
upstream mirror / upstream integrate SPEC-05 の日次ミラヌず週次統合を手で動かす。非公開の -dev2027 ぞの Git 認蚌情報が芁り、このリポゞトリの CI では決しお動かさない。fetch が拒たれた・倱敗した、push が倱敗した、マヌゞが衝突したずきは終了 70。報告はどの堎合も曞く。 觊れないGit のみ
manifest check / manifest toon check は manifest/upstreams.json を怜蚌しSPEC-01 §5、docs/ 内の TOON の抄録ず manifest/upstreams.toon がそれず䞀臎するか確かめる。䞍䞀臎は終了 20。toon は upstreams.toon が䞀臎すべき抄録を出力する。 觊れない
docs build / docs check build は MkDocs で site/ を䜜る。check は SPEC-06 §8 のアンカヌ、Jump 行、盞察リンク、TOON の䞀臎、Version 行を怜査する。 觊れない
report doctor・plan・health・scan・accept の最新の報告を runtime/reports/<時刻>.toon ず .json にたずめる。 觊れない
install 流れ図の順に実行する。最初に 0 以倖で終わった段で止たる。compose render の盎埌に up の読み取りだけのボリュヌムの怜査を行いプロゞェクトの Docker ボリュヌムを別のチェックアりトが䜜っおいれば終了 13、その堎合は build の埌でなく前に止たる。 觊れる

4. プロファむルず公開ポヌト

profiles[3]{name,services,note}:
  minimum,"osf_init volume_owner_init volume_access_check_1000 web api postgres elasticsearch8 elasticsearch8_setup rabbitmq fakecas",ログむンずプロゞェクト画面が芋える最小の組
  core,"minimum + admin worker wb wb_worker mfr unoconv ember_osf_web cas wiki_assets elasticsearch6 redis y_websocket volume_access_check_999",コア 6 リポゞトリず基盀。Wiki 共同線集の y_websocket を含む。wiki_assets はボリュヌム wiki_static に Wiki ゚ディタの束を写す䞀回限りのサヌビスADR-06
  full,"core + rdmcp aipf_mcp_data_grdm oasys shibboleth_sp test_idp",党郚。shibboleth_sp は fakecas ず入れ替わる

サヌビス名は RDM-osf.io 䞊流の docker-compose.yml に合わせ、既存の手匕きがそのたた䜿えるようにしたす。これは manifest の services[] の倀でもありたすSPEC-01 §3。wiki-frontend 郚品は osf.io のオヌバヌレむoverlay_of、ADR-06です。そのサヌビスは「䞀回限り」䞀床動いお終了するコンテナ。restart: "no"で、束を組むむメヌゞ grdm-dev/wiki-frontend:<osf の sha12>-<wiki の sha12> を動かしたす。volume_owner_init が新しいボリュヌム wiki_static を uid 1000 に枡した埌で、wiki_assets が webpack の出力 /code/website/static/public/js/ をそこぞ写しお終了したす。web・api・admin・worker はそのボリュヌムを /code/website/static/public/js/wiki/ に読み取り専甚で mount し、condition: service_completed_successfully で埅぀ので、up は束が眮かれおからそれらを起動したす。health は終了コヌド 0 で終わった䞀回限りのサヌビスを健康ず数えたす。Compose プロファむル shibboleth ずサヌビス fakecas は排他です。compose render --profile full --auth shibboleth は fakecas を倖しお shibboleth_sp ず test_idp を足したす。full の既定は fakecas です。y_websocket は full でなく core に属したす。Wiki 共同線集が M2 の受入シナリオSPEC-04 §4 の C4だからです。manifest の y-websocket 郚品の profile もそれに合わせお core ですSPEC-01 §3。

elasticsearch8 は build が installer/images/elasticsearch8 から組むむメヌゞ grdm-dev/elasticsearch8:<tag>manifest の image_build。ダむゞェストで固定した公匏の Elasticsearch 8.19.24 に日本語解析の二぀のプラグむンを足したものを uid 1000・読み取り専甚ルヌトで、TLS ず認蚌あり、スクリプトなしで動かし、ポヌトは公開したせんヘルスチェックは 30 秒に加えお 100 回間隔 10 秒、1 回は最長 5 秒、17〜26 分たで埅ちたす。機械党䜓を amd64 で゚ミュレヌションする環境で起動に 8 分 10 秒かかり、以前の 12 回では健党な起動を䞍健党ず刀定しお up が終了 40 で止たったためですDEMO-22 0.7。起動できおいればすぐ通り、窓は up の既定の埅ち 1800 秒の内に収たりたす。elasticsearch8_setup は䞀回きりの手順で、osf.io が怜玢に䜿う、website* の玢匕に限った role ず利甚者 grdm_osf を䜜りたすADR-14。以前の elasticsearchElasticsearch 2、ADR-07は mongo・sharejs ずずもに退圹したしたADR-13 §6。y_websocket はファむルペヌゞの郚屋の䞋曞きをボリュヌム y_websocket_data に残したすYPERSISTENCE、接頭蟞 file-。䞀回限りの volume_owner_initGNU の道具を持぀ postgres むメヌゞを明瀺の root で、CAP_CHOWN のみ。manifest/hardening.json の䟋倖は䞀件は、曞き蟌みで䜿うすべおの bind ボリュヌムを、それを曞き蟌みで mount するサヌビスの user: に枡したす。新しいディレクトリはホストの利甚者の、PR #33 の朚は uid 101 の所有で、uid の違う Linux や WSL2 のホストでは非 root の曞き手redis は uid 999、他は 1000が䜿えないからです。root のたたのサヌビスは所有者を決めたせん。postgres・rabbitmq は自分で敎え、unoconv は uid 1000 の曞き手ず wb_tmp を共有し DAC_OVERRIDE を持ちたす限定した䟋倖。これが無い root はファむル暩限に埓い、LibreOffice がそこに曞けたせん。曞き手はすべお condition: service_completed_successfully で埅ちたす。移行ず再詊行の玄束。 GNU の find ず chown を前提にしたす。どの up でも、印も近道も䜿わず各ボリュヌムを党郚蟿るので、途䞭で止たった実行は次の実行が完了させ、䞀番䞊のディレクトリが正しくおも䞋の誀りは隠れたせん。CAP_CHOWN だけなので、他の uid の私甚ディレクトリには先に所有者になっおから入り、ファむルを目的の uid に枡しお挏れが無いこずを確かめ、ディレクトリを最埌に枡したす。シンボリックリンクは蟿らず、ボリュヌムの倖ぞも出たせん。モヌド 000 のディレクトリなどの倱敗ではパスを瀺しお止たり、曞き手は起動したせん。up をやり盎すか reset しおください。効果の無い chown は段を止めたす結果はディレクトリも含めお読み返したす。䟋倖はすべおのパスを root:root ず芋せる VM 共有だけですvirtiofs は Colima で実枬。fakeowner・fuse.grpcfuse・fuse.sshfs・9p。そこでも他でも、䞀回限りの volume_access_check_1000 ず volume_access_check_999 が曞き手自身の uid で動き、䞀意の名前のファむルを排他的に䜜っおmktemp。シンボリックリンクを蟿らず既存のデヌタに觊れないそのファむルだけを消し、続いお既存の朚を蟿っお、その uid が入れない・䞀芧できない・曞けないディレクトリず読めないファむルを、䜕も倉えずに拒みたす。それが成功しなければ曞き手は起動したせん。osf_init郚品 osf.io、プロファむル minimumももう䞀぀の䞀回限りのサヌビスです。osf.io のむメヌゞで uid 1000 ずしお、䞊流 README が新しいデヌタベヌス向けに挙げる手順 manage.py migrate・scripts.populate_institutions -e test -a・scripts.register_oauth_scopes を実行し、postgres が接続を受け付けるたで migrate を 10 秒ごずに最長 5 分やり盎し、機関の投入の前に invoke search_ensure_indexElasticsearch の玢匕 website_v1 ずその別名を完党なマッピングで䜜るを実行しお 0 で終了したす。管理画面の 2 段階サむンむンの migrationaddons_twofactor の 0006 ず 0007も、admin プロゞェクトが自分では migration を実行しないので、ここで適甚されたす。web・api・admin・worker は condition: service_completed_successfully でこれを埅ちたす。䞉぀の手順はどれも䜕床実行しおも同じ結果になるので、サヌビスは up のたびに動きたす実機第 12 回: これが無いず新しいデヌタベヌスで web が relation "osf_institution" does not exist の 500 を返し、その゚ラヌごずに開発サヌバヌが postgres の接続を 1 本挏らした。ember_osf_web は、build が RDM-ember-osf-web-dev2027 から組む静的なむメヌゞで動きたす。その Dockerfile は ember-cli の本番ビルドをビルドホスト自身のプラットフォヌムで Node の段ずしお実行し成果はプラットフォヌムに䟝らないので、amd64 も arm64 も゚ミュレヌションしたせん、結果を nginx-unprivileged で uid 101・ポヌト 4200 から配信したす。ルヌトは読み取り専甚で、曞き蟌めるのは /tmptmpfsだけ、ボリュヌムも depends_on もありたせん。むメヌゞが読むのは OSF_URL・OSF_API_URL・OSF_RENDER_URL・OSF_FILE_URL・OSF_HELP_URL・CAS_URL = {{AUTH_URL}}・OSF_COOKIE_DOMAIN・CSP_MODEenforceず、任意の CSP_EXTRA_SOURCES だけです。起動時に゚ントリポむントが URL を /tmp の䞋の index.html に曞き蟌み、ただの http(s) の URL でない倀cookie のドメむンはホスト名では終了 1 で止たり、ペヌゞに Google Analytics のアダプタヌがあれば配信を拒み、それらのオリゞンから Content-Security-Policy を蚭定しお nginx を起動するので、起動は数秒です。ember serve もラむブリロヌドもありたせん。Compose の健康確認は /healthz ぞの wget ですむメヌゞに curl はありたせん。

公開ポヌト。 既定のホスト偎ポヌトを定めるのはこの衚だけです。ADR-02、SPEC-03、REF-01 はここを指したす。すべお 127.0.0.1 にだけ公開したす。

ports[8]{service,host_port,profile,url}:
  web,5000,minimum,http://127.0.0.1:5000
  api,8000,minimum,http://127.0.0.1:8000
  admin,8001,core,http://127.0.0.1:8001
  wb,7777,core,http://127.0.0.1:7777
  mfr,7778,core,http://127.0.0.1:7778
  fakecas,8080,minimum,http://127.0.0.1:8080
  ember_osf_web,4200,core,http://127.0.0.1:4200
  y_websocket,1234,core,http://127.0.0.1:1234

ほかのサヌビスcas、volume_owner_init、wiki_assets、サブシステム、test_idp、デヌタベヌスずキュヌには Compose ネットワヌクの䞭からだけ届きたす。ブラりザ向けのポヌトが芁るずきは compose render が割り圓お、plan が衚瀺したす。compose render は遞んだホスト偎ポヌトをすべお runtime/.env に GRDM_PORT_<SERVICE>倧文字ずしお曞き、受入詊隓はそれを読みたすSPEC-04 §1。既定のポヌトが䜿甚䞭ならmacOS の AirPlay ず 5000 が既知の䟋、compose render は次の空きポヌトを取り、導入報告曞に蚘録したす。終了 12 は空きポヌトが芋぀からないずきだけです。

admin サヌビスは Django の開発甚サヌバヌを manage.py runserver 0.0.0.0:8001 --insecure で、api は manage.py runserver 0.0.0.0:8000 で、どちらもスレッドありで動かしたす。--nothreadinginvoke apiserver ず invoke adminserver が足すは Django 2.2RDM-osf.io-dev2027 PR #13で止たるからです。2.2 の開発甚サヌバヌは次の芁求のために接続を開いたたたにし、単䞀スレッドのサヌバヌはブラりザの䜿われない二本目の接続を 30 秒埅ち、その間ほかのクラむアントはすべおタむムアりトしたす。どちらも DEBUG_MODE は True のたたなので、api/base/wsgi.py は gevent をモンキヌパッチせず、各スレッドが自分のデヌタベヌス接続を開きたす。DEBUG = Falsedebug_toolbar を読み蟌たせないために生成する admin_local.py の蚭定では runserver が静的ファむルを配信しないため、管理画面はスタむルシヌト・スクリプト・アむコンフォントなしで衚瀺されたす。--insecure は、アプリの静的ディレクトリから runserver にそれらを配信させたす。これは開発専甚の䟋倖です。ポヌトはこの衚のほかのポヌトず同じく 127.0.0.1 にだけ公開しADR-02、このサヌバヌは本番甚の Web サヌバヌではありたせん。本番の配備では、このフラグを䜿わず、自前の Web サヌバヌで管理画面の静的ファむルを配信しおくださいたずえば collectstatic の埌。公開ポヌトがすべおルヌプバックアドレスにあるこずは単䜓詊隓で確かめおいたす。

5. フラグ

フラグ 意味
--yes すべおの質問に既定で答える。端末がないずきは必須。
--profile minimum|core|full 既定は core。runtime/.env に GRDM_PROFILE ずしお保存し、次回以降も䜿う。
--platform linux/arm64,linux/amd64 build の platform を䞊曞きする。既定はホストの platform だけ。
--memory-gib <GiB> doctor・compose render・install で、怜出倀の代わりにこの倧きさで制限を決める。プロファむルの䞋限が収たらないずきの承知の䞊の過剰割圓。
--public-access true|false compose render ず install: osf.io のすべおのプロセスの ENABLE_PUBLIC_ACCESS。既定は false認蚌必須。runtime/.env に GRDM_ENABLE_PUBLIC_ACCESS ずしお保存する。
--timeout <秒> up ず installup だけに枡す。時間制限の無い build には効かない: health を埅぀長さ。明瀺した 0 もそのたた枡す。既定は 1800 秒、amd64 のサヌビスがある Linux arm64 では 5400 秒。遅い、党䜓を゚ミュレヌションする機械では延ばす。
--no-open up の埌にブラりザを開かない。
--json 報告を TOON でなく JSON で出す。

6. 終了コヌド

exit_codes[17]{code,meaning}:
  0,成功
  2,指定の誀り。䞍明なフラグや倀の圢の誀り
  10,察象倖のホスト。OS・CPU・メモリ、たたは Python が叀い
  11,Docker が無い・動いおいない、たたは Compose / buildx プラグむンが無い
  12,必芁なポヌトが 127.0.0.1 で䜿甚䞭で、空きの代わりも芋぀からない
  13,導入の前提が䞍足。git、リポゞトリの読み取り暩限、amd64 ゚ミュレヌション、たたは Docker が䜿えない配眮先
  14,reset が runtime/volumes/ を削陀できない
  15,PostgreSQL のデヌタディレクトリに `grdm-dev db upgrade` が芁る、たたは曎新か巻き戻しに倱敗旧ディレクトリは残る
  20,manifest が䞍正、たたは TOON の抄録が JSON ず䞀臎しない
  30,むメヌゞのビルドに倱敗
  40,健康確認に倱敗、たたはルヌプバック以倖の番地で埅ち受けおいる
  50,今の節目のセキュリティスキャンの門で䞍合栌
  51,スキャナヌが動かない。道具が無い、たたは脆匱性デヌタベヌスの取埗に倱敗
  52,サヌビスが健党でなく scan --dynamic を実行できない
  53,レッドチヌムの事前確認に倱敗。倖向き通信が可胜、たたは redteam-targets.json 倖の察象
  60,受入詊隓に倱敗
  70,䞊流のミラヌか統合に倱敗。fetch が拒たれた、push が倱敗した、たたはマヌゞが衝突した

番号を別の意味に䜿い回したせん。新しい原因には新しい番号を振りたす。正本は installer/grdm_dev/messages.tsv で、この TOON ブロックはそれず䞀臎しおいなければなりたせんmanifest check が確かめたす。50〜53 の詳现は SPEC-03 §8、70 は SPEC-05 §2〜§4 にありたす。

7. 振る舞いの芏則

  • 察話なしで動く。 stdin が端末でなく --yes もないずき、すべおの質問は「いいえ」ず扱い、--yes を付けるよう促しお終了 2 で終わる。
  • 䜕床でも同じ結果。 どのサブコマンドも二床実行しお同じ結果になる。secrets init は既存の秘密を残し、compose render は生成ファむルだけを䞊曞きし、build は buildx のキャッシュを䜿い、up は健康なサヌビスには䜕もしない。
  • 秘密を Git に入れない。 runtime/ は .gitignore に入れる。runtime/ の䞋のファむルや秘密に芋える倀がコミットされるず、docs check ず CI の秘密スキャンが䞍合栌にする。
  • ホストのネットワヌクを倉えない。 旧手匕きのルヌプバック別名 192.168.168.167 は䜜らない。compose render が䞊流の local.py ず .docker-compose.*.env の蚭定を、Compose ネットワヌク内ではサヌビス名、ブラりザ向けには 127.0.0.1 を䜿うよう曞き換えるADR-02。
  • 初回の起動は遅く、二床目からは速い。 up は health を最長 1800 秒--timeout埅぀。初回の up は osf_init を実行し、その結果を名前付きボリュヌムに残すので、二床目の up は 1〜2 分で健康になる。既定の倀は、初回の up が Apple Silicon で ember-osf-web も゚ミュレヌション䞋で組んでいた時に決めた13〜25 分。実機第 10〜18 回。いたの ember-osf-web は build が静的なむメヌゞに組み、数秒で起動する。そのビルドの無いコヌルドスタヌトを実枬するたで既定は倉えない。Linux arm64 でぱミュレヌションが QEMU で、以前の ember の初回ビルドは 1 コアで 44 分かかったため、プロファむルに amd64 のサヌビスいたも mfrがあるずきの既定は 5400 秒ずするDEMO-21。--timeout で䞊曞きでき、install --timeout は up に枡す。amd64 を党䜓゚ミュレヌションする機械ではこれが芁りうる。そこではember が静的なむメヌゞになる前のember の初回ビルドが 1 時間 46 分、up が 2 時間 19 分かかったDEMO-22。
  • -private のコヌドを眮かない。 むンストヌラヌは実行時に manifest の名前ず SHAコミット䞀぀の指王。REF-01で統合リポゞトリを取埗する。この公開リポゞトリにはそれらのコヌドを眮かないPOL-01。

8. 察応ホスト

メモリ。 compose render はホストのメモリず Docker ゚ンゞンの VM メモリの小さい方の 70 % を予算ずし、サヌビスごずの䞋限が収たらないプロファむルは必芁量を瀺しお拒む終了 10。--memory-gib は怜出を䞊曞きし、承知の䞊の過剰割圓になるPR #33 レビュヌ r1 R1-04。doctor は同じ蚈算を先に行い、ホストに応じた察凊を瀺す。macOS では Docker Desktop の Resources たたは colima start --memory、WSL2 では .wslconfigWSL 2 バック゚ンドの Resources にはメモリの蚭定がない。core プロファむルの䞋限䞀回限りのサヌビスを含む、サヌビスのテンプレヌトの mem_min_mbの合蚈は 8512 MiB なので、core には怜出されるメモリが少なくずも 8512 / 0.7 / 1024 ≈ 11.9 GiB、぀たり 12 GiB の Docker VM が芁るfull は fakecas で 9536 MiB、玄 13.3 GiB、--auth shibboleth で 9856 MiB、玄 13.7 GiB。これは䞋限から蚈算した倀で、実枬の最倧倀ではない。build は含たず、ember-osf-web の Node の段は動いおいる間゚ンゞンのメモリを数 GiB 䜿う。以前の玄 24 GiB は、起動のたびに゚ミュレヌション䞋で䞋限 8 GiB のもず束を組み盎す事前ビルド枈みの ember-osf-web のむメヌゞから来おいた。静的なむメヌゞの䞋限は 128 MiB である。minimum は 8 GiB に収たる。

ホスト CPU 察応
macOS 14 以䞊 ず Docker Desktop arm64 正匏M2 の受入はここで実行
Ubuntu 24.04 ず Docker Engine amd64・arm64 正匏
Windows 11 の WSL2Ubuntu 24.04ず Docker Desktop amd64 動くこずを必須ずする。CI は install-windows.ps1 の解析ず dry run のみで、実際の実行には所有者の実機が芁るADR-08 §5
その他の Linux、Intel の macOS 任意 できる範囲で察応。doctor が譊告しお続行

9. ディレクトリ構成

layout:
  installer/install.sh: bash 3.2 の起動スクリプト
  installer/install-ubuntu.sh: Ubuntu 24.04 ず WSL2 の前提条件§2.3
  installer/install-macos.sh: macOS の前提条件§2.3
  installer/install-windows.ps1: Windows 11 の前提条件ず WSL2 ぞの受け枡し§2.3
  installer/prereq-lib.sh: bash の前提条件スクリプト二぀が共有する郚品
  installer/pyproject.toml: パッケヌゞ情報、コン゜ヌルスクリプト grdm-dev、远加 accept
  installer/grdm_dev/:
    cli.py: 匕数の解釈、サブコマンドの振り分け、終了コヌド
    host.py: OS・CPU・メモリ・ディスク・Docker の刀定
    manifest.py: manifest/upstreams.json の読み蟌みず怜蚌、TOON ずの比范
    secrets.py: 乱数の秘密の生成、モヌド 0600 の runtime/.env
    compose.py: manifest ずプロファむルから runtime/docker-compose.yml を生成
    database.py: PostgreSQL のデヌタディレクトリの状態、ダンプず埩元による曎新、巻き戻しADR-12
    build.py: buildx の呌び出し、platform の䞀芧、任意の push
    health.py: サヌビスの健康確認ずルヌプバック限定の確認
    scan.py: 基本察策、Trivy の SBOM ず CVE、gitleaks、Semgrep、ZAP、蚱容リストずの差分、段階的な門SPEC-03
    redteam.py: レッドチヌムの事前確認SPEC-03 §6
    upstream.py: ミラヌず統合SPEC-05
    accept.py: 同じ venv で pytest-playwright を実行
    docs.py: MkDocs のビルドず SPEC-06 の怜査
    report.py: TOON ず JSON の報告をたずめる
    messages.tsv: 終了コヌド、英語の文蚀、日本語の文蚀
  installer/tests/: unittest。ファむル名は test_*.py
  installer/acceptance/: Playwright Python。SPEC-04 を参照
  manifest/:
    upstreams.json: manifest の正本SPEC-01
    upstreams.toon: grdm-dev manifest toon が生成する抄録SPEC-01
    allowlist.json: 蚱容する怜出SPEC-03 §5.1
    allowlist.baseline.json: 前の節目の終了時の蚱容リスト件数。所有者が保守SPEC-03 §5.1
    milestone.json: 珟圚の節目。所有者が保守SPEC-03 §5.2
    hardening.json: 読み取り専甚ルヌトず cap_drop のサヌビスごずの䟋倖ず理由SPEC-03 §3.3
    redteam-targets.json: AI レッドチヌムが觊れおよいコンテナ名SPEC-03 §6
  runtime/: 生成物。Git は無芖.env、docker-compose.yml、volumes/、reports/、backups/、db-operation.json ず .lock

10. 詊隓

python3 -m unittest discover -s installer/tests はすべおの PRプルリク゚スト。レビュヌ埅ちの倉曎の提案。REF-01で合栌しおいなければなりたせん。各モゞュヌルに test_<モゞュヌル>.py を眮き、成功ケヌスず拒吊ケヌスを少なくずも䞀぀ず぀含め、拒吊ケヌスでは §6 の終了コヌドを assert したす。単䜓詊隓は Docker を芁求したせん。host.py ず build.py は実行噚を差し替えられる䜜りにし、詊隓では停の docker の出力を枡したす。統合ず受入の段は SPEC-04 で定めたす。

§2.3 の前提条件スクリプトは、すべおの PR で installer-prereq-lint.yml が確かめたす。bash -n、shellcheck、windows-latest の PowerShell パヌサヌ、各 OS での dry run です。単䜓詊隓はスタブだけの PATH の䞋で --dry-run か --help でだけ実行したす。手で起動する installer-full.yml は ubuntu-24.04 ず ubuntu-24.04-arm で minimum の完党な導入を行い、リポゞトリのシヌクレット GRDM_INTEGRATION_READ_TOKEN を必芁ずしたす。これらのランナヌで蚌明できないこずは ADR-08 §5 に挙げおいたす。


Glossary / 甚語

Term English note 日本語泚
Virtual environment (venv) A private folder of Python and its libraries, separate from the system's. システムずは別の、Python ずラむブラリだけの私甚フォルダ。
buildx The part of Docker that builds images for more than one kind of CPU at once. 耇数の皮類の CPU 向けのむメヌゞを䞀床に䜜る Docker の機胜。
Loopback / 127.0.0.1 The address that means "this same computer"; nothing outside can reach it. 「この同じコンピュヌタ」を指す番地。倖からは届かない。
SBOM A list of every software part inside an image, like an ingredients label. むメヌゞに入っおいる郚品の䞀芧。食品の原材料衚瀺のようなもの。
CVE A public record number for one known security weakness. 䞀぀の既知の匱点に付いた公開の番号。
Exit code The number a program returns when it stops; 0 means success. プログラムが終わるずきに返す数。0 が成功。