Skip to Content

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.js

It ends with exit code 0 when all is well. Each problem prints one line, PREFLIGHT FAIL <NAME> or PREFLIGHT WARN <NAME>, with the reason.

SettingRequired
HASURA_ENDPOINT, HASURA_ADMIN_SECRET, HASURA_JWT_SECRET_KEY, REFRESH_TOKEN_SECRET, ENCRYPT_SECRET_KEYYes
HASURA_ACTION_SECRETYes, the same value on the backend and on Hasura. Falls back to the admin secret
HASURA_EVENTS_SECRET, MODEL_RESULT_WINDOW_SECRETNo. Made from HASURA_ADMIN_SECRET when not set. Your own MODEL_RESULT_WINDOW_SECRET needs 32 or more characters
HOSTED_APP_URLA 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 check

It 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 codeMeaning
0All checks passed
1A check failed
2The 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

  1. Open your app address and sign in as an admin.
  2. 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

  1. Make a guest token on your server with your data app API token.
  2. Load an embed with base-url set to your API address. See Point embeds at your instance.
  3. 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.