Files
sde-meeting-toolkit/DOCKER_TESTING.md
Matt Mabrey 77203955a5 Restrict outbound network to api.anthropic.com only
- New egress-proxy/ container (tinyproxy) that only allows CONNECT to
  api.anthropic.com, refuses everything else.
- docker-compose.yml: sde-meeting-toolkit is no longer on 'default' at
  all. Its only networks are 'proxy' (NPM, inbound) and a new private
  'egress' network shared only with egress-proxy. egress-proxy is the
  only container with a real internet route.
- server.js: route the one outbound Anthropic call through
  EGRESS_PROXY_URL when set, using undici's own fetch + ProxyAgent
  together (mixing them with Node's global fetch throws a version
  mismatch error - caught this locally before it hit a real deploy).
- Add undici as a real dependency (package.json, package-lock.json),
  npm ci step in Dockerfile.
- Add smoke-test-egress.sh + Step 9b in DOCKER_TESTING.md to verify
  this whole chain with real Docker.
- Update CHANGELOG.
2026-09-29 18:16:35 -07:00

176 lines
7.9 KiB
Markdown

# Docker Test Environment: SDE Meeting Toolkit
This doc sets up the toolkit in Docker, on your own machine, for testing. Use it before you hand the container off for company-wide deployment.
## Prerequisites
1. Install Docker Desktop, or Docker Engine and the Docker Compose plugin.
2. Open a terminal.
3. Run this command to confirm Docker works:
```
docker --version
docker compose version
```
If either command fails, install Docker before you continue.
## Step 1: Get the project
1. Go to the `sde-meeting-toolkit` folder.
2. Confirm these files exist: `Dockerfile`, `docker-compose.yml`, `.env.example`, `server.js`.
## Step 2: Create your test environment file
1. Copy `.env.example` to a new file named `.env`, in the same folder.
2. Open `.env` in a text editor.
3. Set a test value for each line:
```
ANTHROPIC_API_KEY=<a personal or trial key, for testing only>
APP_USERS=tester:test-password-123,tester2:test-password-456
RATE_LIMIT_MAX=5
RATE_LIMIT_WINDOW_MS=60000
```
4. Save the file.
Use a personal or trial API key here, not the company-billed key. Keep the company key for the real deployment. `APP_USERS` sets up two logins so you can confirm each person gets their own. `RATE_LIMIT_MAX=5` with a 60 second window makes the rate limit easy to trigger on purpose.
`TOKEN_LIMIT_PER_USER` is left out of this file on purpose: the per-user daily token quota ships off by default (see Step 9, optional). Leave it out unless you specifically want to test that feature.
`.env` is not tracked by Git. Docker Compose reads it automatically because `docker-compose.yml` lists it under `env_file`.
## Step 3: Build the image
1. Run this command in the `sde-meeting-toolkit` folder:
```
docker compose build
```
2. Wait for the build to finish. The image is small; the app has no external dependencies to download.
## Step 4: Start the container
1. Run this command:
```
docker compose up -d
```
2. Run this command to confirm the container is running:
```
docker compose ps
```
3. Run this command to view the startup log:
```
docker compose logs
```
4. Confirm the log reports whether it found `ANTHROPIC_API_KEY`, how many named users are configured, and the per-user token quota.
## Step 5: Test in a browser
1. Open a browser.
2. Go to `http://localhost:5173`.
3. Confirm the browser asks for a username and password.
4. Enter one of the `APP_USERS` pairs from your `.env` file, for example `tester` / `test-password-123`.
5. Confirm the toolkit's landing page loads, with links to both tools.
6. Open each tool link and confirm it loads.
## Step 6: Test the login gate
1. Open a new private or incognito browser window.
2. Go to `http://localhost:5173`.
3. Enter a wrong password.
4. Confirm the page rejects it and asks again.
## Step 7: Test the AI draft button
1. Open the Field Problem Workshop tool.
2. Go to the Breadcrumbs panel.
3. Write a problem statement for a breadcrumb.
4. Click the AI draft button.
5. Confirm the fields fill in, or confirm you get a clear error that names the cause (for example, a bad API key).
## Step 8: Test the rate limit
1. Click the AI draft button more than `RATE_LIMIT_MAX` times within the time window (5 times within 60 seconds, with the test values above).
2. Confirm the next click returns a rate-limit message instead of a normal draft or a silent failure.
3. Wait for the time window to pass, then confirm the button works again.
## Step 8b: Test the login lockout and audit log
1. Open a new private or incognito browser window, or use `curl -u tester:wrongpass http://localhost:5173/`.
2. Enter the wrong password enough times to exceed `LOGIN_ATTEMPT_MAX` (default 10) within the window.
3. Confirm the next request — even with the correct password — is refused with a 429 and a lockout message, not a login prompt.
4. Wait past `LOGIN_LOCKOUT_MS` (default 15 minutes; lower it in `.env` for a faster test), then confirm the correct password works again.
5. Run this command to view the sign-in audit log:
```
cat data/auth-log.jsonl
```
6. Confirm it lists one line per failed attempt (username tried, address, timestamp) and one line for the eventual success. No passwords appear in the file.
## Step 9 (optional): Test the per-user token quota
Skip this step for a normal test run. The quota ships off by default; this is only for confirming the feature still works if you turn it back on.
1. Add `TOKEN_LIMIT_PER_USER=2000` to `.env` and restart: `docker compose up -d --build`.
2. Log in as `tester` and click the AI draft button once or twice, until the response reports a quota error instead of a draft.
3. Confirm the error names `tester`, the tokens used, the limit, and a countdown to the reset.
4. Open a new private or incognito browser window and log in as `tester2` instead.
5. Confirm `tester2` can still click the AI draft button. Each named user has a separate quota.
6. Run this command to view the usage file directly:
```
cat data/token-usage.json
```
7. Confirm it lists a separate entry for each user who made a call, with today's date and a token count.
8. Run `docker compose restart`, then confirm `tester` is still blocked. The quota survives a restart because `data` is a mounted volume.
9. Remove `TOKEN_LIMIT_PER_USER` from `.env` and restart again to turn it back off.
## Step 9b: Test the egress restriction
The container has no direct route to the internet at all. Its one outbound call (the AI draft button) is forced through a second container, `egress-proxy`, which only allows that one destination and refuses everything else. This confirms that restriction actually holds, not just that the AI draft button still works.
1. Run:
```
bash smoke-test-egress.sh
```
2. This rebuilds and starts the full stack (`sde-meeting-toolkit` and `egress-proxy` together), then checks:
- the landing page still loads normally
- the app container cannot reach an unrelated site (`example.com`) directly
- `egress-proxy` refuses to forward to that same unrelated site
- `egress-proxy` does allow a tunnel to `api.anthropic.com`
- the AI draft endpoint still works end to end through the whole chain
3. A `PASS`/`FAIL` line prints for each check, with a summary count at the end. Any `FAIL` line explains what broke and points at the relevant log command.
4. For the last check to be a full test (not just "the server route responds"), set `MOCK_AI=false` with a real `ANTHROPIC_API_KEY` in `.env` first.
## Step 10: Stop the container
1. Run this command:
```
docker compose down
```
2. This stops and removes the container. It does not delete your `.env` file, your `data` folder, or the project folder.
## Rebuild after a code change
1. Edit the code as needed.
2. Run this command:
```
docker compose up -d --build
```
3. This rebuilds the image and restarts the container with your changes.
## Troubleshooting
**Port 5173 is already in use.**
Stop whatever else is using that port, or change the port mapping in `docker-compose.yml` from `"5173:5173"` to, for example, `"5180:5173"`. Then open `http://localhost:5180` instead.
**The browser does not ask for a login.**
Check that `APP_USERS` is set in `.env` (or the legacy `APP_USERNAME`/`APP_PASSWORD` pair), with no typos in the variable names. Restart the container after any `.env` change: `docker compose up -d --build`.
**Everyone seems to share one quota, or a user's quota did not reset the next day.**
Check that each person has their own entry in `APP_USERS`, not one shared `APP_USERNAME`/`APP_PASSWORD`. Quota resets happen on UTC calendar days, which may be a few hours off from your local midnight.
**The AI draft button reports a missing key.**
Check that `ANTHROPIC_API_KEY` is set in `.env` and is a real key. Restart the container after the change.
**Changes to the code do not appear.**
Run `docker compose up -d --build` to rebuild the image. A plain `docker compose up -d` reuses the existing image and skips your changes.
Next: run the steps above in order. Report back once Step 5 loads the login prompt.