From ad1b8273c0ff8779ec0f4beef37d3a6eba8b79b1 Mon Sep 17 00:00:00 2001 From: Matt Mabrey Date: Fri, 16 Oct 2026 15:08:01 -0700 Subject: [PATCH] T13.8: run the stack in Docker on a PC, local compose override and steps (D22); log BL-070 --- .env.local.example | 10 ++++++++++ DEPLOYMENT.md | 29 +++++++++++++++++++++++++++++ docker-compose.local.yml | 38 ++++++++++++++++++++++++++++++++++++++ docs/waves/backlog.md | 13 +++++++++++++ docs/waves/wave-13.md | 21 +++++++++++++++++++++ 5 files changed, 111 insertions(+) create mode 100644 .env.local.example create mode 100644 docker-compose.local.yml diff --git a/.env.local.example b/.env.local.example new file mode 100644 index 0000000..334d432 --- /dev/null +++ b/.env.local.example @@ -0,0 +1,10 @@ +# Copy to .env in the repository root for a local Docker run (T13.8). +# .env is ignored by git. Use values that are not used anywhere else. +POSTGRES_USER=wpsuite +POSTGRES_PASSWORD=local-only-change-me +POSTGRES_DB=wpsuite +# Generate: python -c "import secrets; print(secrets.token_urlsafe(48))" +AUTH_SECRET_KEY=local-only-change-me-to-a-long-random-string +# Rehearse the Okta sync first. Add OKTA_API_TOKEN and OKTA_ORG_URL only when you +# want the local stack to call the real Okta, and keep this on until you read the log. +OKTA_SYNC_DRY_RUN=true diff --git a/DEPLOYMENT.md b/DEPLOYMENT.md index eb76a25..367fc63 100644 --- a/DEPLOYMENT.md +++ b/DEPLOYMENT.md @@ -485,6 +485,35 @@ If the sync cannot reach Okta, or Okta gives an answer the sync cannot trust, th sync changes **no** account in that cycle and writes a line to the api log: `docker compose logs api | grep "Okta sync"`. +## Run the stack on your own PC (T13.8) + +Use this to check a build in Docker before you deploy it. It needs Docker Desktop. +Do not use it on the host. + +1. Copy `.env.local.example` to `.env` in the repository root. Change the two + `CHANGE` values: the database password and `AUTH_SECRET_KEY`. +2. Run these commands in the repository root: + + docker compose -f docker-compose.yml -f docker-compose.local.yml up -d --build + +3. Open `http://localhost:8080/api/health`. The answer is `{"ok":true}`. +4. Read the api log: `docker compose logs api`. The log shows each database + migration, then one `Okta sync` line. With no `OKTA_API_TOKEN`, the line says + `DISABLED`. That is correct. +5. To stop it and keep the data, run + `docker compose -f docker-compose.yml -f docker-compose.local.yml stop`. + To stop it and delete the data, replace `stop` with `down -v`. + +What this proves: the images build, all migrations run on Postgres, and the app +starts. What it does not prove: sign-in. Okta sends the browser back to the +redirect URI that is set for the Okta app, and that is the production host name. +To rehearse the Okta sync against your real Okta, add `OKTA_API_TOKEN` and +`OKTA_ORG_URL` to `.env` and keep `OKTA_SYNC_DRY_RUN=true`. The local database has +no real users, so every real Okta user shows as a non-match. Use it only to check +that the token works and that the log lines appear. + +The override file `docker-compose.local.yml` explains each change that it makes. + ## Permissions roles `User.role` is the **permissions** role; `User.project_role` is the person's **job diff --git a/docker-compose.local.yml b/docker-compose.local.yml new file mode 100644 index 0000000..c1b3d14 --- /dev/null +++ b/docker-compose.local.yml @@ -0,0 +1,38 @@ +# Local override (T13.8). Use it only on your own PC, never on the host. +# +# docker compose -f docker-compose.yml -f docker-compose.local.yml up -d --build +# +# What it changes, and why: +# 1. It publishes the web server on http://localhost:8080 (loopback only). On the +# host a reverse proxy reaches the web server over the `proxy` network and no +# port is published. +# 2. It replaces the external `proxy` network with an ordinary bridge that this +# stack owns. A `proxy` network that already exists on a PC may have no gateway +# (internal), and Docker does not publish ports through such a network. +# 3. It makes the web server answer for any host name, so http://localhost:8080 +# works. The shipped nginx config answers only for wp.controls.dev, and +# without this every /api request from localhost gets a 404. The change is +# made when the container starts: it removes the stock default.conf, which +# answers to "localhost" first, and marks the app server as the default. The +# shipped config file is not edited. +# 4. It turns the backup service off. Its scripts are checked out with CRLF line +# endings on Windows and cannot start (BL-070). To start it anyway, add +# --profile backup. +# +# Sign-in needs a real Okta redirect URI, so this stack proves the build, the +# database migrations on Postgres, and the Okta sync. It does not prove sign-in. +services: + webserver: + ports: + - "127.0.0.1:8080:80" + command: + - sh + - -c + - rm -f /etc/nginx/conf.d/default.conf && sed -i 's/listen 80;/listen 80 default_server;/' /etc/nginx/conf.d/wp-suite.conf && exec nginx -g 'daemon off;' + backup: + profiles: ["backup"] + +networks: + proxy: !override + name: wp_local_proxy + driver: bridge diff --git a/docs/waves/backlog.md b/docs/waves/backlog.md index f3f0390..5f09a27 100644 --- a/docs/waves/backlog.md +++ b/docs/waves/backlog.md @@ -817,3 +817,16 @@ boundary"). Do not use `localStorage` as the store of record. as an option. Keep that behavior when the list changes. - **Suggested wave or follow-up:** future wave, after the codes arrive. >>>>>>> theirs + +### BL-070 - Shell scripts get CRLF line endings on Windows, and the backup container cannot start + +- **Found during:** T13.8 (local Docker run) +- **Where:** `scripts/*.sh`, no `.gitattributes` in the repository +- **What:** Git for Windows checks out `scripts/entrypoint.sh` with CRLF line endings. + The container then fails with `exec /app/entrypoint.sh: no such file or directory` + and restarts in a loop. The files are stored with LF in Git, so the host (Linux) is + not affected. Any PC build is. +- **Why not now:** T13.8 only makes the local run work. The override turns the backup + service off. A `.gitattributes` rule (`*.sh text eol=lf`) is a repository-wide change. +- **Suggested wave or follow-up:** next housekeeping pass. Add `*.sh text eol=lf` and + renormalize. diff --git a/docs/waves/wave-13.md b/docs/waves/wave-13.md index 7508d16..3cf561a 100644 --- a/docs/waves/wave-13.md +++ b/docs/waves/wave-13.md @@ -349,3 +349,24 @@ Alembic upgrade, downgrade, upgrade passed. Import check passed. Result 2026-10-16: all Okta sync tests and `security_check.py` pass in the sandbox. This task changes no frontend file. + +## T13.8: run the stack in Docker on a PC + +**Item:** D22 (`docs/waves/decisions-2026-10-16.md`), as a way to check T13.7 and later builds before a deploy. + +**Done when:** + +- [x] one command starts the api, the database and the web server from the shipped compose file plus `docker-compose.local.yml` +- [x] `http://localhost:8080/api/health` answers 200 and `/api/projects` answers 401 without a session +- [x] every migration runs on Postgres (head `8e2cb3003f8a`) +- [x] the api log shows the `Okta sync` startup line +- [x] the steps are in `DEPLOYMENT.md`, "Run the stack on your own PC" +- [x] the shipped `docker-compose.yml` and nginx config are not changed + +Result 2026-10-16 (Docker Desktop 29.7.2, Compose 5.4.0, Windows): passed. Three +things in the shipped files stop a local run. The override handles the first two +and the third is logged: + +1. The web server publishes no port (the host's reverse proxy reaches it). The override publishes 8080 on loopback. +2. An existing `proxy` network on a PC can have no gateway, and Docker then does not publish ports. The override uses its own bridge. The stock nginx `default.conf` also answers "localhost" first and the app server answers only wp.controls.dev, so the override removes the stock file and makes the app server the default. +3. The backup container cannot start on Windows: `scripts/entrypoint.sh` has CRLF line endings (BL-070). The override turns the backup service off.