Root User Configuration

SigNoz allows you to provision a root user during startup so an admin account exists immediately after deployment. This eliminates the gap between deployment and manually creating the first admin, enhancing security for fresh installs and automation (e.g., IaC, GitOps). The root user is created from configuration at startup.

This feature is available starting with SigNoz v0.112.0.

Prerequisites

SigNoz v0.112.0 or later.
A relational database (SQLite or Postgres) already configured for SigNoz (used for organizations and users).

Configuration

Set the root user via environment variables:

Variable	Description
`SIGNOZ_USER_ROOT_ENABLED`	Enable root user provisioning (`true` / `false`).
`SIGNOZ_USER_ROOT_EMAIL`	Email address of the root user.
`SIGNOZ_USER_ROOT_PASSWORD`	Password for the root user. Use a strong password.
`SIGNOZ_USER_ROOT_ORG_NAME`	Name of the organization for the root user (e.g. `default`).

Example:

SIGNOZ_USER_ROOT_ENABLED=true
SIGNOZ_USER_ROOT_EMAIL=admin@example.com
SIGNOZ_USER_ROOT_PASSWORD=<secure-password>
SIGNOZ_USER_ROOT_ORG_NAME=default

The root user cannot be deleted, edited, or have its password changed from the SigNoz UI. To change credentials, update the environment variables and restart (where supported by your deployment).
Root user provisioning runs at startup only; changing env vars requires a restart to take effect.

Fresh installs

For a new SigNoz deployment:

Set the root user environment variables before first start (e.g. in your deployment manifest, Helm values, or Compose file).
Set SIGNOZ_USER_ROOT_ENABLED=true and provide SIGNOZ_USER_ROOT_EMAIL, SIGNOZ_USER_ROOT_PASSWORD, and SIGNOZ_USER_ROOT_ORG_NAME.
Deploy or start SigNoz. On startup, the root user and organization (if needed) are created. You can log in immediately with the configured email and password.

Existing installs

If SigNoz is already running and you want to enable the root user:

Align the organization name with what you will set in config. This query sets the organization name in the database so it matches the root user config. In your SigNoz relational database (SQLite or Postgres), run:
```
UPDATE organizations SET name = '<org-name>';
```
Verify this value:
- <org-name>: The value you will use for SIGNOZ_USER_ROOT_ORG_NAME (e.g. default). Use the same value in both the query and the env var.
Set the root user environment variables (SIGNOZ_USER_ROOT_ENABLED, SIGNOZ_USER_ROOT_EMAIL, SIGNOZ_USER_ROOT_PASSWORD, SIGNOZ_USER_ROOT_ORG_NAME) to match the organization you updated above.
Restart SigNoz so it provisions the root user on startup.

The value in SIGNOZ_USER_ROOT_ORG_NAME must match the organization name in the database. A mismatch can prevent the root user from being associated with the correct organization.

Validate

After deployment or restart:

Open the SigNoz UI and go to the login page.
Sign in with the root user email and password you configured.
Confirm you have full admin access (e.g. Settings → Org Settings, user management).

Troubleshooting

Root user not created after restart

Ensure SigNoz is v0.112.0 or later.
Check that SIGNOZ_USER_ROOT_ENABLED is true and that SIGNOZ_USER_ROOT_EMAIL, SIGNOZ_USER_ROOT_PASSWORD, and SIGNOZ_USER_ROOT_ORG_NAME are set. Restart SigNoz after changing env vars.
Check SigNoz logs for errors during startup related to root user provisioning.

Root user cannot log in or is in the wrong organization

Ensure the organization name in the database matches SIGNOZ_USER_ROOT_ORG_NAME. Re-run the UPDATE organizations query from Existing installs with the same <org-name> as in your env vars, then restart SigNoz.