From efa07927f2f8ba9fad093c370a6ddd9270a27fcb Mon Sep 17 00:00:00 2001 From: Matt Mabrey Date: Thu, 20 Aug 2026 15:09:51 -0700 Subject: [PATCH] Add Docker test environment doc --- DOCKER_TESTING.md | 125 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 125 insertions(+) create mode 100644 DOCKER_TESTING.md diff --git a/DOCKER_TESTING.md b/DOCKER_TESTING.md new file mode 100644 index 0000000..87df540 --- /dev/null +++ b/DOCKER_TESTING.md @@ -0,0 +1,125 @@ +# 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= + APP_USERNAME=tester + APP_PASSWORD=test-password-123 + 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. Set `APP_USERNAME` and `APP_PASSWORD` so you can confirm the login gate works. `RATE_LIMIT_MAX=5` with a 60 second window makes the rate limit easy to trigger on purpose, for testing. + +`.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` and whether a login is required. + +## 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 the `APP_USERNAME` and `APP_PASSWORD` values from your `.env` file. +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: Stop the container + +1. Run this command: + ``` + docker compose down + ``` +2. This stops and removes the container. It does not delete your `.env` file 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 both `APP_USERNAME` and `APP_PASSWORD` are set in `.env`, with no typos in the variable names. Restart the container after any `.env` change: `docker compose up -d --build`. + +**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.