Troubleshooting

Start with these three, in order. Between them they explain most of what goes wrong.

docker compose ps                        # is anything restarting
docker compose logs app | tail -50       # why
curl -s http://localhost:3026/api/health # does it reach the database

Startup#

Reinstalling, and 28P01#

Reinstalling does not start over, and this catches almost everyone who tries it.

The database does not live in the install directory. It lives in a Docker volume named after the compose project, which is named after the directory. docker compose down keeps that volume by design, and so does deleting the directory: creating a directory with the same name again re-attaches the same volume. Postgres, for its part, sets the password exactly once, when initdb first creates the data directory, and never looks at POSTGRES_PASSWORD again.

So a second install writes a new random password into a new .env, hands it to a database that has never seen it, and the app crash-loops with:

error: password authentication failed for user "openisms"
  code: '28P01'

Nothing is wrong with the release. Pick whichever of these is true for you.

The instance is empty and you want a genuinely clean start. Deleting the volumes is what "start over" actually requires:

docker compose down -v
docker compose up -d

Your .env is untouched, so the new database is created with the password already in it.

-v removes every volume this project owns, not only the database: postgres-data, minio-data, database-dump, backup-archive, caddy-data and caddy-config. If you have uploaded evidence, or you keep local archives from the backup profile, those go too, and none of it can be undone. "Empty" has to mean empty of files as well as of compliance rows.

The instance holds data and you still have the old .env. Put it back next to compose.yaml. That is the only thing that opens the instance as it stands, and it is by far the best of the three: it recovers the object store and the erasure salt along with the database.

The instance holds data and the old .env is gone. The database is recoverable. Some other things are not, so read this before you start.

Change the database's password to the one in your new .env. No old password is needed, because Postgres trusts connections made from inside its own container:

docker compose exec postgres psql -U openisms -d openisms

At the openisms=# prompt:

\password openisms

It asks twice. Paste the POSTGRES_PASSWORD value from .env, then \q to leave, then docker compose restart app. If you changed POSTGRES_USER or POSTGRES_DB, use those names instead.

Use \password rather than writing the ALTER USER yourself. It prompts instead of taking the password as an argument, so the value never reaches your shell history or the process list, and a password containing quotes needs no escaping.

One trap if you write POSTGRES_PASSWORD by hand rather than letting the installer generate it: compose interpolates .env before it hands the value to the container, so a $ starts a variable reference and usually expands to nothing. pa$$word reaches Postgres as pa. Write $$ for a literal $, or avoid the character. The same applies to every secret in that file.

What a lost .env costs you, beyond the database:

This is why the installer refuses to write a fresh .env over a surviving instance instead of doing it for you.

One thing that will not help you here: docker compose ps reports Postgres as healthy throughout. The health check is pg_isready, which asks whether the server accepts connections, not whether your credentials work. It answers yes for a user that does not exist.

Login#

Content#

Evidence uploads#

Certificates#

Getting help#

Open an issue at github.com/NISD2/open-isms/issues. Include:

• your compose.yaml and .env with every secret stripped,
• docker compose logs app | tail -50,
• what curl -s localhost:3026/api/health returns.

The version in that health response is the first thing anyone will ask for.