Run every command below from the directory containing compose.yaml.
Start here: service status
Each of db, api and ui reports a health state, and Compose starts them in order — db, then api, then ui, then nginx. A service stuck in starting or marked unhealthy blocks everything after it, so work on the earliest unhealthy service first. A later service that never started is usually a symptom, not the cause.
For the logs of a single service:
The certificate and key are bind-mounted from host paths recorded in .env. If either path does not exist or is not readable, nginx fails at startup rather than serving without TLS.
Check the paths Compose is using, then confirm both files exist on the host:
If a path is wrong, correct it in .env and recreate the container so the new bind mount applies — a plain restart keeps the old mount:
See TLS certificates for the file format and renewal.
Port already in use
nginx is the only service that publishes a host port, on the address and port you chose during setup (BIND_ADDRESS and BIND_PORT in .env, default 0.0.0.0:443). If something else on the host already holds that port, the container cannot bind and Compose reports an allocation failure.
Find the conflict:
Either stop the conflicting service, or change BIND_PORT in .env and recreate nginx. Note that binding below port 1024 requires the Docker daemon to run as root, which is why the install steps use sudo.
The database never becomes healthy
Two causes account for most of it:
- Missing or empty
db/secrets.txt. It is passed in as a Compose secret and holds the key generated by env.sh. If setup was interrupted, the file may be absent.
- Permissions on the data directory, which typically follows a restore where ownership was not preserved. See Backup & restore.
The API never becomes healthy
The API healthcheck calls /api/v1/misc/ping inside the container. Reproduce it directly to separate an API problem from a proxy problem:
If that responds but the browser does not, the problem is in nginx or the network path, not the API. If it does not respond, read the API logs — it fails to start when it cannot reach the database or when required values are missing from .env.
The page loads but every request fails
This is the signature of a URL mismatch. env.sh writes the address you gave it into several variables (CYMPH_APP_BASE_URL, NEXTAUTH_URL, NEXT_PUBLIC_WEBAPP_URL, CYMPH_BACKEND_API_ENDPOINT, NEXT_PUBLIC_BACKEND_API_ENDPOINT) and into the nginx server_name. If you later change the hostname, port or scheme of the deployment, all of them have to agree — the browser is told to call an API address that no longer answers.
After correcting them, recreate the affected services:
Cannot reach the deployment at all
Work outward from the host:
- On the host, confirm the port is listening:
sudo ss -tlnp | grep :443
- From the host, confirm TLS answers:
openssl s_client -connect localhost:443 </dev/null
- From a client, confirm the host firewall and any network firewall permit the port.
If BIND_ADDRESS is set to 127.0.0.1 rather than 0.0.0.0, the deployment is only reachable from the host itself.
Certificate warnings in the browser
Expected with a self-signed certificate. With a CA-issued certificate it usually means the bundle is incomplete — the server certificate is present but the intermediates are missing, so clients cannot build a chain. Concatenate the full chain into the bundle file and restart nginx.
Integrations fail with 403 or a timeout
The deployment is reaching your endpoint from an address that endpoint does not permit, or not reaching it at all. See Networking.
Features are missing or user creation is blocked
The license controls the global user limit and which features are enabled. Check the uploaded license and its expiry — see Licensing.
Locked out of the administrator account
See Resetting the administrator password.
If you need to raise an issue with Cymph, include the service states and recent logs:
Review support.txt before sending it. Logs can contain hostnames, e-mail addresses and integration endpoints from your environment.
