Documenting the Stack

Documenting the Stack for the Next Developer

The Compose 514 file says how the stack runs; the README says how to use it. BookNest's README still started PostgreSQL 1,289 alone from the retired docker-compose.yml. Its new first section leads with the commands:

README.md: the part a new developer reads firstShell

    docker compose up -d --build --wait    # web, api and db; returns when all are healthy
    open http://localhost:8080/            # the catalog, served by Nginx
    docker compose run --rm test           # the 9 tests against the real database
    docker compose down                    # stop; add -v to delete the database volume
| Service | Image | Port (default) | Purpose |
|---------|-------|----------------|---------|
| `web`  | `web/Dockerfile` (nginx:1.30-alpine) | 8080 | Front end, proxies `/api/` |
| `api`  | `Dockerfile` (node:24-slim) | 3000 | REST API |
| `db`   | `postgres:18` | 5432 (127.0.0.1) | Data, volume `pgdata` |

Below it come the .env variables, the development and production file pairs, and PGPASSWORD_FILE. Commit the front end, the Compose file and the documentation together, so every commit runs as documented:

Committing the complete stackShell

git add web compose.yaml README.md
git commit -q -m "Add the Nginx front end and document the Compose stack"
git log --oneline -1

Output

21b203c Add the Nginx front end and document the Compose stack

Test such documentation by following it on a clean clone.

MENU