Use the integrated Explorer UI

  • InfluxDB 3 Enterprise v3.11+

InfluxDB 3 Enterprise embeds

InfluxDB 3 Explorer 1.11 and serves it directly from the server process. You don’t need to run a separate standalone Explorer deployment to get a query and dashboarding UI.

Enable the Explorer UI

Include webui in --mode and set --webui-session-secret:

influxdb3 serve --mode all,webui --webui-session-secret 
WEBUI_SESSION_SECRET

Replace WEBUI_SESSION_SECRET with a unique secret. Every node in the cluster that runs webui mode must share the same session secret so a browser session stays valid across nodes.

--mode accepts webui alongside any other mode (for example, all,webui, query,webui, or webui by itself). A node that doesn’t include webui in --mode doesn’t serve the UI.

The server serves Explorer at the root path of its regular HTTP address and port–for example, http://localhost:8181/. Explorer doesn’t use a separate port.

Explorer runs without a plugin directory. To use the plugin features in Explorer, create a directory and pass it to --plugin-dir.

Control who can reach Explorer

What someone can do after reaching Explorer depends on whether user authentication is enabled.

  • Without user authentication, anyone who can reach Explorer can use the InfluxDB connection configured in it, with that token’s permissions. Treat reaching Explorer the same as holding the token: use tokens scoped to the task, and put an authenticating reverse proxy with TLS in front of any remote access.
  • With user authentication (v3.12+), users sign in before they reach the UI, and their role determines what they can do. Use TLS for remote access.

Either way, bind the server to an interface you intend to expose. To control which interface the server listens on, see --http-bind. When browsers reach Explorer over HTTPS, also set --webui-cookie-secure so session cookies are never sent over HTTP.

Quick start without authentication

To try Explorer without setting up user authentication, start the server with --without-auth:

influxdb3 serve --mode all,webui \
  --webui-session-secret local-dev-only \
  --without-auth

Explorer configures a working default connection automatically, so you can open the UI and start querying immediately.

Quick start with user authentication

When you start with --user-auth-type set and the cluster has no users and no operator token yet, Explorer shows a setup page (“Set up InfluxDB 3 Explorer”) instead of the normal UI.

If the cluster already has an operator token (for example, an existing deployment that used token authentication), the setup page isn’t offered and influxdb3 manage init-admin returns 409 operator token already configured. Create the first admin user with the operator token instead:

influxdb3 create user --username 
USERNAME
 --role Admin --token 
OPERATOR_TOKEN

  • If password sign-in is available (--jwt-key-id and --jwt-private-key are set), the setup page lets you create the first admin user directly in the browser and shows the operator token once. Store it securely: it can’t be retrieved again.

  • If only OAuth sign-in is configured (--user-auth-type oauth without JWT keys), the setup page can’t take a password, so it directs you to create the first admin from the CLI instead:

    influxdb3 manage init-admin --oauth-id 
    OAUTH_SUBJECT

    Then sign in through your identity provider.

See Bootstrap the initial admin for the equivalent CLI-only workflow.

After you sign in, Explorer configures the default connection for you.

Default connections and query routing

Explorer always needs a default connection (a server URL and API token) to query data. How that connection gets configured depends on how you start the server:

  • --without-auth: Explorer configures a working default connection automatically, without a token.
  • User authentication enabled (--user-auth-type basic and/or oauth): Explorer configures the default connection for you after you sign in.
  • apiv3_ token authentication only (the default: no --without-auth and no --user-auth-type): Explorer has no way to obtain a token automatically, so you provide a server URL and token yourself the first time you connect.

The node that serves the Explorer UI doesn’t have to be the node that serves queries or writes:

  • Every node that serves the UI forwards Explorer’s default-connection requests over the internode protocol to a running node in the cluster, round-robin: a query-capable node for reads, and an ingest-capable node for writes. Only nodes that advertise an internode address (--internode-bind-addr or --conn-info) are used, and the serving node counts as a candidate if it advertises one.
  • If no such node is available, a serving node that itself runs query or ingest mode (for example, a single all,webui node) handles the request locally.
  • Sign-in and user-management requests are always handled by the node that serves the UI.

Configure SSO for the Explorer UI

For browser-based single sign-on through the Explorer UI (as opposed to CLI OAuth login), set --webui-public-uri together with --oauth-client-id, --oauth-issuer, and --oauth-audience:

influxdb3 serve --mode all,webui \
  --webui-session-secret 
WEBUI_SESSION_SECRET
 \
  --user-auth-type oauth \
  --oauth-issuer https://my-idp.example.com/ \
  --oauth-audience my-audience \
  --oauth-client-id 
OAUTH_CLIENT_ID
 \
  --webui-public-uri 
WEBUI_PUBLIC_URI

Replace WEBUI_SESSION_SECRET with your session secret, WEBUI_PUBLIC_URI with the browser-reachable base URL of the Explorer UI (for example, https://explorer.example.com), and OAUTH_CLIENT_ID with your identity provider’s OAuth client ID.

InfluxDB 3 Enterprise derives the OAuth callback URL as WEBUI_PUBLIC_URI/auth/callback. Register that exact URL with your identity provider as an allowed redirect URI.

See Authenticate with OAuth/OIDC for the other OAuth flags.

Sessions

Explorer stores sessions on the server and gives the browser a cookie that identifies the session. --webui-session-secret signs that cookie so the server can reject cookies that were altered or forged. The secret doesn’t encrypt the cookie. Keep the secret private: anyone who has it can create cookies the server accepts.

Sessions are sliding and last 120 days:

  • A session that has 60 days or less remaining is renewed for another 120 days on its next authenticated request, so an actively used session doesn’t expire.
  • A session with no authenticated requests expires 120 days after it was created or last renewed.

Changing --webui-session-secret invalidates every existing session and signs all users out.

To manage the session secret:

  • Generate the secret once and reuse it. To generate a secret, run openssl rand -base64 24.
  • Keep the secret out of your shell history and process list. Set the secret through the INFLUXDB3_WEBUI_SESSION_SECRET environment variable instead of the command line when you can.
  • Rotate the secret if it may have been exposed. Rotating signs out every user.

Explorer application data

The integrated Explorer keeps its application state in a SQLite database that the server synchronizes to object storage for each cluster. You don’t mount a volume to persist it, which is the main operational difference from the Explorer Docker container.

Migrate data from the 3.11 UI

If a browser has data from before you turned on user authentication (for example, from the integrated Explorer in InfluxDB 3.11, or from using Explorer on this deployment without authentication), Explorer offers to migrate that browser’s dashboards, saved queries, query history, and connections to your signed-in account the first time you sign in from that browser.

You can accept or decline the offer. Either way, InfluxDB 3 Enterprise keeps the original data. Declining doesn’t delete anything, and you won’t be asked again from that browser. If you accept, connection credentials (API tokens and object-storage credentials) are cleared from the migrated connections, so you need to re-enter them.

Was this page helpful?

Thank you for your feedback!