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

7.9 KiB

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.