Nkechi

The failure mode nobody warns you about: permissions.

The catalogue deployed containers running as a particular user and group, and it quietly set ownership or an ACL on the host directories to match. When you rebuild the container yourself and the runtime picks a different user, the app starts, finds it cannot write, and fails in whatever way that app fails — sometimes an error, sometimes an empty screen, sometimes silently losing writes.

So add a fifth item to the inventory list: the numeric user and group the container runs as. Then set the same one explicitly in your own definition.

If you are on a filesystem with ACLs rather than plain permission bits, be aware the mode you see in a directory listing is not the whole story. Read the ACL properly before concluding the permissions are fine.

Stop redeploying. Each redeploy destroys the evidence and, worse, leaves partial state behind that changes the next attempt.

The status the UI shows you is the orchestrator's opinion of the container, not the application's. "Failed" means a process exited non-zero or a health check never passed. The reason is in the container's own log, and you have to go and get it.

Deploy it once more, and while it is in the deploying state — not after it gives up — get a shell on the host and list the running containers for that app, then follow the logs of each one. If the app ships a database alongside itself there will be more than one container, and the one that fails is usually not the one you were watching.

With the actual log in front of you, it is almost always one of three things:

1. Permissions on the host dataset. The app runs as a specific unprivileged user inside the container. If the dataset you pointed it at is owned by root, or carries an ACL that denies that user, the app cannot create its data directory and dies at startup. The log line is some form of permission denied on a path, and it is unmissable once you are reading the right log.

The fix is to set ownership of that dataset to the user and group the app expects, recursively, before deploying. Note that on a filesystem with ACLs, a permissive-looking mode can still be overridden by an ACL entry — check the actual ACL, not just the mode.

2. A non-empty data directory from a previous failed attempt. This is the one that makes it reproducible across four attempts. Bundled database engines refuse to initialise into a directory that already contains files, so attempt one leaves half a database behind and attempts two through four fail for a different reason than attempt one did — and look identical from the UI.

The fix is to genuinely empty the data path between attempts. If you created a fresh dataset each time you may have dodged this; if you reused one, this is very likely your problem.

3. A port already bound. The app wants a port something else is already holding. The log says address already in use. Cheap to rule out: list listening sockets on the host before deploying.

My money is on the second one, because it fits "identical result every time" better than the others do.

A different cause that produces the same symptom, worth ruling out if the reset above does not work: the app initialised correctly but is now talking to a different database than the one it initialised.

Happens when the database host, name or credentials in the environment change between deployments — you renamed something, or a generated password was regenerated on redeploy. The app finds a database that exists and is reachable but has no user table matching what it expects, and hands you a login page it cannot satisfy.

Check the connection settings in the current deployment against what the app's log says it connected to at startup.