From 708c204b8db35ae9aea33519d1ebb0edad9de537 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 3 Sep 2026 18:23:26 +0000 Subject: [PATCH 1/2] docs(enterprise): document integrated Explorer WASM UI in 3.11 ## What changed - Add `content/influxdb3/enterprise/visualize-data/explorer.md`, the server-side deployment page for the integrated Explorer web UI. - Document the `webui` value of `--mode` in the shared config options reference. - Add an Enterprise-only "Web UI" section to the shared config options reference covering `--webui-session-secret` and `--webui-openai-base-url`. - Link the 3.11 release notes entry to the new page. ## Why Enterprise 3.11 ships Explorer inside the binary as a WebAssembly guest, but the only description of it was the release notes entry. Readers had no page that states the requirements, the startup command, or how the integrated UI differs from the Docker container. This is item 3 of the "Before the release" list in docs/exec-plans/2026-09-02-explorer-v110-release-readiness.md (PR #7734), which reserves the Enterprise-side WASM instructions for a separate change. It touches no file that PR #7734 restructures. ## Impact The new page carries `metadata: [InfluxDB 3 Enterprise v3.11+]` and shows both version checks (`influxdb3 --version` and `GET /ping`), following DOCS-VERSION-AVAILABILITY.md. The config options additions are gated with `show-in "enterprise"`, so Core output is unchanged. Four facts are marked with NEEDS VERIFICATION comments rather than guessed: the address that serves the UI, whether the first connection needs an operator token, how the AI chat endpoint authenticates, and the full `--webui-*` option list with its environment variable names. Extract those from `influxdb3 serve --help-all` and remove the comments before publishing. ## Verification - `npx hugo --quiet` builds without errors. - The `#web-ui`, `#webui-session-secret`, and `#webui-openai-base-url` anchors render in the Enterprise config options page and are absent from Core. - Every internal link on the new page resolves to a built page or anchor. - Vale and link-checker aren't installed in this environment, so neither ran. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01DEVE1zb7YVtzh5ZEVAxbdv --- .../enterprise/visualize-data/explorer.md | 207 ++++++++++++++++++ .../shared/influxdb3-cli/config-options.md | 46 ++++ .../_index.md | 3 + 3 files changed, 256 insertions(+) create mode 100644 content/influxdb3/enterprise/visualize-data/explorer.md diff --git a/content/influxdb3/enterprise/visualize-data/explorer.md b/content/influxdb3/enterprise/visualize-data/explorer.md new file mode 100644 index 0000000000..f283fecf87 --- /dev/null +++ b/content/influxdb3/enterprise/visualize-data/explorer.md @@ -0,0 +1,207 @@ +--- +title: Use the integrated InfluxDB 3 Explorer UI +list_title: InfluxDB 3 Explorer +description: > + Serve the InfluxDB 3 Explorer web UI directly from your + {{< product-name >}} server. Starting with v3.11, Explorer ships inside the + Enterprise binary as a WebAssembly (WASM) guest, so you don't run a separate + container. +menu: + influxdb3_enterprise: + parent: Visualize data + name: Use InfluxDB 3 Explorer + identifier: visualize-with-explorer +weight: 100 +metadata: [InfluxDB 3 Enterprise v3.11+] +related: + - /influxdb3/enterprise/reference/config-options/#mode + - /influxdb3/enterprise/reference/config-options/#web-ui + - /influxdb3/explorer/, InfluxDB 3 Explorer documentation +--- + +Starting with {{% product-name %}} v3.11, the +[InfluxDB 3 Explorer](/influxdb3/explorer/) web UI ships inside the Enterprise +binary as a [WebAssembly](https://webassembly.org/) (WASM) guest that the +server hosts in-process behind a +[WASI](https://wasi.dev/) sandbox. +To serve Explorer from your server, add the `webui` mode when you start the +server. +You don't need to run the Explorer Docker container alongside InfluxDB. + +Explorer isn't enabled by default. +The `all` mode doesn't include `webui`, so name `webui` explicitly--for +example, `--mode all,webui`. + +- [Before you begin](#before-you-begin) +- [Check your version](#check-your-version) +- [Start the server with Explorer enabled](#start-the-server-with-explorer-enabled) +- [Connect Explorer to your server](#connect-explorer-to-your-server) +- [Manage the session secret](#manage-the-session-secret) +- [Explorer application data](#explorer-application-data) +- [Enable AI chat](#enable-ai-chat) +- [Choose between integrated and containerized Explorer](#choose-between-integrated-and-containerized-explorer) + +## Before you begin + +To serve Explorer from your server, you need the following: + +- {{% product-name %}} v3.11 or later. + For earlier releases, run the + [Explorer Docker container](/influxdb3/explorer/install/). +- A session secret. + {{% product-name %}} requires + [`--webui-session-secret`](/influxdb3/enterprise/reference/config-options/#webui-session-secret) + whenever `webui` mode is enabled, and doesn't start without it. +- A plugin directory. + Pass the directory to + [`--plugin-dir`](/influxdb3/enterprise/reference/config-options/#plugin-dir) + and create it before you start the server. + +## Check your version + +Explorer availability depends on the InfluxDB 3 server version and edition, not +on the Explorer version alone. +Use either of the following checks. + +To check the version of a local binary: + +```bash +influxdb3 --version +``` + +To check the version and edition of a running server, send a `GET` request to +the `/ping` endpoint: + +```sh +curl --get "http://localhost:8181/ping" \ + --header "Authorization: Bearer AUTH_TOKEN" +``` + +The response headers include `x-influxdb-version` and `x-influxdb-build`. +`x-influxdb-build` reports `Core` or `Enterprise`, so one request answers both +the version question and the edition question. +Use `GET`; a `HEAD` request returns `404`. + +## Start the server with Explorer enabled + +1. Create the plugin directory: + + ```bash + mkdir -p ./plugins + ``` + +2. Start the server with `webui` added to `--mode` and a session secret: + + ```bash + influxdb3 serve \ + --cluster-id cluster0 \ + --node-id node0 \ + --mode all,webui \ + --plugin-dir ./plugins \ + --webui-session-secret "$(openssl rand -base64 24)" + ``` + +`openssl rand -base64 24` generates a new secret on every start, which signs +users out after each restart. +For anything beyond a local trial, generate the secret once and pass the same +value on every start. +See [Manage the session secret](#manage-the-session-secret). + +> [!Important] +> #### Control who can reach Explorer +> +> 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: bind the server to an +> interface you intend to expose, use tokens scoped to the task, and put an +> authenticating reverse proxy with TLS in front of any remote access. +> To control which interface the server listens on, see +> [`--http-bind`](/influxdb3/enterprise/reference/config-options/#http-bind). + + + +## Connect Explorer to your server + +After the server starts, configure a connection to your server in Explorer the +same way you configure one in the standalone Docker Explorer--for example, +`http://localhost:8181`. +For the connection fields and the steps to create a connection, see +[Get started with InfluxDB 3 Explorer](/influxdb3/explorer/get-started/). + + + +## Manage the session secret + +`--webui-session-secret` signs the session cookies that Explorer issues. +The server requires the option whenever `webui` mode is enabled. + +- **Generate the secret once and reuse it.** + A secret that changes on restart invalidates every existing session. +- **Keep the secret out of your shell history and process list.** + Set the secret through the environment variable instead of the command line + when you can. +- **Rotate the secret when it may have been exposed.** + Rotating signs out all users. + +To generate a secret: + +```bash +openssl rand -base64 24 +``` + +## 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](/influxdb3/explorer/install/#persist-data-across-restarts). + +## Enable AI chat + +Explorer includes an AI chat feature that you can point at any +OpenAI-compatible endpoint. +To enable it, set +[`--webui-openai-base-url`](/influxdb3/enterprise/reference/config-options/#webui-openai-base-url) +to the base URL of the endpoint: + +```bash +influxdb3 serve \ + --cluster-id cluster0 \ + --node-id node0 \ + --mode all,webui \ + --plugin-dir ./plugins \ + --webui-session-secret "$WEBUI_SESSION_SECRET" \ + --webui-openai-base-url "https://your-openai-compatible-endpoint" +``` + +Chat prompts, and any query results included with them, go to the endpoint you +configure. +Choose an endpoint that your data handling policies allow. + + + +## Choose between integrated and containerized Explorer + +| | Integrated (WASM) | Docker container | +| :--- | :--- | :--- | +| Requires | {{% product-name %}} v3.11+ | Docker | +| Runs | In the InfluxDB server process | As a separate container | +| Enabled by | `--mode all,webui` | `docker run influxdata/influxdb3-ui` | +| Application data | SQLite synchronized to object storage | SQLite in a mounted volume | +| Works with InfluxDB 3 Core | No | Yes | + +Use the container when you run Core, when you run an Enterprise release +earlier than v3.11, or when you want Explorer to run separately from the +database server--for example, on an operator workstation. +See [Install and run InfluxDB 3 Explorer](/influxdb3/explorer/install/). diff --git a/content/shared/influxdb3-cli/config-options.md b/content/shared/influxdb3-cli/config-options.md index 9ddd8f1a2f..6a39180bfe 100644 --- a/content/shared/influxdb3-cli/config-options.md +++ b/content/shared/influxdb3-cli/config-options.md @@ -193,6 +193,7 @@ For detailed information about thread allocation, see the [Resource Limits](#res - [Processing Engine](#processing-engine) {{% show-in "enterprise" %}} - [Cluster Management](#cluster-management) +- [Web UI](#web-ui) {{% /show-in %}} - [Resource Limits](#resource-limits) - [Data Lifecycle Management](#data-lifecycle-management) @@ -260,6 +261,7 @@ This option supports the following values: - `query`: Enables only query capabilities - `compact`: Enables only compaction processes - `process`: Activates the [Processing Engine](/influxdb3/enterprise/reference/processing-engine/) so the node can execute trigger plugins. `process` has no API surface of its own — it doesn't accept writes or serve queries. Setting [`--plugin-dir`](#plugin-dir) implicitly adds `process` mode regardless of `--mode`. Conversely, `--mode=process` requires `--plugin-dir`. In a multi-node cluster, combine `process` with another mode (typically `query`) so plugins can call `influxdb3_local.query()` locally. +- `webui` *(3.11+)*: Serves the [InfluxDB 3 Explorer](/influxdb3/enterprise/visualize-data/explorer/) web UI from the server process as a WebAssembly (WASM) guest. `all` doesn't include `webui`, so name `webui` explicitly--for example, `--mode all,webui`. `webui` mode requires [`--webui-session-secret`](#webui-session-secret) and [`--plugin-dir`](#plugin-dir). You can specify multiple modes using a comma-delimited list (for example, `ingest,query`). @@ -2359,6 +2361,50 @@ together with the `--internode-bind-addr` option. | :--------------------- | :-------------------- | | `--conn-info` | `INFLUXDB3_CONN_INFO`
`INFLUXDB3_ENTERPRISE_CONN_INFO` ([pre-3.11 name](#name-changes-in-3-11)) | +*** + +### Web UI {#web-ui metadata="v3.11+"} + +Configure the integrated [InfluxDB 3 Explorer](/influxdb3/enterprise/visualize-data/explorer/) web UI, +which the server hosts in-process as a WebAssembly (WASM) guest. +The web UI is off unless you add `webui` to [`--mode`](#mode). + +- [webui-session-secret](#webui-session-secret) +- [webui-openai-base-url](#webui-openai-base-url) + + + +#### webui-session-secret + +Specifies the secret that signs web UI session cookies. +Required whenever [`--mode`](#mode) includes `webui`--the server doesn't start +without it. + +Generate a secret with `openssl rand -base64 24`, then pass the same value on +every start. +A secret that changes between restarts signs out every user. + +| influxdb3 serve option | Environment variable | +| :------------------------ | :-------------------------------- | +| `--webui-session-secret` | `INFLUXDB3_WEBUI_SESSION_SECRET` | + +*** + +#### webui-openai-base-url + +Specifies the base URL of the OpenAI-compatible endpoint that the web UI AI +chat sends requests to. +Chat prompts, and any query results included with them, go to this endpoint. + +| influxdb3 serve option | Environment variable | +| :------------------------- | :--------------------------------- | +| `--webui-openai-base-url` | `INFLUXDB3_WEBUI_OPENAI_BASE_URL` | + {{% /show-in %}} *** diff --git a/content/shared/v3-core-enterprise-release-notes/_index.md b/content/shared/v3-core-enterprise-release-notes/_index.md index 6486e2e5f5..ffa56b2067 100644 --- a/content/shared/v3-core-enterprise-release-notes/_index.md +++ b/content/shared/v3-core-enterprise-release-notes/_index.md @@ -260,6 +260,9 @@ Additional Enterprise-specific updates: cluster. AI chat is included and can point at any OpenAI-compatible endpoint with `--webui-openai-base-url`. + For setup steps, see + [Use the integrated InfluxDB 3 Explorer UI](/influxdb3/enterprise/visualize-data/explorer/). + - **Thread defaults scale with your license on the upgraded storage engine**: On clusters running the upgraded storage engine (the default for new clusters), `--num-io-threads` and the DataFusion thread pool each default to From 9ff6042929f04e2ffe424baab1180b9ab40637f3 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 3 Sep 2026 18:30:50 +0000 Subject: [PATCH 2/2] docs(enterprise): link get-started setup to integrated Explorer ## What changed Add an Enterprise-only optional bullet to the "Start InfluxDB" option list in content/shared/influxdb3-get-started/setup.md, naming `--mode all,webui` and linking to the integrated Explorer deployment page. ## Why The setup guide is where a reader chooses their `influxdb3 serve` options. Without a mention there, the integrated web UI is reachable only from the release notes or the Visualize data section, so a reader setting up a 3.11 server has no reason to know the option exists. The bullet names the dependencies and defers the requirements and the full command to the deployment page rather than repeating them. ## Impact Enterprise only. The bullet is wrapped in `show-in "enterprise"`, and the Explorer link uses the explicit `/influxdb3/enterprise/` path rather than `/influxdb3/version/`, so the shared file produces no Core-side link to a page that doesn't exist in Core. ## Verification - `npx hugo --quiet` builds without errors. - The bullet renders on /influxdb3/enterprise/get-started/setup/ and is absent from the Core build of the same page. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01DEVE1zb7YVtzh5ZEVAxbdv --- content/shared/influxdb3-get-started/setup.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/content/shared/influxdb3-get-started/setup.md b/content/shared/influxdb3-get-started/setup.md index 700ec06722..828f27c40c 100644 --- a/content/shared/influxdb3-get-started/setup.md +++ b/content/shared/influxdb3-get-started/setup.md @@ -115,6 +115,15 @@ Provide the following: To accept only local connections until you create your first admin token, specify `127.0.0.1:8181`. +{{% show-in "enterprise" %}} +- _(Optional, v3.11+)_ `--mode all,webui`: Serves the InfluxDB 3 Explorer web UI + from the server process. + `all` doesn't include `webui`, so name `webui` explicitly. + This mode also requires `--webui-session-secret` and `--plugin-dir`. + For the requirements and the full startup command, see + [Use the integrated InfluxDB 3 Explorer UI](/influxdb3/enterprise/visualize-data/explorer/). +{{% /show-in %}} + > [!Caution] > #### Create your admin token before you expose the server >