T13.8: run the stack in Docker on a PC, local compose override and steps (D22); log BL-070

This commit is contained in:
2026-10-16 15:08:01 -07:00
parent bcef0e8145
commit ad1b8273c0
5 changed files with 111 additions and 0 deletions

10
.env.local.example Normal file
View File

@@ -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

View File

@@ -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: sync changes **no** account in that cycle and writes a line to the api log:
`docker compose logs api | grep "Okta sync"`. `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 ## Permissions roles
`User.role` is the **permissions** role; `User.project_role` is the person's **job `User.role` is the **permissions** role; `User.project_role` is the person's **job

38
docker-compose.local.yml Normal file
View File

@@ -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

View File

@@ -817,3 +817,16 @@ boundary"). Do not use `localStorage` as the store of record.
as an option. Keep that behavior when the list changes. as an option. Keep that behavior when the list changes.
- **Suggested wave or follow-up:** future wave, after the codes arrive. - **Suggested wave or follow-up:** future wave, after the codes arrive.
>>>>>>> theirs >>>>>>> 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.

View File

@@ -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. Result 2026-10-16: all Okta sync tests and `security_check.py` pass in the sandbox.
This task changes no frontend file. 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.