Self-Hosted Deployment
Verify a self-hosted deployment
Check the settings, the services, sign-in and an embed after you install or upgrade Databrain.
Run these checks in order after every install or upgrade. Each one needs the one before it.
1. Check the settings before you start
The backend checks its required settings without connecting to anything:
docker compose run --rm databrainbackend node dist/preflight.jsIt ends with exit code 0 when all is well. Each problem prints one line, PREFLIGHT FAIL <NAME> or PREFLIGHT WARN <NAME>, with the reason.
| Setting | Required |
|---|---|
HASURA_ENDPOINT, HASURA_ADMIN_SECRET, HASURA_JWT_SECRET_KEY, REFRESH_TOKEN_SECRET, ENCRYPT_SECRET_KEY | Yes |
HASURA_ACTION_SECRET | Yes, the same value on the backend and on Hasura. Falls back to the admin secret |
HASURA_EVENTS_SECRET, MODEL_RESULT_WINDOW_SECRET | No. Made from HASURA_ADMIN_SECRET when not set. Your own MODEL_RESULT_WINDOW_SECRET needs 32 or more characters |
HOSTED_APP_URL | A warning when not set |
Keep ENCRYPT_SECRET_KEY the same across upgrades. It encrypts saved datasource credentials. On Kubernetes, run the same command as an init container.
2. Start and check the services
Start the install, then check each service:
curl -fsS https://api.analytics.example.com/health/live
curl -fsS https://api.analytics.example.com/health/ready/health/live answers {"status":"live"}. /health/ready answers 200 with "status":"ready" when Hasura, the database and (if set) Keycloak and Redis are up. See Set up health checks.
3. Run the diagnostics tool
databrain-diag checks the install from inside the containers. It ships in the Hasura image:
docker run --rm --entrypoint cat <registry>/dbn-hasura-multix:<version> \
/usr/local/bin/databrain-diag > databrain-diag && chmod +x databrain-diag
./databrain-diag checkIt checks Hasura (/healthz?strict=true), the database, the backend /health/live, the backend to Hasura, and Redis. Add --warehouse <host>:<port> to test that the backend reaches a warehouse. On Kubernetes, add --k8s -n <namespace>.
| Exit code | Meaning |
|---|---|
0 | All checks passed |
1 | A check failed |
2 | The tool could not run (no Docker or kubectl, or a bad option) |
Run ./databrain-diag with no command to also write a support bundle (a zip). It never stores secret values, and it masks every file. Send the zip to Databrain support when you need help.
4. Sign in and check the license
- Open your app address and sign in as an admin.
- Go to Settings > License. The status shows Licensed and Valid until shows the right date.
See Manage your license.
5. Check the data path
Open a dashboard that uses each of your datasources, and check that its metrics load.
6. Check an embed
- Make a guest token on your server with your data app API token.
- Load an embed with
base-urlset to your API address. See Point embeds at your instance. - In the browser’s network tab, check that the requests go to your API address and answer
200.
Use a client ID with known data, and check that the embed shows only that client’s rows.
7. Check the MCP server (if you turned it on)
GET <your app address>/mcp answers 401 without a sign-in. That means it runs. Then connect an AI app from Settings > MCP.
If a step fails, stop there. Fix it before you go on, because the later steps depend on it.