Skip to content

Latest commit

 

History

History

environment

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
 
 
 
 
 
 

README.md

Environment guide / 環境蚭定ず開発環境

Summary: How to install the 2027 developer environment for GakuNin (Japan's academic identity federation) RDM using the installer script, including prerequisites, step-by-step commands, everyday operations, security notes, and troubleshooting. All services run on 127.0.0.1 with no host network changes. 抂芁: GakuNin日本の孊術認蚌連携RDM の 2027 開発環境をむンストヌラヌで導入する手順。前提条件、ステップごずのコマンド、日垞操䜜、セキュリティ泚意点、トラブルシュヌティングを含む。すべおのサヌビスは 127.0.0.1 で動䜜し、ホストのネットワヌク蚭定は倉えたせん。

Jump: English · 日本語

  • Version / 版: 1.11 — 2026-11-13. Learned: a sentence that names the current milestone is live state, not history, so it changes in the same PR as manifest/milestone.json: the owner closed M2 on 2026-11-13, the file now says M3, and from now on scan fails with exit 50 if the allow-list grows past 58 entries.  珟圚の節目を名指す文は履歎ではなく珟圚の状態なので、manifest/milestone.json ず同じ PR で倉える。所有者は 2026-11-13 に M2 を閉じ、ファむルは M3 になった。これからは蚱容リストが 58 項目を超えるず scan は終了 50 で倱敗する。 1.10 — 2026-11-13. Learned: a scan line that reads ok has to say what it did not scan: with mandatory sign-in ZAP cannot enter web, and the report now lists that target as skipped (skipped_targets), not as scanned (PR #56 review r1 R1-01).  ok ず読める怜査の行は、怜査しなかったものを蚀わなければならない。必須サむンむンでは ZAP は web に入れず、報告はその察象を怜査枈みでなく察象倖skipped_targetsずしお茉せるPR #56 レビュヌ r1 R1-01。 1.9 — 2026-11-12. Learned: an upgrade guide has to be an order of commands, because each step needs the one before: the new secrets must exist before compose render, compose render before build (tags) and again after it, and the search index rebuild only after up; secrets rotate is not that first step, since it needs a healthy old stack and rolled back here when the former ember image took more than 300 seconds to start.  アップグレヌドの手匕きはコマンドの順序でなければならない。どの段も前の段を芁するからである。新しい秘密は compose render の前に、compose render は buildタグの前ず埌に、怜玢の玢匕の再構築は up の埌に芁る。secrets rotate はその最初の段ではない。健康な旧スタックを芁し、ここでは以前の ember のむメヌゞの起動が 300 秒を超えお巻き戻った。 1.8 — 2026-11-11. Learned: a troubleshooting entry that names a workaround goes stale the day the workaround ends: ember-osf-web is built from source again as a static image, so the DEMO-20 cases now say that the prebuilt image was the past state and what build does now (RDM-ember-osf-web-dev2027 PR #2 review r1 R1-03).  回避策を名指しする障害察応の項は、その回避策が終わった日に叀くなる。ember-osf-web は再び゜ヌスから静的なむメヌゞずしお組たれるので、DEMO-20 の事䟋は事前ビルド枈みのむメヌゞが過去の状態だったこずず、いたの build の動きを曞くようにしたRDM-ember-osf-web-dev2027 PR #2 レビュヌ r1 R1-03。 1.7 — 2026-11-12. Learned: the guide must not promise what an option cannot do: --timeout lengthens only the wait of up, never the build (PR #50 review r1 R2).  手匕きは、オプションにできないこずを玄束しおはならない。--timeout が延ばすのは up の埅ちだけで、ビルドではないPR #50 レビュヌ r1 R2。 1.6 — 2026-11-12. Learned: an amd64 test machine on Apple Silicon is a fully emulated computer, so it needs two more host tools and a long first start, and it compiled osf.io's scientific Python about ten times slower than Rosetta did (a full build there was not finished after 5 h 12 min); the guide now says so and says how to give up a longer wait through the one command, which does not shorten the build (DEMO-22).  Apple Silicon 䞊の amd64 の詊隓機は党䜓を゚ミュレヌションする蚈算機なので、ホストの道具が二぀倚く芁り、最初の起動も長く、osf.io の科孊蚈算の Python のコンパむルは Rosetta の玄 10 倍遅かったそこでのビルド党䜓が 5 時間 12 分埌も未完。手匕きはそれを曞き、䞀぀のコマンドで up の埅ちを延ばす方法も瀺すビルドは短くならないDEMO-22。 1.5 — 2026-11-10. Learned: a safety check should say what it does not cover: the shared-folder check looks for four names directly under each shared mount point, decoded as the kernel escapes them, not for every credential anywhere (PR #44 review r1 R1).  安党のための怜査は、䜕を芋ないかも蚀うべきである。共有フォルダの怜査は、カヌネルの゚スケヌプを埩号した各共有 mount 先の盎䞋にある四぀の名前だけを探し、どこにある資栌情報でも芋぀けるわけではないPR #44 レビュヌ r1 R1。 1.4 — 2026-11-10. Learned: a test VM is only isolated if nothing of the host is shared by default: Lima's Ubuntu template mounted the host home and showed ~/.config/gh inside the VM, so the Lima steps below share only read-only mirrors and install-ubuntu.sh stops when credentials are visible (DEMO-21).  テスト甚の VM は、既定でホストの䜕も共有しないずきだけ隔離されおいる。Lima の Ubuntu テンプレヌトはホヌムを mount し ~/.config/gh を VM から芋せたので、䞋の Lima の手順は読み取り専甚のミラヌだけを共有し、install-ubuntu.sh は資栌情報が芋えるず止たるDEMO-21。 1.3 — 2026-11-10. Learned: on a Linux server image the acceptance browser needs two more steps than on a Mac, a library for Playwright's driver and Chromium's system libraries, so §3.9 lists them (DEMO-21).  Linux のサヌバヌむメヌゞでは受入詊隓のブラりザに Mac より二぀倚い手順、Playwright のドラむバヌ甚のラむブラリず Chromium のシステムラむブラリが芁るので、§3.9 に茉せたDEMO-21。
  • Version / 版: 1.2 — 2026-11-10. Learned: telling a reader that the installer checks each prerequisite is not the same as helping them get one, so the guide now starts from a script for each OS (ADR-08).  「むンストヌラヌが前提条件を確認する」ず䌝えるこずは、それを揃える手助けにはならない。そこで手匕きは OS ごずのスクリプトから始めるADR-08。
  • Version / 版: 1.1 — 2026-11-06. Learned: the Project Metadata edit page needs a waffle flag that no setup step turned on, so the legacy startup steps now set ember_edit_draft_registration_page once after the first migration (PR #17); the 2027 installer has no equivalent step yet.  Project Metadata の線集画面には、どの手順も有効にしおいなかった waffle フラグが必芁なため、旧ガむドの起動手順に初回マむグレヌション埌の ember_edit_draft_registration_page 蚭定を远加したPR #17。2027 むンストヌラヌには盞圓する手順がただ無いず分かった。
  • Version / 版: 1.0 — 2026-11-06. Learned: full startup is not yet verified by a recorded run: the ember-osf-web (the browser interface) base image is end-of-life and current Docker (the tool that runs containers: boxes that each hold one program and everything it needs) refuses to pull it, so the manifest (the list of components and the exact source revisions they are built from) already configures a digest-pinned prebuilt image for ember-osf-web as a fallback until M4 modernizes its Dockerfile (DEMO-20, manifest/upstreams.json).  完党な起動はただ実行蚘録で怜蚌できおいない。ember-osf-webブラりザ画面のベヌスむメヌゞがサポヌト終了で珟行 Dockerコンテナ䞀぀のプログラムず必芁なものを入れた箱を動かす道具が取埗を拒むため、M4 で Dockerfile を近代化するたでの代替ずしお、manifest郚品ず、それを組む正確な゜ヌス版の䞀芧にはダむゞェスト固定の配垃枈みむメヌゞがすでに蚭定されおいるDEMO-20、manifest/upstreams.json。
  • Version / 版: 0.1 — 2026-11-05. Initial bilingual skeleton pointing to the legacy guide.  旧ガむドを指す最初の二蚀語の骚組み。
  • Normative for: docs/guides/environment/
  • Parent index / 芪玢匕: Guides
  • Related: SPEC-02 Installer CLI · ADR-02 Network Model · ADR-03 Staged Security Gate · SPEC-03 Security Gate · SPEC-04 Acceptance Tests · SPEC-06 Documentation Conventions · DEMO-20 Core Install on Mac Studio · REF-01 Glossary
  • Used by: Guides index · DEMO-20 Core Install on Mac Studio

English

→ 日本語版ぞ

1. Quick start

Install the 2027 developer environment for GakuNin RDM with these three commands:

git clone https://github.com/RCOSDP/RDM-developer-guide.git
cd RDM-developer-guide
./installer/install.sh --yes

When the installer completes, grdm-dev up opens your browser at the web URL it reports. The default is http://127.0.0.1:5000, but if port (a numbered door a program listens on) 5000 was busy the installer chose another port and recorded it in runtime/.env as GRDM_PORT_WEB; always use the URL or port printed in the report rather than assuming 5000.

Caveat (2026-11-06): a complete startup of the core profile (a named subset of services to run) has not yet been verified by a recorded run. The ember-osf-web Dockerfile cannot be built with current Docker, so the manifest already runs a digest-pinned prebuilt image for that component (see §3.5 and §6). Expect the next recorded run in DEMO-20.

Prerequisites by OS

  • macOS 14 or newer, Apple Silicon (arm64): Docker Desktop installed
  • Ubuntu 24.04, amd64 (the Intel/AMD type of CPU; Apple Silicon is arm64) or arm64: Docker Engine installed
  • Windows 11 with WSL2 (Windows Subsystem for Linux 2, a way to run Ubuntu inside Windows; see REF-01) and Ubuntu 24.04: Docker Desktop installed

Note: The installer checks each prerequisite. It exits with code 10 if your host is unsupported and 11 if Docker is missing, not running, or lacks the Compose or buildx (multi-platform image builder) plugin. See SPEC-02 §8 for the full host list.

Prepare the host with the per-OS script

If your computer does not have the prerequisites yet, run the script for your OS instead of install.sh. Each one shows what it will change, asks before any administrator action, and ends by running install.sh. Add --yes to consent to everything in advance, or --dry-run to only see the plan. Run them from the repository folder.

OS Command
Ubuntu 24.04 ./installer/install-ubuntu.sh
macOS (Apple Silicon) ./installer/install-macos.sh
Windows 11 (in PowerShell) powershell -ExecutionPolicy Bypass -File .\installer\install-windows.ps1

Expected result: the plan is printed, and after your answer the installer's report ends with the web URL.

On Windows you only need this one script file from the repository. It enables WSL2, installs Ubuntu 24.04, checks Docker Desktop and its WSL integration, and clones the repository inside WSL, never under /mnt/c, because the Windows disk is slow from WSL and changes line endings. Read the script before you run it. -ExecutionPolicy Bypass applies to this one run only.

Note: The integration repositories are private. Before the build, give git your own access where the install runs (inside WSL on Windows), for example gh auth login and then gh auth setup-git. The scripts never ask for, read or store a token.

Trying the Ubuntu script in a Lima VM on a Mac

Lima (a tool that runs Linux virtual machines on macOS) is a quick way to test the Ubuntu path on a Mac (DEMO-21).

Warning: Lima's Ubuntu template mounts your home directory into the VM (read-only), even when your configuration lists its own mounts:, because the template's list is merged in. Your ~/.config/gh/hosts.yml, which holds your GitHub token, is then readable inside the VM. install-ubuntu.sh stops with exit 10 when one of .config/gh/hosts.yml, .git-credentials, .netrc or .docker/config.json exists directly under the mount point of a shared folder. It does not search deeper, so the steps below still matter.

Write the VM configuration, create the VM, then remove the home mount before you start it. Run on the Mac:

limactl create --name grdm-ubuntu2404 --tty=false my-vm.yaml   # base: template:ubuntu-24.04, your own mounts
# open ~/.lima/grdm-ubuntu2404/lima.yaml and delete the line  - location: "~"
limactl start grdm-ubuntu2404
limactl shell grdm-ubuntu2404 -- mount | grep -E 'virtiofs|9p|sshfs'

Expected result: only the folders you chose are listed; no line ends in your home directory.

To test Ubuntu amd64 on an Apple Silicon Mac, set vmType: qemu and arch: x86_64 in my-vm.yaml and run brew install qemu lima-additional-guestagents first (Lima needs QEMU and the amd64 guest agent for this). The whole virtual machine is then emulated, so expect everything to be many times slower than on real hardware, and give the first start a long --timeout. To make the user a non-root user whose uid is not 1000, add user: {name: grdm, uid: 2002, home: /home/grdm} (DEMO-22).

To give the VM the private repositories without a token, share read-only bare mirrors (git clone --mirror on the Mac) and point git at them inside the VM with git config --global url."file:///<mirror>.git".insteadOf https://github.com/RCOSDP/<repo>.git.

Note: Docker Desktop is never installed by these scripts, because its licence depends on your organisation. Homebrew is not installed either; install-macos.sh tells you where to get its signed package. See ADR-08 for the reasons.


2. What you get

The installer creates a self-contained environment under runtime/ with no changes to your host network. It uses two Docker Compose (the tool that starts several containers together from one file) networks:

  • Internal network grdm — services talk to each other using Compose service names (e.g., web, api, postgres). No ports are published and there is no route to the Internet.
  • Publishing network grdm-edge — the seven browser-facing services (web, api, admin, wb, mfr, fakecas, ember_osf_web) also attach here so their ports can be published on 127.0.0.1. Because it is an ordinary bridge network, these seven services already have outbound (egress) access; no other service does unless you grant it (§4).
flowchart TD
    subgraph HOST["Host computer (macOS / Ubuntu / WSL2)"]
        BROWSER["Browser → http://127.0.0.1:GRDM_PORT_WEB"]
        subgraph DOCKER["Docker Compose"]
            INTERNAL[internal network grdm]
            PUBLISHING[public bridge network grdm-edge]
        end
    end
    
    subgraph SERVICES["Running services"]
        web[web (default port 5000)]
        api[api (default port 8000)]
        postgres[postgres]
        rabbitmq[rabbitmq]
    end
    
    BROWSER -->|"127.0.0.1:<web port>"| web
    web -->|"http://api:8000"| api
    api -->|"postgres:5432"| postgres
    web -->|"rabbitmq:5672"| rabbitmq
    
    BROWSER --- PUBLISHING
    web --- PUBLISHING
    api --- PUBLISHING
    
    web --- INTERNAL
    api --- INTERNAL
    postgres --- INTERNAL
    rabbitmq --- INTERNAL
Loading

3. Step by step

./installer/install.sh --yes creates a Python virtual environment at .venv/ (a venv is a private folder of Python and its libraries, separate from the system), installs grdm-dev into it, and then runs grdm-dev install. That command executes the following steps in this exact order and stops at the first non-zero exit (SPEC-02 §2.1, installer/grdm_dev/install.py):

  1. doctor
  2. plan
  3. secrets init — only when runtime/.env does not exist yet
  4. compose render
  5. build
  6. up
  7. health --network
  8. scan
  9. report

The acceptance tests (accept, §3.9) are not part of this sequence; run them manually afterwards. The subsections below describe each step so you can also run it on its own after the bootstrap has created .venv/.

3.1 grdm-dev doctor

Check that your host meets all requirements (run on its own after the bootstrap created .venv/):

.venv/bin/grdm-dev doctor

Success: You see a TOON report (TOON is a compact text form of JSON data that people and AI read easily; see REF-01) showing your OS, CPU, memory, free disk, and Docker version.

Failure exit codes: 10 — unsupported host (OS, CPU, memory, or Python < 3.11); 11 — Docker missing, not running, or Compose / buildx plugin absent.

3.2 grdm-dev plan

See which images will be built and which services will start:

.venv/bin/grdm-dev plan --profile core

A manifest is the list of components and the exact source revisions they are built from (manifest/upstreams.json; see REF-01). A profile is a named subset of services to run: minimum, core (default), or full (SPEC-02 §4). The choice is saved in runtime/.env as GRDM_PROFILE and reused later.

Success: You see a TOON report with the services and their published ports.

Failure exit code: 20 — manifest invalid or TOON excerpt disagrees with JSON.

3.3 grdm-dev secrets init

Generate random secrets and write them to runtime/.env with mode 0600 (owner read/write only):

.venv/bin/grdm-dev secrets init

Success: A new runtime/.env file appears with random database passwords, Django secret key, and CAS (the sign-in service protocol GRDM uses) keys.

Failure exit code: 2 — usage error (e.g., missing --force if runtime/.env exists).

Security note: The installer never writes default or example passwords. Every secret is generated from your OS's random source.

3.4 grdm-dev compose render

Generate the Docker Compose file from the manifest and profile:

.venv/bin/grdm-dev compose render --profile core

Success (exit 0): runtime/docker-compose.yml appears with all services configured for your host, and any port that had to move away from its default is reported.

Failure exit codes: 20 — manifest invalid; 2 — usage error, for example runtime/.env is missing (run secrets init first) or --egress names an unknown service; 12 — a required port is in use and no free alternative was found within +100 (§6).

3.5 grdm-dev build

Build or pull all images:

.venv/bin/grdm-dev build

Success: All images are built or pulled, and a TOON report shows their status (built, prebuilt, ...).

Failure exit code: 30 — image build or prebuilt pull failed (e.g., an EOL base cannot be built for arm64 without emulation). EOL means end of life: the vendor no longer fixes bugs or security holes (REF-01). Emulation means running an linux/amd64 image on an arm64 CPU through Docker's built-in CPU translation; it is slower but works for most images.

Real cases from DEMO-20:

  • modular-file-renderer (the file preview service): Built with emulation (build_platform: linux/amd64) because pandas==0.25.1 has no arm64 wheel (a prebuilt Python package file; without one, pip must compile from source, which fails on this EOL base).
  • ember-osf-web: At the time, the source build failed on every CPU because the base image used Docker manifest v2 schema 1, which current Docker refuses, so the manifest carried a digest-pinned prebuilt_image that build pulled instead (DEMO-20). The Dockerfile has since been modernized (RDM-ember-osf-web-dev2027 PR #2): build builds ember-osf-web from its pinned commit on your own CPU, without emulation, into a static nginx image, and the row says built.

3.6 grdm-dev up

Start all services and wait for health:

.venv/bin/grdm-dev up --profile core

Success: All services report healthy, and the browser opens at the web URL up reports (http://127.0.0.1:<GRDM_PORT_WEB>, default port 5000). Add --no-open to skip the browser.

Failure exit code: 40 — one or more services did not become healthy within the timeout.

3.7 grdm-dev health and health --network

Manually check service health:

.venv/bin/grdm-dev health            # service responses only
.venv/bin/grdm-dev health --network  # also verify that every published port listens on 127.0.0.1 only

Success: All services report healthy; with --network, the report also shows loopback_only: true.

Failure exit code: 40 — one or more services are unhealthy; with --network, also when any container port is bound to an address other than 127.0.0.1. Plain health does not check host exposure, so only health --network proves loopback-only publishing. The automatic install sequence runs health --network.

3.8 grdm-dev scan

Run the whole security gate of SPEC-03:

.venv/bin/grdm-dev scan

Without flags, scan runs every part: baseline controls, the Trivy (a scanner that lists known weaknesses in images) image scanner's SBOM (software bill of materials: the list of every part inside an image) and CVE list (a CVE is a public identifier for one known security weakness), the gitleaks secret scan, Semgrep (static analysis that reads source code for dangerous patterns), and the OWASP ZAP (a scanner that probes the running website the way an attacker would) dynamic baseline. The flags --baseline, --secrets, and --dynamic each run one part only and are not the whole gate:

.venv/bin/grdm-dev scan --baseline   # subset: baseline controls of runtime/docker-compose.yml and runtime/.env only
.venv/bin/grdm-dev scan --secrets    # subset: gitleaks over the repository only
.venv/bin/grdm-dev scan --dynamic    # subset: OWASP ZAP baseline only (needs healthy services)

Gate rule by milestone (manifest/milestone.json, currently M3 since the owner closed M2 on 2026-11-13, so the allow-list may hold at most the M2 count of 58 entries, see the status board; ADR-03, SPEC-03 §5): the gate data — manifest/milestone.json, the allow-list manifest/allowlist.json (the written list of known findings accepted for a limited time) and its baseline manifest/allowlist.baseline.json — must be readable and well-formed at every milestone, M1 included: an unreadable file or an allow-list entry missing one of its six fields exits 50 (SPEC-03 §5.1 rule 1). Baseline-control violations (default secrets, publishing outside loopback, privileged: true, a missing grdm internal network) also exit 50 at every milestone. Only with valid gate data and passing baseline controls are M1–M3 report-only for vulnerability findings: the run exits 0 and records them. From M2 the allow-list may not grow: scan compares the entry count with manifest/allowlist.baseline.json and a larger count exits 50 (at M1 the count is only reported). At M4 any HIGH or CRITICAL finding not in the allow-list exits 50; in addition, passing M4 requires that the first real AI red-team run (authorized attack testing of the isolated environment, SPEC-03 §6) has been completed and every intrusion path it found has been fixed or allow-listed — the red-team preflight (grdm-dev redteam preflight, a readiness check that proves isolation before a run) is not that run. At M5 every CRITICAL or HIGH finding exits 50, allow-listed or not; the allow-list may contain no CRITICAL or HIGH entry (scan exits 50 if it does); and the AI red team must report zero unresolved intrusion paths. scan itself enforces the data validity, baseline, count, and severity rules; the M4 red-team completion and the M5 zero-paths result are milestone acceptance requirements that the owner records with the red-team evidence (SPEC-03 §6–7), not checks scan performs.

Success: Exit 0; the report under runtime/reports/scan_<date>.json (plus TOON) shows the baseline controls passed and the findings for the current milestone.

Failure exit codes: 50 — gate failed for the current milestone (see rule above); 51 — a scanner could not run (Trivy, gitleaks, or Semgrep missing, or its vulnerability database could not be downloaded); 52 — --dynamic was requested while services are unhealthy.

Limit of the dynamic part: with mandatory sign-in (ENABLE_PUBLIC_ACCESS=false, the default) web answers an anonymous request only with a redirect to the sign-in page, which ZAP cannot open. When the scan itself confirms that redirect and that it goes to the configured sign-in address, web is listed under skipped_targets with a note "ZAP NOT RUN on web" and the run can still exit 0; the pages behind sign-in were then not scanned by ZAP. Any other failure to reach a target, such as a redirect elsewhere, stays exit 51.

3.9 grdm-dev accept (manual, separate step)

The acceptance tests (SPEC-04) are not run by install. They need the optional Python extra and a Chromium build in the existing .venv/, installed once:

.venv/bin/pip install -e "installer[accept]"
PLAYWRIGHT_BROWSERS_PATH=.venv/.playwright .venv/bin/playwright install chromium

On Linux (Ubuntu 24.04) two more commands are needed, both with sudo (DEMO-21). Run this one before the two commands above, because Playwright's driver does not start without it:

sudo apt-get install -y libatomic1

and this one after them, to add Chromium's system libraries (it asks for sudo itself):

PLAYWRIGHT_BROWSERS_PATH=.venv/.playwright .venv/bin/playwright install-deps chromium

Then run the tests with --seed, which creates disposable test users, runs the browser scenarios, and removes those users again within the same run (there is no persistent seed step):

.venv/bin/grdm-dev accept --seed

Success: All tests pass, and a report is written under docs/demo/runs/<run-id>/.

Failure exit codes: 2 — the extra or Chromium is not installed (the message repeats the two commands above); 40 — the integration precheck failed, so the browser tests did not start (fix health first); 60 — one or more tests failed.

Tip: --only <scenario> runs one scenario; --headed shows the browser window.


4. Everyday commands

Start, stop, reset

.venv/bin/grdm-dev up       # start services and wait for health
.venv/bin/grdm-dev down     # stop containers, keep volumes
.venv/bin/grdm-dev reset    # stop and delete runtime/volumes/

Tip: Add --yes to skip confirmation prompts.

View logs

docker compose -f runtime/docker-compose.yml logs -f web api

Note: The generated runtime/docker-compose.yml uses the service names from the manifest.

Change profile

.venv/bin/grdm-dev compose render --profile full --yes
.venv/bin/grdm-dev up --yes

Egress control

The seven publishing services on grdm-edge (web, api, admin, wb, mfr, fakecas, ember_osf_web) already have outbound access to the Internet. Every other service has none by default (ADR-02 §4). --egress adds that access for the services you name, by attaching them to grdm-edge too:

# Requires the full profile (rdmcp and aipf_mcp_data_grdm are not in core); select it first or in the same command.
.venv/bin/grdm-dev compose render --profile full --egress rdmcp,aipf_mcp_data_grdm
.venv/bin/grdm-dev compose render --egress none   # clear the saved grant

The choice is saved in runtime/.env as GRDM_EGRESS_SERVICES, kept on later renders, shown by scan --baseline, and cleared with --egress none. Naming a service that is not in the selected profile is a usage error (exit 2).

Default ports

Service Host port Profile
web 5000 minimum
api 8000 minimum
admin 8001 core
wb (WaterButler) 7777 core
mfr (Modular File Renderer) 7778 core
fakecas 8080 minimum
ember_osf_web 4200 core

Note: If a port is in use (e.g., macOS AirPlay on 5000), compose render finds the next free port and records it in runtime/.env as GRDM_PORT_<SERVICE>; see §6.


5. Security notes

The installer implements these controls from milestone M1 (SPEC-03 §3):

  • Secrets: All passwords and keys are generated at install time with random values, written to runtime/.env (mode 0600), and never committed to Git.
  • Network: Services talk on an internal Compose network (internal: true). Browser-facing ports are published only on 127.0.0.1; health --network verifies it.
  • Container hardening: Non-root (the program does not run as the all-powerful administrator user) user, read-only root filesystem, and cap_drop: [ALL] are the defaults for every service, together with resource limits (memory, CPU, process count). privileged: true is forbidden everywhere. A service that cannot tolerate one of the defaults (for example the PostgreSQL, RabbitMQ, or Elasticsearch images, which must write inside the image at start-up) gets a documented per-service exception in manifest/hardening.json, naming the relaxed control, the reason, the review date, and the milestone at which it is to be removed. Read-only roots therefore apply where the service tolerates them, not to every service.
  • Supply chain: Images are pulled by digest (exact fingerprint), never a floating tag such as latest.
  • Sign-in: Since RDM-osf.io-dev2027 PR #8 every data page and API route needs a signed-in user (ENABLE_PUBLIC_ACCESS=false, the default); grdm-dev compose render --public-access true turns anonymous viewing of public projects back on. The admin app asks a one-time code after the password (PR #10): an administrator without one is sent to an enrolment page on the first sign-in, and every administrator signs in again after an upgrade.
  • Search: Elasticsearch 8 is reached over TLS with its own certificate authority and a user limited to the search indices; no port is published (ADR-14).

These are the requirements the installer enforces; whether a given running environment satisfies them is shown by health --network and scan, not by this guide.

What the installer does not protect:

  • Attacks on your operating system itself (e.g., kernel vulnerabilities)
  • Phishing of the developer
  • The production GRDM service (this guide is for development only)

6. Troubleshooting

A port is in use (exit 12)

compose render starts from the port you requested or the one saved in runtime/.env (GRDM_PORT_<SERVICE>; the SPEC-02 §4 default if neither exists) and searches up to 100 ports above it for a free one. Ports already held by this project's own running containers are kept. If another program holds the port, the service moves to the first free candidate, the choice is recorded as GRDM_PORT_<SERVICE>, and the render reports it. Exit code 12 happens only when no free alternative exists in that range.

Fix: Stop the other program if you want the original port back, or simply use the port compose render / plan reports.

# macOS: AirPlay shares port 5000
sudo lsof -i :5000
# Kill the process if you do not need AirPlay

Docker missing (exit 11)

doctor fails if Docker is not installed, not running, or lacks the Compose plugin.

Fix: Install Docker Desktop (macOS, Windows) or Docker Engine (Ubuntu). Version ≥ 27 with Compose v2 plugin is required. On Ubuntu, ./installer/install-ubuntu.sh installs Docker Engine for you.

Build failed (exit 30)

This happens when an image cannot be built for your CPU architecture or a prebuilt image cannot be pulled.

Real cases from DEMO-20:

  1. modular-file-renderer on arm64: Built successfully with build_platform: linux/amd64 (emulation) because the base Python 3.5 image has no arm64 wheel for pandas==0.25.1.
  2. ember-osf-web on any platform: The source build failed because the base image used Docker manifest v2 schema 1, which current Docker refuses to pull.

Current state: ember-osf-web no longer uses a prebuilt_image: its modernized Dockerfile (RDM-ember-osf-web-dev2027 PR #2) runs the ember-cli build in a Node stage on your own CPU and produces a static nginx image, so build builds it like the other components (manifest/upstreams.json). That Node stage needs several GiB of Docker engine memory while it runs; if the ember-osf-web build fails with exit 30, check the engine's memory first.

Health check failed (exit 40)

health fails if a service does not respond. health --network additionally fails if any published port listens on an address other than 127.0.0.1; the plain command does not perform that check.

Fix: Check logs with docker compose -f runtime/docker-compose.yml logs <service>, then restart the service. For a non-loopback listener, inspect runtime/docker-compose.yml (every ports: entry must start with 127.0.0.1:) and re-run compose render.


7. What changed since the old guide

The rows below compare what README.legacy.md actually describes with the 2027 installer.

Old way (README.legacy.md) New way (2027 installer) Why
Configure a loopback alias 192.168.168.167 on the host (needs sudo) so services can reach each other Internal network grdm with Compose service names + publishing network grdm-edge on 127.0.0.1 No sudo, no host network change, no LAN exposure, same setup on macOS/Ubuntu/WSL2 (ADR-02)
Copy local-dist.py to local.py for web and api by hand; one URL serves both the browser and the services Generated settings separate internal URLs (service names) from external browser URLs (http://127.0.0.1:<port>/) Redirects and absolute URLs work from the browser without the alias (ADR-02 §4)
Hand-written docker-compose.override.yml that swaps images to niicloudoperation/*:latest and carries commented platform: lines per CPU grdm-dev compose render generates runtime/docker-compose.yml from the manifest and profile; platform: comes from the manifest's build_platform No manual edits, no host-specific file to commit by mistake, same output for everyone
Start from distribution images (niicloudoperation/*:latest, quay.io/centerforopenscience/*) and install Python/Node modules into volumes with the *_requirements services Build from manifest-pinned source revisions; prebuilt images only as documented, digest-pinned exceptions Exact reproducibility, no floating tags, no stale module volumes
Uncomment Elasticsearch limits and single-node settings in docker-compose.yml by hand on Apple Silicon compose render writes resource limits scaled from doctor and per-service exceptions from manifest/hardening.json One generated file instead of per-host edits
Default credentials shipped by the upstream Compose files (e.g., postgres/postgres; SPEC-03 §3.1) Random secrets in runtime/.env (mode 0600), generated by secrets init; scan --baseline fails if a default remains No default credentials left behind

Note: The old instructions are kept verbatim in README.legacy.md for historical reference. The legacy guide itself never documented default passwords; they come from the upstream Compose files it relied on.

8. Latest changes

  • 2026-11-12 — Elasticsearch 8, y-websocket only, mandatory sign-in, admin two-step sign-in (ADR-13 §6, ADR-14). An existing installation upgrades in this order: git pull; grdm-dev secrets init --missing (adds ELASTIC8_PASSWORD and ELASTIC8_OSF_PASSWORD, keeps every other value, drops SHAREJS_SECRET); grdm-dev compose render; grdm-dev build; grdm-dev compose render again; grdm-dev up; then once docker compose exec web invoke migrate_search to rebuild the search index from PostgreSQL (the Elasticsearch 2 data is not moved; runtime/volumes/elasticsearch_data, mongo_data and mongo_tls are no longer used and can be removed by hand). sharejs and mongo are gone, so port 7007 is no longer published. The first administrator sign-in after the upgrade asks to enrol a one-time code; keep the recovery codes it shows once.
  • 2026-11-06 — Waffle flag for the Metadata addon (PR #17). The legacy startup steps in README.legacy.md now run docker compose run --rm web python3 manage.py waffle_flag ember_edit_draft_registration_page --everyone once, right after the first database migration, in each of the three startup variants. A waffle flag (a named on/off switch stored in the database that turns a feature on for chosen users) is required to open the Project Metadata edit page of the Metadata addon. The 2027 installer (grdm-dev) does not run this step yet; if you need the Metadata addon, run the same manage.py waffle_flag command against the web service by hand. Incorporated from PR #17 by yacchin1205 (2026-11-06).

日本語

→ To English

1. クむックスタヌト

GakuNin RDM の 2027 開発環境を以䞋の䞉぀のコマンドで導入したす

git clone https://github.com/RCOSDP/RDM-developer-guide.git
cd RDM-developer-guide
./installer/install.sh --yes

むンストヌラヌが完了するず、grdm-dev up が報告した web の URL をブラりザで開きたす。既定は http://127.0.0.1:5000 ですが、ポヌトプログラムが埅ち受ける番号付きの入口5000 が䜿甚䞭だった堎合はむンストヌラヌが別のポヌトを遞び、runtime/.env に GRDM_PORT_WEB ずしお蚘録しおいたす。5000 ず決め぀けず、必ず報告に衚瀺された URL たたはポヌトを䜿っおください。

泚意2026-11-06 時点: core プロファむル起動するサヌビスの名前付きの組の完党な起動は、ただ実行蚘録で怜蚌できおいたせん。ember-osf-web の Dockerfile は珟行 Docker では組めないため、manifest はこの郚品に぀いおダむゞェスト固定の配垃枈みむメヌゞをすでに䜿う蚭定になっおいたす§3.5・§6。次の実行蚘録は DEMO-20 に远蚘されたす。

OS ごずの前提条件

  • macOS 14 以䞊、Apple Silicon (arm64): Docker Desktop をむンストヌル枈み
  • Ubuntu 24.04、amd64Intel/AMD 系の CPU の皮類。Apple Silicon は arm64たたは arm64: Docker Engine をむンストヌル枈み
  • Windows 11 + WSL2Windows Subsystem for Linux 2。Windows の䞭で Ubuntu を動かす仕組み。REF-01の Ubuntu 24.04: Docker Desktop をむンストヌル枈み

Note: むンストヌラヌは各前提条件を確認したす。ホストが未察応なら終了コヌド 10、Docker が無い・動いおいない・Compose や buildx耇数 CPU 向けむメヌゞを䜜る機胜プラグむンが無いなら 11 で終わりたす。察応ホストの䞀芧は SPEC-02 §8 を参照。

OS ごずのスクリプトでホストを準備する

前提条件がただ揃っおいないコンピュヌタでは、install.sh の代わりに OS に合ったスクリプトを実行したす。どれも倉曎点を瀺し、管理者の操䜜の前に尋ね、最埌に install.sh を実行したす。--yes を付けるず先にすべお同意し、--dry-run を付けるず予定を芋るだけです。リポゞトリのフォルダで実行したす。

OS コマンド
Ubuntu 24.04 ./installer/install-ubuntu.sh
macOSApple Silicon ./installer/install-macos.sh
Windows 11PowerShell で powershell -ExecutionPolicy Bypass -File .\installer\install-windows.ps1

期埅する結果: 予定が衚瀺され、答えた埌にむンストヌラヌの報告が web の URL で終わりたす。

Windows で必芁なのは、リポゞトリのこのスクリプトファむル䞀぀だけです。WSL2 を有効にし、Ubuntu 24.04 を入れ、Docker Desktop ず WSL 連携を確認し、リポゞトリを WSL の䞭に clone したす。Windows のディスクは WSL から遅く改行も倉わるので、/mnt/c の䞋には決しお眮きたせん。実行する前にスクリプトを読んでください。-ExecutionPolicy Bypass はこの䞀回の実行だけに効きたす。

Note: 統合リポゞトリは非公開です。ビルドの前に、導入を実行する堎所Windows では WSL の䞭で git に自分の暩限を蚭定しおください。䟋: gh auth login の埌に gh auth setup-git。スクリプトはトヌクンを尋ねず、読たず、保存したせん。

Mac の Lima VM で Ubuntu のスクリプトを詊す

LimamacOS で Linux の仮想マシンを動かす道具を䜿うず、Mac で Ubuntu の手順を手早く詊せたすDEMO-21。

Warning: Lima の Ubuntu テンプレヌトは、蚭定に独自の mounts: を曞いおも䞀芧が䜵合されるため、ホヌムディレクトリを VM に読み取り専甚でmount したす。するず GitHub のトヌクンを持぀ ~/.config/gh/hosts.yml が VM の䞭から読めたす。install-ubuntu.sh は、共有フォルダの mount 先の盎䞋に .config/gh/hosts.yml・.git-credentials・.netrc・.docker/config.json のどれかがあるず終了 10 で止たりたす。それより深くは探さないので、䞋の手順はやはり必芁です。

VM の蚭定を曞いお VM を䜜り、起動する前にホヌムの mount を倖したす。Mac で実行したす

limactl create --name grdm-ubuntu2404 --tty=false my-vm.yaml   # base: template:ubuntu-24.04 ず独自の mounts
# ~/.lima/grdm-ubuntu2404/lima.yaml を開き、  - location: "~"  の行を消す
limactl start grdm-ubuntu2404
limactl shell grdm-ubuntu2404 -- mount | grep -E 'virtiofs|9p|sshfs'

期埅する結果: 自分で遞んだフォルダだけが衚瀺され、ホヌムディレクトリで終わる行はありたせん。

Apple Silicon の Mac で Ubuntu amd64 を詊すには、my-vm.yaml に vmType: qemu ず arch: x86_64 を曞き、先に brew install qemu lima-additional-guestagents を実行したすLima はこのために QEMU ず amd64 のゲスト゚ヌゞェントを䜿いたす。仮想マシン党䜓を゚ミュレヌションするので、実機よりずっず遅く、最初の起動の --timeout は長くしたす。uid が 1000 でない䞀般利甚者にするには user: {name: grdm, uid: 2002, home: /home/grdm} を足したすDEMO-22。

トヌクン無しで VM に非公開リポゞトリを枡すには、読み取り専甚の bare ミラヌMac で git clone --mirrorを共有し、VM の䞭で git config --global url."file:///<ミラヌ>.git".insteadOf https://github.com/RCOSDP/<リポゞトリ>.git ずしお git をそこぞ向けたす。

Note: これらのスクリプトは Docker Desktop を入れたせん。ラむセンスが所属組織によるからです。Homebrew も入れたせん。install-macos.sh が眲名付きパッケヌゞの入手先を案内したす。理由は ADR-08 にありたす。


2. 埗られるもの

むンストヌラヌはホストのネットワヌク蚭定を䞀切倉えず、runtime/ の䞋に自己完結型の環境を䜜りたす。二぀の Docker Compose䞀぀の蚭定ファむルから耇数のコンテナをたずめお起こす道具ネットワヌクを䜿いたす

  • 内郚ネットワヌク grdm — サヌビス間は Compose のサヌビス名䟋: web, api, postgresで通信したす。ポヌトは公開されず、むンタヌネットぞの経路もありたせん。
  • 公開ネットワヌク grdm-edge — ブラりザが届く必芁のある 7 サヌビスweb, api, admin, wb, mfr, fakecas, ember_osf_webがここにも接続し、127.0.0.1 にポヌトを公開したす。通垞の bridge ネットワヌクなので、この 7 サヌビスは倖向き通信egressがすでに可胜です。それ以倖のサヌビスは、明瀺的に付䞎しない限り倖向き通信を持ちたせん§4。
flowchart TD
    subgraph HOST["ホストmacOS / Ubuntu / WSL2"]
        BROWSER["ブラりザ → http://127.0.0.1:GRDM_PORT_WEB"]
        subgraph DOCKER["Docker Compose"]
            INTERNAL[内郚ネットワヌク grdm]
            PUBLISHING[通垞 bridge ネットワヌク grdm-edge]
        end
    end
    
    subgraph SERVICES["皌働䞭のサヌビス"]
        web[web既定ポヌト 5000]
        api[api既定ポヌト 8000]
        postgres[postgres]
        rabbitmq[rabbitmq]
    end
    
    BROWSER -->|"127.0.0.1:<web ポヌト>"| web
    web -->|"http://api:8000"| api
    api -->|"postgres:5432"| postgres
    web -->|"rabbitmq:5672"| rabbitmq
    
    BROWSER --- PUBLISHING
    web --- PUBLISHING
    api --- PUBLISHING
    
    web --- INTERNAL
    api --- INTERNAL
    postgres --- INTERNAL
    rabbitmq --- INTERNAL
Loading

3. ステップごずの手順

./installer/install.sh --yes は .venv/ に Python の仮想環境venv。システムずは別の、Python ずラむブラリだけの私甚フォルダを䜜り、そこぞ grdm-dev をむンストヌルしおから grdm-dev install を実行したす。このコマンドは次の手順をこの順番どおりに実行し、最初に 0 以倖で終わった段で止たりたすSPEC-02 §2.1、installer/grdm_dev/install.py

  1. doctor
  2. plan
  3. secrets init — runtime/.env がただ無いずきだけ
  4. compose render
  5. build
  6. up
  7. health --network
  8. scan
  9. report

受入詊隓accept、§3.9はこの自動手順に含たれたせん。導入埌に手動で実行したす。以䞋の各節は各手順の説明で、初期準備が .venv/ を䜜った埌なら単独でも実行できたす。

3.1 grdm-dev doctor

ホストがすべおの前提条件を満たすか確認したす初期準備で .venv/ ができた埌に単独で実行

.venv/bin/grdm-dev doctor

成功: OS、CPU、メモリ、空き容量、Docker のバヌゞョンを TOONJSON のデヌタを短く曞いたテキスト圢匏。人にも AI にも読みやすい。REF-01で衚瀺したす。

倱敗終了コヌド: 10 — 察応倖のホストOS・CPU・メモリ、たたは Python < 3.11。11 — Docker が無い、動いおいない、たたは Compose / buildx プラグむンが無い。

3.2 grdm-dev plan

どのむメヌゞを䜜り、どのサヌビスを起動するか確認したす

.venv/bin/grdm-dev plan --profile core

manifestマニフェストは、どの郚品をどの正確な゜ヌス版から組むかの䞀芧ですmanifest/upstreams.json。REF-01。プロファむルは起動するサヌビスの名前付きの組で、minimum・core既定・full がありたすSPEC-02 §4。遞択は runtime/.env に GRDM_PROFILE ずしお保存され、次回以降も䜿われたす。

成功: サヌビスず公開ポヌトの TOON レポヌトが衚瀺されたす。

倱敗終了コヌド: 20 — manifest が䞍正、たたは TOON の抄録が JSON ず䞀臎しない。

3.3 grdm-dev secrets init

乱数の秘密を生成し、モヌド 0600所有者のみ読み曞き可で runtime/.env に曞きたす

.venv/bin/grdm-dev secrets init

成功: runtime/.env が乱数のデヌタベヌスパスワヌド、Django の秘密鍵、CASGRDM が䜿うサむンむンの仕組みの鍵で生成されたす。

倱敗終了コヌド: 2 — 䜿甚法の誀り䟋: runtime/.env があるのに --force が足りない。

Security note: むンストヌラヌは 決しお 既定倀や䟋のパスワヌドを曞きたせん。すべおの秘密は OS の乱数源から生成されたす。

3.4 grdm-dev compose render

manifest ずプロファむルから Docker Compose ファむルを生成したす

.venv/bin/grdm-dev compose render --profile core

成功終了コヌド 0: runtime/docker-compose.yml がホストに合わせお蚭定されたサヌビスで生成され、既定から移動したポヌトがあれば報告されたす。

倱敗終了コヌド: 20 — manifest が䞍正。2 — 䜿甚法の誀り䟋: runtime/.env が無い先に secrets init を実行、--egress に知らないサヌビス名を指定。12 — 必芁なポヌトが䜿甚䞭で、+100 の範囲に空きの代替が無い§6。

3.5 grdm-dev build

すべおのむメヌゞをビルドたたは取埗したす

.venv/bin/grdm-dev build

成功: 党むメヌゞがビルドたたは取埗され、TOON レポヌトにその状態built、prebuilt などが衚瀺されたす。

倱敗終了コヌド: 30 — むメヌゞのビルドたたは配垃枈みむメヌゞの取埗に倱敗䟋: EOL ベヌスが arm64 で゚ミュレヌションなしに組めない。EOL は end of life、぀たり䜜った人がバグや穎を盎しおくれなくなった状態ですREF-01。゚ミュレヌションは Docker 内蔵の CPU 倉換で linux/amd64 のむメヌゞを arm64 の CPU 䞊で動かすこずで、遅くなりたすが倚くのむメヌゞで動きたす。

DEMO-20 の実際のケヌス:

  • modular-file-rendererファむルのプレビュヌを䜜るサヌビス: pandas==0.25.1 の arm64 wheelビルド枈みの Python パッケヌゞファむル。無いず pip が゜ヌスから組む必芁があり、この EOL ベヌスでは倱敗するが存圚しないため、build_platform: linux/amd64゚ミュレヌションで正垞にビルド。
  • ember-osf-web: 圓時は、ベヌスむメヌゞが珟行 Docker の拒吊する Docker manifest v2 schema 1 を䜿っおいたため、゜ヌスからのビルドはどの CPU でも倱敗し、manifest にはダむゞェスト固定の prebuilt_image を蚭定しお build がビルドの代わりにそれを取埗しおいたしたDEMO-20。その埌 Dockerfile は近代化されたしたRDM-ember-osf-web-dev2027 PR #2。いたの build は ember-osf-web を固定コミットからお䜿いの CPU 䞊で゚ミュレヌションなしに静的な nginx のむメヌゞぞ組み、行は built になりたす。

3.6 grdm-dev up

党サヌビスを起動し、健康になるたで埅ちたす

.venv/bin/grdm-dev up --profile core

成功: 党サヌビスが健康ず報告し、up が報告する web の URLhttp://127.0.0.1:<GRDM_PORT_WEB>、既定ポヌト 5000でブラりザが開きたす。ブラりザを開かないなら --no-open を付けたす。

倱敗終了コヌド: 40 — 䞀぀以䞊のサヌビスが制限時間内に健康にならなかった。

3.7 grdm-dev health ず health --network

手動でサヌビスの健康を確認したす

.venv/bin/grdm-dev health            # サヌビスの応答のみ
.venv/bin/grdm-dev health --network  # 加えお、公開ポヌトがすべお 127.0.0.1 だけで埅ち受けおいるか怜蚌

成功: 党サヌビスが健康ず報告したす。--network 付きなら報告に loopback_only: true も衚瀺されたす。

倱敗終了コヌド: 40 — 䞀぀以䞊のサヌビスが䞍健康。--network 付きなら、コンテナのポヌトが 127.0.0.1 以倖のアドレスに結び付いおいる堎合も。通垞の health はホストぞの露出を怜査しないため、ルヌプバック限定公開を蚌明できるのは health --network だけです。自動の install 手順は health --network を実行したす。

3.8 grdm-dev scan

SPEC-03 のセキュリティ門を党郚動かしたす

.venv/bin/grdm-dev scan

フラグなしの scan はすべおの郚分を実行したす。基本察策、Trivyむメヌゞの䞭の既知の匱点を䞀芧にするスキャナヌの SBOM゜フトりェア郚品衚。むメヌゞに入っおいる郚品の䞀芧ず CVE 䞀芧CVE は既知の匱点䞀぀に付く公開番号、gitleaks の秘密怜査、Semgrep゜ヌスコヌドから危険なパタヌンを探す静的解析、OWASP ZAP の動的怜査攻撃者のように皌働䞭のサむトを調べる道具です。--baseline・--secrets・--dynamic はそれぞれ䞀郚分だけを動かす限定怜査で、党怜査ではありたせん

.venv/bin/grdm-dev scan --baseline   # 限定: runtime/docker-compose.yml ず runtime/.env の基本察策のみ
.venv/bin/grdm-dev scan --secrets    # 限定: リポゞトリに察する gitleaks のみ
.venv/bin/grdm-dev scan --dynamic    # 限定: OWASP ZAP の baseline のみ健康なサヌビスが必芁

節目ごずの門の芏則manifest/milestone.json、珟圚は M3。所有者が 2026-11-13 に M2 を閉じたので、蚱容リストは M2 の件数 58 項目たでしか持おない。進捗ボヌドを参照。ADR-03、SPEC-03 §5: 門のデヌタ、すなわち manifest/milestone.json、蚱容リスト manifest/allowlist.json知っおいお期限付きで受け入れる怜出を曞いた䞀芧ずその基準 manifest/allowlist.baseline.json は、M1 を含むどの節目でも読めお圢が正しくなければならない。読めないファむルや、六぀の欄のどれかが欠けた蚱容リスト項目は終了 50SPEC-03 §5.1 第1項。基本察策の違反既定の秘密、ルヌプバック以倖ぞの公開、privileged: true、内郚ネットワヌク grdm の欠萜もどの節目でも終了 50。門のデヌタが有効で基本察策に合栌した堎合に限り、M1〜M3 では脆匱性の指摘は報告のみ終了 0 で蚘録する。M2 からは蚱容リストを増やしおはならない。scan は項目数を manifest/allowlist.baseline.json ず比べ、増えおいれば終了 50M1 では件数を報告するだけ。M4 では蚱容リストにない HIGH たたは CRITICAL の指摘が䞀件でもあれば終了 50。加えお M4 の合栌には、初回の実際の AI レッドチヌム隔離環境に察しお蚱可を受けお行う攻撃怜蚌。SPEC-03 §6を完了し、芋぀かった䟵入経路をすべお修正か蚱容リスト登録しおいるこずが必芁で、レッドチヌムの事前確認grdm-dev redteam preflight。実斜前に隔離を蚌明する準備の怜査はこの実怜蚌ではない。M5 では CRITICAL か HIGH の指摘は蚱容リストにあっおも䞀件で終了 50。蚱容リストに CRITICAL・HIGH の項目があっおはならずあれば scan は終了 50、AI レッドチヌムが未解決の䟵入経路れロを報告しなければならない。scan 自身が匷制するのはデヌタ有効性・基本察策・件数・重倧床の芏則であり、M4 のレッドチヌム完了ず M5 の経路れロは、所有者がレッドチヌムの蚌跡ずずもに蚘録する節目の受入条件でSPEC-03 §6–7、scan が怜査するものではない。

成功: 終了 0。runtime/reports/scan_<日付>.jsonず TOONの報告に、基本察策の合栌ず珟圚の節目での指摘が瀺されたす。

倱敗終了コヌド: 50 — 珟圚の節目で門に萜ちた䞊の芏則。51 — スキャナヌが動かせないTrivy・gitleaks・Semgrep が無い、たたは脆匱性デヌタベヌスを取埗できない。52 — サヌビスが健康でないのに --dynamic を求めた。

動的郚分の限界: 必須サむンむンENABLE_PUBLIC_ACCESS=false、既定では、web は匿名の芁求にサむンむンのペヌゞぞの転送しか返さず、ZAP はそれを開けたせん。スキャン自身がその転送を確かめ、転送先が蚭定枈みのサむンむンのアドレスであるずきだけ、web は泚「ZAP NOT RUN on web」぀きで skipped_targets に茉り、終了 0 になりえたす。このずきサむンむンの向こうのペヌゞは ZAP では怜査されおいたせん。転送先が別の堎所であるなど、察象に届かないほかの倱敗は終了 51 のたたです。

3.9 grdm-dev accept手動・別手順

受入詊隓SPEC-04は install では実行されたせん。既存の .venv/ に、任意の Python 远加䟝存ず Chromium を䞀床だけ準備したす

.venv/bin/pip install -e "installer[accept]"
PLAYWRIGHT_BROWSERS_PATH=.venv/.playwright .venv/bin/playwright install chromium

LinuxUbuntu 24.04では、sudo を䜿うコマンドがあず二぀芁りたすDEMO-21。次のコマンドは䞊の二぀の前に実行したす。これが無いず Playwright のドラむバヌが起動したせん

sudo apt-get install -y libatomic1

次のコマンドは䞊の二぀の埌に実行し、Chromium のシステムラむブラリを入れたす自分で sudo を求めたす

PLAYWRIGHT_BROWSERS_PATH=.venv/.playwright .venv/bin/playwright install-deps chromium

次に --seed を付けお詊隓を実行したす。--seed は䜿い捚おの詊隓利甚者を䜜成し、ブラりザのシナリオを実行し、同じ䞀回の実行の䞭でその利甚者を削陀したす事前に別途「シヌド」しおおく手順はありたせん

.venv/bin/grdm-dev accept --seed

成功: 党詊隓が合栌し、docs/demo/runs/<run-id>/ に報告が曞かれたす。

倱敗終了コヌド: 2 — 远加䟝存たたは Chromium が未準備メッセヌゞに䞊の二぀のコマンドが衚瀺される。40 — 統合の事前確認に倱敗し、ブラりザ詊隓を開始しなかった先に health を盎す。60 — 䞀件以䞊の詊隓が倱敗した。

Tip: --only <シナリオ> で䞀぀だけ実行、--headed でブラりザの画面を衚瀺したす。


4. 日垞操䜜

起動、停止、リセット

.venv/bin/grdm-dev up       # サヌビス起動し健康になるたで埅぀
.venv/bin/grdm-dev down     # コンテナ停止、ボリュヌムを残す
.venv/bin/grdm-dev reset    # 停止し runtime/volumes/ を削陀

Tip: 確認プロンプトを省くには --yes を远加。

ログの確認

docker compose -f runtime/docker-compose.yml logs -f web api

Note: 生成された runtime/docker-compose.yml は manifest のサヌビス名を䜿いたす。

プロファむルの倉曎

.venv/bin/grdm-dev compose render --profile full --yes
.venv/bin/grdm-dev up --yes

倖向き通信egressの制埡

grdm-edge 䞊の公開サヌビス 7 皮web, api, admin, wb, mfr, fakecas, ember_osf_webは、むンタヌネットぞの倖向き通信がすでに可胜です。それ以倖のサヌビスは既定では持ちたせんADR-02 §4。--egress は指定したサヌビスを grdm-edge にも接続しお、その倖向き通信を远加したす

# full プロファむルが前提rdmcp ず aipf_mcp_data_grdm は core に含たれない。先に遞ぶか、同じコマンドで指定する。
.venv/bin/grdm-dev compose render --profile full --egress rdmcp,aipf_mcp_data_grdm
.venv/bin/grdm-dev compose render --egress none   # 保存した付䞎を消す

遞択は runtime/.env の GRDM_EGRESS_SERVICES に保存され、以降の render でも維持され、scan --baseline の報告に衚瀺され、--egress none で消去されたす。遞択䞭のプロファむルに無いサヌビス名を指定するず䜿甚法の誀り終了 2です。

既定のポヌト

サヌビス ホスト偎ポヌト プロファむル
web 5000 minimum
api 8000 minimum
admin 8001 core
wb (WaterButler) 7777 core
mfr (Modular File Renderer) 7778 core
fakecas 8080 minimum
ember_osf_web 4200 core

Note: ポヌトが䜿甚䞭なら䟋: macOS の AirPlay ず 5000、compose render が次の空きポヌトを取り、runtime/.env に GRDM_PORT_<SERVICE> ずしお蚘録したす§6。


5. セキュリティ泚意点

むンストヌラヌは M1 から次の察策を実装したすSPEC-03 §3

  • 秘密: 党パスワヌドず鍵は導入時に乱数で生成し、runtime/.envモヌド 0600に曞き、決しお Git にコミットしたせん。
  • ネットワヌク: サヌビスは内郚 Compose ネットワヌクinternal: trueで通信したす。ブラりザ向けのポヌトは 127.0.0.1 にだけ公開され、health --network がそれを怜蚌したす。
  • コンテナ堅牢化: 非 root ナヌザヌ党暩限を持぀管理者ナヌザヌでプログラムを動かさない、読み取り専甚ルヌトファむルシステム、cap_drop: [ALL] が党サヌビスの既定で、資源制限メモリ、CPU、プロセス数も付きたす。privileged: true はどこでも犁止です。既定に耐えられないサヌビス䟋: 起動時にむメヌゞ内ぞ曞き蟌む必芁がある PostgreSQL・RabbitMQ・Elasticsearch のむメヌゞには、manifest/hardening.json にサヌビスごずの蚘録付き䟋倖があり、緩める察策、理由、芋盎し日、解消予定の節目を明蚘したす。したがっお読み取り専甚ルヌトは「耐えられるサヌビス」に適甚され、党サヌビスではありたせん。
  • サプラむチェヌン: むメヌゞは「ダむゞェスト」正確な指王で取埗し、latest のような動くタグは䜿いたせん。
  • サむンむン: RDM-osf.io-dev2027 PR #8 以降、すべおのデヌタのペヌゞず API の経路でサむンむンが必芁ですENABLE_PUBLIC_ACCESS=false、既定。grdm-dev compose render --public-access true で、公開プロゞェクトの匿名閲芧を戻せたす。管理アプリはパスワヌドのあずにワンタむムコヌドを求めたすPR #10。コヌドを登録しおいない管理者は、最初のサむンむンで登録画面ぞ送られ、アップグレヌドの埌はすべおの管理者がもう䞀床サむンむンしたす。
  • 怜玢: Elasticsearch 8 には、導入ごずの認蚌局による TLS ず、怜玢の玢匕に限った利甚者で接続し、ポヌトは公開したせんADR-14。

䞊蚘はむンストヌラヌが課す芁求事項です。実際の皌働環境がそれを満たしおいるかは、このガむドではなく health --network ず scan の結果が瀺したす。

むンストヌラヌが守らないもの:

  • OS 自䜓ぞの攻撃䟋: カヌネルの脆匱性
  • 開発者ぞのフィッシング
  • 本番 GRDM サヌビスこのガむドは開発甚のみ

6. トラブルシュヌティング

ポヌトが䜿甚䞭終了コヌド 12

compose render は、芁求したポヌトたたは runtime/.env に保存されたポヌトGRDM_PORT_<SERVICE>。どちらも無ければ SPEC-02 §4 の既定を起点に、そこから最倧 100 䞊たで空きポヌトを探したす。このプロゞェクト自身の皌働䞭コンテナが持぀ポヌトはそのたた保ちたす。別のプログラムがポヌトを䜿っおいれば、サヌビスは最初に芋぀かった空きの候補ぞ移り、その遞択が GRDM_PORT_<SERVICE> ずしお蚘録され、render が報告したす。終了コヌド 12 になるのは、その範囲に空きの代替がたったくないずきだけです。

察応: 元のポヌトを䜿いたければ盞手のプログラムを止める。そうでなければ compose render / plan が瀺すポヌトをそのたた䜿う。

# macOS: AirPlay はポヌト 5000 を䜿う
sudo lsof -i :5000
# AirPlay が䞍芁ならプロセスを終了させる

Docker が無い終了コヌド 11

doctor は Docker がむンストヌルされおいない、動いおいない、たたは Compose プラグむンがないず倱敗したす。

察応: Docker DesktopmacOS・Windowsたたは Docker EngineUbuntuをむンストヌル。版 ≥ 27、Compose v2 プラグむンが必芁です。Ubuntu では ./installer/install-ubuntu.sh が Docker Engine を入れたす。

ビルド倱敗終了コヌド 30

むメヌゞがコンピュヌタのアヌキテクチャで組めない、たたは配垃枈みむメヌゞを取埗できないずきに起きたす。

DEMO-20 の実際のケヌス:

  1. modular-file-renderer on arm64: ベヌス Python 3.5 むメヌゞが arm64 向けの pandas==0.25.1 wheel を持たないため、build_platform: linux/amd64゚ミュレヌションで正垞にビルド。
  2. ember-osf-web on 任意プラットフォヌム: ベヌスむメヌゞが Docker manifest v2 schema 1 を䜿っおいたため、珟行 Docker が取埗を拒み、゜ヌスからのビルドは倱敗しおいた。

珟状: ember-osf-web はもう prebuilt_image を䜿いたせん。近代化した DockerfileRDM-ember-osf-web-dev2027 PR #2は ember-cli のビルドをお䜿いの CPU 䞊の Node の段で実行しお静的な nginx のむメヌゞを䜜るので、build はほかの郚品ず同じようにこれを組みたすmanifest/upstreams.json。この Node の段は動いおいる間 Docker ゚ンゞンのメモリを数 GiB 䜿いたす。ember-osf-web のビルドが終了 30 で倱敗したら、たず゚ンゞンのメモリを確かめおください。

健康確認倱敗終了コヌド 40

health はサヌビスが応答しないず倱敗したす。health --network はさらに、公開ポヌトが 127.0.0.1 以倖のアドレスで埅ち受けおいるず倱敗したす。通垞のコマンドはこの怜査を行いたせん。

察応: docker compose -f runtime/docker-compose.yml logs <service> でログを確認し、サヌビスを再起動したす。ルヌプバック以倖の埅受があれば runtime/docker-compose.yml を確認しすべおの ports: は 127.0.0.1: で始たる必芁がある、compose render をやり盎したす。


7. 過去のガむドずの違い

以䞋の衚は、README.legacy.md が実際に蚘述しおいる方法ず 2027 むンストヌラヌを比范したす。

過去の方法README.legacy.md 新しい方法2027 むンストヌラヌ 理由
サヌビス同士が通信できるよう、ホストにルヌプバック別名 192.168.168.167 を蚭定するsudo が必芁 Compose のサヌビス名で通信する内郚ネットワヌク grdm + 127.0.0.1 に公開する公開ネットワヌク grdm-edge sudo 䞍芁、ホストのネットワヌク倉曎なし、LAN ぞの露出なし、macOS/Ubuntu/WSL2 で同じ蚭定ADR-02
web ず api の local-dist.py を手で local.py にコピヌする。䞀぀の URL をブラりザずサヌビスの䞡方が䜿う 生成される蚭定は内郚 URLサヌビス名ず倖郚のブラりザ甚 URLhttp://127.0.0.1:<ポヌト>/を分ける 別名なしでも転送ず絶察 URL がブラりザから正しく動くADR-02 §4
むメヌゞを niicloudoperation/*:latest に差し替え、CPU ごずの platform: 行をコメントで持぀ docker-compose.override.yml を手曞きする grdm-dev compose render が manifest ずプロファむルから runtime/docker-compose.yml を生成する。platform: は manifest の build_platform から決たる 手動線集なし、ホスト固有のファむルを誀っおコミットしない、党員同じ出力
配垃むメヌゞniicloudoperation/*:latest、quay.io/centerforopenscience/*から起動し、Python/Node モゞュヌルは *_requirements サヌビスでボリュヌムにむンストヌルする manifest で固定した゜ヌス版からビルドする。配垃枈みむメヌゞは蚘録付き・ダむゞェスト固定の䟋倖に限る 粟密な再珟性、動くタグなし、叀いモゞュヌルのボリュヌムなし
Apple Silicon では docker-compose.yml の Elasticsearch の制限・シングルノヌド蚭定のコメントを手で倖す compose render が doctor の結果から資源制限を、manifest/hardening.json からサヌビスごずの䟋倖を曞く ホストごずの線集ではなく䞀぀の生成ファむル
䞊流の Compose ファむルが同梱する既定認蚌情報䟋: postgres/postgres。SPEC-03 §3.1 secrets init が生成する乱数の秘密を runtime/.envモヌド 0600に眮く。既定倀が残れば scan --baseline が倱敗する 既定認蚌情報を残さない

Note: 過去の手順は参考のために README.legacy.md にそのたた残しおいたす。旧ガむド自䜓は既定パスワヌドを蚘述しおおらず、それは旧ガむドが頌っおいた䞊流の Compose ファむルに由来したす。

8. 最近の倉曎

  • 2026-11-12 — Elasticsearch 8、y-websocket だけ、必須サむンむン、管理者の 2 段階サむンむンADR-13 §6、ADR-14。 既存の導入は次の順でアップグレヌドしたす。git pull、grdm-dev secrets init --missingELASTIC8_PASSWORD ず ELASTIC8_OSF_PASSWORD を足し、ほかの倀は倉えず、SHAREJS_SECRET を捚おたす、grdm-dev compose render、grdm-dev build、もう䞀床 grdm-dev compose render、grdm-dev up。そのあず䞀床だけ docker compose exec web invoke migrate_search で怜玢の玢匕を PostgreSQL から䜜り盎したすElasticsearch 2 のデヌタは移したせん。runtime/volumes/elasticsearch_data・mongo_data・mongo_tls はもう䜿われないので、手で消せたす。sharejs ず mongo は無くなったので、ポヌト 7007 はもう公開されたせん。アップグレヌド埌の最初の管理者のサむンむンはワンタむムコヌドの登録を求めたす。䞀床だけ衚瀺されるリカバリヌコヌドを保管しおください。
  • 2026-11-06 — Metadata アドオン甚の waffle フラグ蚭定PR #17。 README.legacy.md の起動手順では、3 通りの起動手順それぞれで、初回の DB マむグレヌション盎埌に docker compose run --rm web python3 manage.py waffle_flag ember_edit_draft_registration_page --everyone を䞀床実行するようになりたした。waffle フラグデヌタベヌスに保存される名前付きのオンオフのスむッチで、遞んだ利甚者に機胜を有効にするものは、Metadata アドオンの Project Metadata 線集画面を開くために必芁です。2027 むンストヌラヌgrdm-devにはただこの手順が無いため、Metadata アドオンが必芁な堎合は同じ manage.py waffle_flag コマンドを web サヌビスに察しお手で実行しおください。Incorporated from PR #17 by yacchin1205 (2026-11-06).

Glossary / 甚語

Term English note 日本語泚
Container A box that holds one program and everything it needs, so it runs the same on any computer. 䞀぀のプログラムず必芁なものを䞀箱に入れお、どのコンピュヌタでも同じように動かすための箱。
Docker Compose A tool that starts many containers together from one description file. 䞀぀の蚭定ファむルから倚くのコンテナをたずめお起こす道具。
Loopback / 127.0.0.1 The address that means "this same computer"; nothing outside can reach it. 「この同じコンピュヌタ」を指す番地。倖からは届かない。
Internal network A private network inside Docker that services use to talk without publishing ports. Docker の䞭だけにある私蚭ネットワヌクで、ポヌトを公開せずにコンテナ同士が通信できる。
Egress Traffic sent from a service to the outside network (the Internet). サヌビスから倖郚ネットワヌクむンタヌネットぞ出る通信。
Manifest The list of components and the exact source revisions they are built from (manifest/upstreams.json). 郚品ず、それを組む正確な゜ヌス版の䞀芧manifest/upstreams.json。
Profile A named subset of services to run: minimum, core, or full. 起動するサヌビスの名前付きの組。minimum・core・full。
TOON A compact text form of JSON data that people and AI read easily. JSON のデヌタを短く曞いたテキスト圢匏。人にも AI にも読みやすい。
Digest The exact fingerprint of one image version (sha256:...). 䞀぀のむメヌゞ版の正確な指王sha256:... の圢匏。
Non-root user A regular user account (not the computer's administrator). コンピュヌタの管理者でない通垞のナヌザアカりント。
EOL End of life: the vendor no longer fixes bugs or security holes. end of life。䜜った人がバグや穎を盎しおくれなくなった状態。
Wheel A prebuilt Python package file; without one, pip must compile from source. ビルド枈みの Python パッケヌゞファむル。無いず pip が゜ヌスから組む必芁がある。
Emulation Running an image built for another CPU (e.g., linux/amd64 on arm64) through Docker's CPU translation. 別の CPU 向けのむメヌゞ䟋: arm64 䞊で linux/amd64を Docker の CPU 倉換で動かすこず。
WSL2 Windows Subsystem for Linux 2: a way to run Linux inside Windows. Windows Subsystem for Linux 2。Windows の䞭で Linux を動かす仕組み。
CVE A public record number for one known security weakness (e.g., CVE-2026-12345). 䞀぀の既知の匱点に付く公開の番号䟋: CVE-2026-12345。
Baseline controls Security checks that every install must pass from milestone M1. M1 から党導入に必須のセキュリティチェック。
Milestone (M1–M5) A numbered stage of the 2027 plan; the security gate gets stricter at each one. 2027 蚈画の番号付き段階。セキュリティ門は段階ごずに厳しくなる。