When something breaks
The most common cases, their cause, and the concrete fix.
Two moves solve most mysteries: the health check at /api/health (is the store up, is the database fine, which version?) and the container log:
cd /opt/vault/docker && docker compose --env-file ../.env logs -f appCommon cases
| Symptom | Cause | Fix |
|---|---|---|
| The build is killed partway through | Not enough memory — the most common install failure on small servers | Add 2 GB of swap and run install.sh again — it offers to do this for you |
| Login just does not work, no error shown | APP_URL in .env does not match the address in the browser (http/https, www, port) | Set APP_URL to exactly the browser address, restart the container |
| Page loads but unstyled / no images | Manual installs only: the three copy steps after the build are missing | See Advanced — the three cp commands are mandatory |
| Operator password forgotten | — | “Forgot password?” on the sign-in page — needs email configured |
| Setup wizard is stuck | An abandoned wizard run | pnpm reset:install resets only the wizard |
| Container runs but never reports healthy | Usually the database is not ready yet, or .env is incomplete | Watch the log (command above) — the first red line names the reason |