Docker Desktop isn't running. Open it and wait for the whale icon in your taskbar/menu bar to show
it's ready, then retry.

Docker needs to download the app's images on first run (roughly 500MB). This can take a few
minutes on a slower connection — it's a one-time cost, later starts are fast.

Wait 30–60 seconds after starting, then open http://localhost:3000
manually — the browser auto-open sometimes fires before the server's actually ready.

Edit docker-compose.yml, change "3000:3000" to "3001:3000" (or any free port), then access
the app at that port instead.

If your working copy lives inside a OneDrive-synced folder on Windows, Next.js's .next build
cache occasionally breaks because OneDrive interferes with the symlinks Next creates during the
build (a real, recurring glitch during this project's own development, not hypothetical). The fix:

# PowerShell
Remove-Item -Recurse -Force .next

# bash
rm -rf .next

Then re-run npm run build. If it recurs often, moving the project outside a OneDrive/Dropbox/
iCloud-synced folder avoids it entirely.

If a change involved deleting or renaming a directory (not just editing files), a normal
docker compose build can serve a stale cached layer that still references the old path. Rebuild
with --no-cache whenever a session's changes included directory deletions:

docker compose -f docker-compose.yml -f docker-compose.prod.yml build --no-cache dashboard
docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d dashboard

A running container isn't the same as a healthy app — always check the actual logs after a deploy,
not just docker ps. An unhandledRejection in the logs means something is actually broken even
though Docker reports the container as up.

• Docker install (desktop)
• Environment variables reference