influxdata / influxdata/docs-v2
Explorer install docs: connecting to a native InfluxDB 3 instance from Docker on Linux fails silently with `localhost`
- Dominant language
- JavaScript
- Stars
- 82
- Forks
- 326
- Avg merge
- 1d 1h
- Merged PRs (30d)
- 82
Description
## Problem
When a user has InfluxDB 3 Core or Enterprise running natively (outside Docker) and follows the Explorer [Quick Start](https://docs.influxdata.com/influxdb3/explorer/install/#quick-start) or [Get started](https://docs.influxdata.com/influxdb3/explorer/get-started/) guide to connect Explorer, they hit a silent networking dead-end on Linux.
The "When to use `host.docker.internal`" note in both `install.md` and `get-started.md` currently says:
> If InfluxDB is running natively on your machine (not in Docker), use `localhost`.
This is correct on **Docker Desktop** (macOS, Windows), where `localhost` inside a container resolves to the host. It is **wrong on Linux with Docker Engine**, where:
- `localhost` inside the container resolves to the container itself (not the host)
- `host.docker.internal` is not automatically available — it requires `--add-host=host.docker.internal:host-gateway` in the `docker run` command
- The Docker bridge gateway (`172.17.0.1` by default) is the reliable fallback
A user in this situation opens the Explorer server configuration dialog, types `http://localhost:8181`, and gets a connection failure with no clear hint as to why.
The `_index.md` Quick Start (`docker run --publish 8080:8080 ... influxdata/influxdb3-ui`) also omits any mention of this networking consideration, so users who start there and jump straight to the UI have no warning before they hit the error.
## Affected pages
- `content/influxdb3/explorer/_index.md` — Quick Start snippet has no networking guidance at all
- `content/influxdb3/explorer/install.md` — "When to use `host.docker.internal`" note says to use `localhost` for native InfluxDB; the Quick Start `docker run` command also lacks `--add-host`
- `content/influxdb3/explorer/get-started.md` — Same "When to use `host.docker.internal`" note with the same incorrect advice
## Expected behavior
The docs should give Linux users a working path forward. Options, in order of simplicity:
1. **Add `--add-host=host.docker.internal:host-gateway`** to the Quick Start `docker run` example (and the Compose equivalent via `extra_hosts`), then keep the `host.docker.internal` advice consistent for all platforms.
2. **Document the bridge gateway fallback** (`172.17.0.1`) as the Linux alternative when `--add-host` isn't used.
3. **Mention `--network host`** as an option (with the caveat that it disables port isolation and is not recommended for shared/production setups).
At minimum, the "use `localhost`" bullet must be qualified: it works on Docker Desktop but not on Linux Docker Engine.
## Suggested fix
**In `install.md` and `get-started.md`**, replace the current note bullet:
> - If InfluxDB is running natively on your machine (not in Docker), use `localhost`.
with something like:
> - If InfluxDB is running natively on your machine (not in Docker):
> - On **Docker Desktop** (macOS or Windows): use `localhost`.
> - On **Linux with Docker Engine**: `localhost` resolves to the container, not the host. Use `host.docker.internal` by adding `--add-host=host.docker.internal:host-gateway` to your `docker run` command (or `extra_hosts: ["host.docker.internal:host-gateway"]` in Compose). Alternatively, use the Docker bridge gateway IP directly (typically `172.17.0.1` — verify with `ip route show default | awk '/default/ {print $3}'` on the host).
**In `install.md` Quick Start**, add `--add-host=host.docker.internal:host-gateway` to the `docker run` example so the one-liner works out of the box for Linux users connecting to a native InfluxDB instance.
**In `_index.md` Quick Start**, add a brief note that the server URL to use in the UI depends on where InfluxDB is running, with a link to the install page for details.
## Steps to reproduce
1. Run InfluxDB 3 Core natively on a Linux host: `influxdb3 serve --node-id my-node`
2. Follow the Quick Start: `docker run --detach --name influxdb3-explorer --publish 127.0.0.1:8888:8080 influxdata/influxdb3-ui:latest`
3. Open `http://localhost:8888`, go to **Configure > Servers**, enter `http://localhost:8181`
4. Explorer fails to connect; `localhost` resolves inside the container to the container itself
## Environment
- Linux with Docker Engine (not Docker Desktop)
- InfluxDB 3 Core or Enterprise running natively (not in Docker)
- InfluxDB 3 Explorer running in Docker
Contributor guide
No contributing guide indexed for this repository
Research direction
Read the Quick Start and networking guidance in content/influxdb3/explorer/_index.md, install.md, and get-started.md, comparing the Docker commands and native-connection notes. Update the affected examples and guidance so Linux Docker Engine users have a working host connection path, while Docker Desktop behavior remains clear; verify the rendered links and Markdown formatting.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- docker
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 84/100