sde-meeting-toolkit/DOCKER_TESTING.md

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