Document Docker prerequisites

README.md

@@ -40,7 +40,13 @@ Node.js 24 with npm workspaces; React, TypeScript, and Vite; NestJS; Prisma with
 
 The first runnable path is a fully local demo. After the dependencies and the PostgreSQL Docker image are downloaded, it needs no external account, cloud credential, or third-party service: no AWS, Cognito, S3, SES, SNS, API key, or `.env` file. (Cloning, `npm ci`, and the first image pull need network access.)
 
-Prerequisites: Node.js 24, and Docker with Compose v2 running.
+Prerequisites: Node.js 24 with npm, plus an operating-system-level Docker
+installation that provides Docker Engine, the `docker` CLI, and Docker Compose
+v2. Docker is not installed by `npm ci`. Before continuing, `docker --version`,
+`docker compose version`, and `docker info` must all succeed. If Docker is not
+installed or one of these checks fails, follow
+[`doc/GETTING_STARTED.md`](doc/GETTING_STARTED.md#2-clone-and-prerequisites)
+before running the demo.
 
 ```bash
 git clone https://github.com/id774/spa-development-reference.git

doc/DEVELOPMENT.md

@@ -6,7 +6,22 @@ The development workflow reference: how to run the application locally and how t
 
 - **Node.js 24** and npm (the root `package.json` requires `node >=24`; `.nvmrc` selects 24).
 - **A PostgreSQL-compatible database** for the backend and for the backend tests. For the local demo, `compose.yaml` provides PostgreSQL 17 (`npm run demo`; Docker with Compose is required for that path). For development and tests, any PostgreSQL you can reach works; Docker is not otherwise required.
-- **For the local demo**: nothing beyond Node.js 24 and Docker. `npm run demo` (orchestrated by `scripts/demo.mjs`) checks the prerequisites and the ports `127.0.0.1:5173`, `3000`, and `55432`, starts PostgreSQL and waits until it is healthy, applies the migrations, runs the backend (`APP_MODE=local`) and the frontend, waits until both answer, and then prints the ready message. `npm run demo:setup` prepares only the database and migrations, `npm run demo:backend` runs only the backend, `npm run demo:down` stops PostgreSQL (data kept), `npm run demo:reset` removes the demo data, and `npm run demo:deliveries` prints the recorded emails and events. The data layout, pass criteria, and first-run troubleshooting are in [`GETTING_STARTED.md`](GETTING_STARTED.md), section 4.
+- **For the local demo**: Node.js 24 and an OS-level Docker installation
+  providing Docker Engine, the `docker` CLI, and Docker Compose v2. Docker is
+  not installed by `npm ci`; the same user that runs the demo must be able to
+  run `docker --version`, `docker compose version`, and `docker info`
+  successfully. Installation and first-time verification are documented in
+  [`GETTING_STARTED.md`](GETTING_STARTED.md#21-verify-docker-before-installing-repository-dependencies).
+  `npm run demo` (orchestrated by `scripts/demo.mjs`) re-checks the prerequisites
+  and the ports `127.0.0.1:5173`, `3000`, and `55432`, starts PostgreSQL and
+  waits until it is healthy, applies the migrations, runs the backend
+  (`APP_MODE=local`) and the frontend, waits until both answer, and then prints
+  the ready message. `npm run demo:setup` prepares only the database and
+  migrations, `npm run demo:backend` runs only the backend,
+  `npm run demo:down` stops PostgreSQL (data kept), `npm run demo:reset`
+  removes the demo data, and `npm run demo:deliveries` prints the recorded
+  emails and events. The data layout, pass criteria, and first-run
+  troubleshooting are in [`GETTING_STARTED.md`](GETTING_STARTED.md), section 4.
 - **For a sign-in against real AWS services**: a Cognito user pool, plus AWS access (S3, SES, SNS) when you exercise attachments or notifications. The automated tests need none of these; they use test doubles and a local PostgreSQL.
 
 ## 2. Install

doc/GETTING_STARTED.md

@@ -33,9 +33,43 @@ cd spa-development-reference
 | Git | Cloning. |
 | Node.js 24 and npm | Every milestone. `.nvmrc` selects 24. |
 | A PostgreSQL-compatible database | The automated tests in Milestone 2 (`npm test`) and the migration check. (Milestone 1 provides its own through Docker.) |
-| Docker with Compose | Milestone 1 (local PostgreSQL). Optional for Milestone 2: a disposable PostgreSQL and the image builds. |
+| Docker Engine, the `docker` CLI, and Docker Compose v2 | Milestone 1 (local PostgreSQL). Optional for Milestone 2: a disposable PostgreSQL and the image builds. This is an OS-level prerequisite; `npm ci` does not install it. |
 | An AWS account, with Cognito, Aurora, S3, SES, SNS, and ECS/Fargate through the CDK stack | Milestone 3 only. |
 
+### 2.1 Verify Docker before installing repository dependencies
+
+Docker is external software, not an npm dependency. The npm package named
+`docker` is unrelated to Docker Engine and does not satisfy this prerequisite.
+
+Install Docker for your platform from the official Docker documentation:
+
+- Docker Engine: <https://docs.docker.com/engine/install/>
+- Docker Compose: <https://docs.docker.com/compose/install/>
+
+Docker Desktop includes Docker Engine, the Docker CLI, and Docker Compose.
+On Linux, Docker Engine plus the Docker Compose plugin is sufficient.
+
+Before continuing, all three commands below must succeed for the same user that
+will run `npm run demo`:
+
+```sh
+docker --version
+docker compose version
+docker info
+```
+
+Interpret a failure as follows:
+
+- `docker: command not found` means the Docker CLI is not installed or is not on
+  `PATH`;
+- failure of `docker compose version` means Docker Compose v2 is not available;
+- failure of `docker info` means the Docker daemon is not running or the current
+  user cannot access it.
+
+Fix the Docker installation or access problem before running `npm run demo`.
+Do not try to satisfy this prerequisite by installing an npm package named
+`docker`.
+
 ## 3. Install
 
 From the repository root:
@@ -46,7 +80,14 @@ npm ci
 
 Expected: the command exits with code 0 and the workspace dependencies are installed.
 
-This is the only install step before the local demo; continue with `npm run demo` (section 4.1). It generates the Prisma client itself, so you do not need to run `npm run prisma:generate` first. Run `npm run prisma:generate` directly when you need the Prisma client in `backend/src/generated/` outside the demo, for example when working on the backend on its own or during repository validation.
+This is the only **repository dependency installation** step before the local
+demo. It does not install Node.js or Docker; those external prerequisites must
+already satisfy section 2. Continue with `npm run demo` (section 4.1).
+
+The demo generates the Prisma client itself, so you do not need to run
+`npm run prisma:generate` first. Run `npm run prisma:generate` directly when you
+need the Prisma client in `backend/src/generated/` outside the demo, for example
+when working on the backend on its own or during repository validation.
 
 ## 4. Milestone 1: Local demo
 
@@ -56,7 +97,9 @@ The first runnable path is fully local. After the dependencies and the PostgreSQ
 
 ### 4.1 Run it
 
-Before you start: Node.js 24 (`nvm use` reads `.nvmrc`), and Docker with Compose v2 running. Then, from the repository root:
+Before you start, complete the prerequisite checks in section 2: Node.js 24 must
+be active, and `docker --version`, `docker compose version`, and `docker info`
+must all succeed. Then, from the repository root:
 
 ```sh
 npm ci
@@ -65,7 +108,10 @@ npm run demo
 
 That is all: no second terminal and no configuration. `npm run demo`:
 
-1. checks the prerequisites (Node.js 24, Docker, Docker Compose v2, a running Docker daemon, and free ports `127.0.0.1:5173`, `127.0.0.1:3000`, and `127.0.0.1:55432`) and stops with an explanation if one is missing;
+1. re-checks the prerequisites (Node.js 24, the Docker CLI, Docker Compose v2,
+   access to a running Docker daemon, and free ports `127.0.0.1:5173`,
+   `127.0.0.1:3000`, and `127.0.0.1:55432`) and stops with an explanation if one
+   is missing;
 2. starts the local PostgreSQL 17 through `compose.yaml` and waits until it is healthy;
 3. generates the Prisma client and applies the migrations;
 4. starts the backend (`APP_MODE=local`) and the frontend;