Documentation / Deployment

Initial Configuration

The first-run checklist for a freshly deployed Nexus instance — bootstrap the first administrator, understand the tenant slug, connect your first bridge with secrets held in Key Vault, run a test query, invite your team under RBAC, and confirm the deployment is healthy.

This page is the first-run checklist for a newly provisioned Nexus instance. It is for the administrator who just finished the Azure Marketplace install and needs to bring the instance from "provisioned" to "in production": sign in, connect a data source, prove it works end to end, bring the team on, and verify health. Every step runs against your own Azure subscription and your own data — Nexus is not in a Stingray-hosted service, so there is nothing to configure on Stingray's side.

What the deployment already set up

Before you touch anything, the Marketplace deployment has already provisioned the pieces the first-run flow depends on. Knowing they exist tells you what "healthy" looks like:

A tenant slug — the short, unique identifier you chose in the wizard (for example contoso). It names your instance and, later, your custom-domain hostname. It is fixed at deploy time.
One or more admin bootstrap object IDs — Entra directory object IDs you supplied in the wizard that seed the first administrators. This is how a brand-new tenant avoids a lockout: the people whose object IDs were listed are administrators the moment they first sign in, with no prior grant needed.
A per-tenant Key Vault for secrets, a PostgreSQL Flexible Server (managed-identity auth, passwords disabled) for state, an Azure Files share for pipeline and version-history state, and the Entra app registration that drives sign-in.

1. Sign in as the bootstrap administrator

Open the Nexus desktop app (or your instance's web entry point) and sign in. Authentication is OAuth2 with PKCE against your tenant's Entra ID app registration, so you sign in with your normal organizational Microsoft account — the same credentials, MFA, and conditional-access policies your directory already enforces. Nexus never sees or stores a password.

The first person to sign in must be one of the admin bootstrap object IDs from the deployment. On first sign-in you accept the Terms of Service and Privacy Policy, then land on the dashboard. From there the management surfaces — bridges, users, roles, secrets — are available to administrators. Identity is covered in full in Identity & Sign-In.

2. Connect your first data source (a bridge)

A bridge is a named connection to one data system, identified by its adapter type and a name — for example (mssql, "production"). One adapter type can back many bridges, so two SQL Servers are simply two bridges. Bridges are credential-derived: a bridge exists because its secret exists in your Key Vault.

Bridges come in two scopes:

Scope	Owned by	Who can use it	Managed by
Service	the tenant	anyone whose RBAC permits the report or pipeline that uses it	administrators
User	one individual user	only that user	each user, for their own credentials

For initial setup, create a service bridge so your team can share one connection. In the desktop Bridges page, open Service bridges, add a named bridge, choose the adapter type, and fill in the required fields (host, database, credentials, and so on). Every secret value is written to your tenant's Azure Key Vault — never to the application database and never echoed back in an API response. The isolation rule is absolute: a request can never cause Nexus to resolve another user's credentials, and even an administrator cannot read a stored secret back out of Key Vault.

To confirm what an adapter needs and that the connection works before you commit it:

Review the adapter's required fields in the add-bridge form.
Use Test connection to validate connectivity end to end (network reachability plus authentication).

Personal credentials belong in My bridges, which every user manages for themselves under their own Entra-object-id-keyed namespace. The bridge model and credential isolation are detailed in Connections & Bridges and Secrets.

3. Run a test query

With a bridge configured, prove Nexus can read from it. The fastest path is the MCP tools or the desktop query surface:

List bridges to confirm your new connection appears.
Discover the schema for that bridge to load its tables and columns.
Run a small query — select a handful of rows from a known table.

A quick smoke test against a SQL bridge, expressed as MCP tool calls:

list_bridges                       # confirm (mssql, "production") is present
discover_schema  bridge=production # load tables/columns
query_data       bridge=production
                 SELECT TOP 10 * FROM dbo.Customers

Rows coming back confirm the whole path at once: sign-in, RBAC authorization, credential resolution from Key Vault, network egress to the source, and adapter execution. If the query fails, the error message distinguishes an authorization problem from a connectivity or credential problem, so you know which link to fix.

4. Invite your team

Add teammates so they can build reports, pipelines, and sites. Inviting a user records them against your tenant's Entra directory and assigns a role. Nexus uses granular, per-resource role-based access control, so you scope what each person can see and run rather than granting blanket access. A typical opening posture:

Keep the bootstrap administrators as Admin (manage bridges, users, roles, secrets).
Invite analysts as Reader (or a custom role) with grants that let them run reports and queries against the shared service bridge.
Grant broader authoring rights (pipelines, sites) only to the people who need them, per resource.

You can refine roles and per-resource grants at any time. The full model — roles, per-resource grants, execution roles, and admin edit-locks — is in Roles & RBAC and Users.

5. Verify the deployment is healthy

Finally, confirm the instance is fully ready. Nexus exposes health, readiness, and diagnostic surfaces that report the state of its core dependencies. A healthy first-run deployment shows:

Check	Healthy result
Startup	Ready, with no failed checks
Health (`uql_health`)	OK, version reported
Readiness	Database connected and migrated, secrets loaded, adapters ready, signing secret present
Deep diagnostics (`uql_health_deep`)	Database reachable, all migrations applied, control plane and Key Vault reachable
Bridges (`uql_list_bridges_status`)	Configured bridges report connected

Database migrations run automatically on server startup, so a healthy readiness result also tells you the schema is at the version the running image expects. If readiness reports the database connected, migrations applied, secrets loaded, and adapters ready, the instance is operational.

What's next

Build saved reports and run them on a schedule — see Reports.
Author Python pipelines (async def run(ctx)) that read from your bridges — see Pipelines overview and the Pipeline SDK.
Add a bridge per system you integrate, and configure user bridges where individuals should use their own credentials.
Give your instance a branded URL — see Custom Domains.
Query from Excel — see the Excel add-in.