influxdata / influxdata/docs-v2

Explorer install docs: connecting to a native InfluxDB 3 instance from Docker on Linux fails silently with `localhost`

Open
#7,333 0 comments 0 reactions 0 assignees View on GitHub
doc-bug influxdb/influxdb3-explorer
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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.