Skip to content

Troubleshooting

The ways a first run most often looks broken when it is not, each from a real session:

  • A rebuild changed nothing on screen. The browser is serving the previous stylesheet and script from its cache. Hard-refresh the tab (Ctrl+Shift+R) after any docker compose up --build; the served files are current, the tab is not.
  • The demo command exits with code 1 and a message about admin variables. It refuses to run without MANIFEST_IDENTITY_ADMIN_USERNAME and MANIFEST_IDENTITY_ADMIN_PASSWORD set, on purpose, so no clone ever carries a default account. Set both in .env and run it again.
  • The app container starts and then exits. The database password split (D-051) means MANIFEST_IDENTITY_APP_DB_PASSWORD must be present in .env alongside POSTGRES_PASSWORD; a missing one fails the migration step before the server starts. docker compose logs migrate names which.
  • Port 8000 is already taken. Another instance, often a forgotten uvicorn, holds it. ss -ltnp | grep 8000 names the process; stop it or change the published port in the compose file.
  • Sign-in fails right after a fresh start. The admin user is created by the bootstrap on first start from the same two variables; if they changed after the first run, the stored user did not. Reset with the database-delete step above, or create the user through the admin routes.
  • The container job fails on a scheduled run when nothing changed. Debian shipped a fix for a package in the pinned base image, and the scan blocks until the digest moves. Pull the tag named in the Dockerfile's comment, read its manifest digest from the registry, and move it in the Dockerfile and the workflow twin in one commit; the parity check refuses either alone. If upstream has not rebuilt yet, the built image already carries the fix through its own update step, and only the base row stays red until it has.