bitflicker64 commented on code in PR #3149: URL: https://github.com/apache/hugegraph/pull/3149#discussion_r3866718064
########## docker/README.md: ########## @@ -196,11 +359,307 @@ curl http://localhost:8520/v1/health # Check Server (Graph API) curl http://localhost:8080/versions -# List registered stores via PD -curl http://localhost:8620/v1/stores +# Every PD endpoint except /v1/health, /actuator/* and /v1/prom/targets/* +# needs an Authorization header. PD only checks that the Basic-auth user is +# one of its internal service names, so the empty password below is enough +# — and it grants the full PD control plane, writes included, not just these +# reads. That is exactly why the shared network must be treated as a trust +# boundary. Without the header PD answers with an exception body, not data. +pd_auth="Authorization: Basic $(printf 'hubble:' | base64)" + +# List registered stores via PD (expect three, each "state":"Up") +curl -H "${pd_auth}" http://localhost:8620/v1/stores # List partitions -curl http://localhost:8620/v1/partitions +curl -H "${pd_auth}" http://localhost:8620/v1/partitions +``` + +Confirm authentication actually engaged — `/versions` stays open by design, +so it cannot tell you whether auth is on. A graph read without credentials +must be rejected: + +```bash +cd docker +# Expect 401 on all three replicas +for port in 8080 8081 8082; do + curl -s -o /dev/null -w "${port}: %{http_code}\n" \ + "http://localhost:${port}/graphs/hugegraph/schema/vertexlabels"; +done + +# And a signed-in read must succeed. Parse the generated single-quoted +# value without executing docker/.env as shell. Passing the credential +# through --config keeps it out of argv, where `ps` would expose it. +# The subshell keeps the `exit 1` below from closing an interactive shell. +( +set -eu +read_dotenv_value() { + key="$1" + key_pattern="^[[:space:]]*(export[[:space:]]+)?${key}=" + count="$(grep -Ec "${key_pattern}" .env || true)" + [ "${count}" -eq 1 ] || return 1 + value="$(sed -nE "s/${key_pattern}'([^']*)'[[:space:]]*$/\\2/p" .env)" + # sed prints nothing and still exits 0 when the value is unquoted or + # double-quoted, which would otherwise hand back an empty credential. + [ -n "${value}" ] || return 1 + printf '%s\n' "${value}" +} +HUGEGRAPH_ADMIN_PASSWORD="$(read_dotenv_value HUGEGRAPH_ADMIN_PASSWORD)" || { + echo "HUGEGRAPH_ADMIN_PASSWORD must use the documented single-quoted format" >&2 + exit 1 +} +curl -s -o /dev/null -w '%{http_code}\n' \ + --config <(printf 'user = "admin:%s"\n' "${HUGEGRAPH_ADMIN_PASSWORD}") \ + http://localhost:8080/graphs/hugegraph/schema/vertexlabels +) +``` + +`200` from the second command with `401` from all three of the first means +authentication is on and working. If the first command returns `200`, the +running image ignored `PASSWORD` and the cluster is **unauthenticated** — +the most likely cause is an image older than the release this integration +needs (see the version note in the quickstart above). + +### Running without authentication + +The cluster above authenticates, and that is the right default: it is the +configuration most people copy, and an open graph database on a reachable +port is a bad surprise. For a throwaway local trial on a trusted network you +can opt out with `docker-compose-3x3.non-auth.yml`, which drops the admin +password and the JWT secret from all three Servers. Anyone who can reach the +published ports then has full read and write access to every graph, so do not +use it anywhere else. + +```bash +cd docker + +# The network and Hubble's volumes are external in every flow, so create them +# once even here. This mode skips only the credential half of the setup block. +docker network inspect hugegraph-net >/dev/null 2>&1 || + docker network create hugegraph-net +for vol in hugegraph-hubble-db hugegraph-hubble-upload-files; do + docker volume inspect "${vol}" >/dev/null 2>&1 || + docker volume create "${vol}" >/dev/null +done + +# No docker/.env is needed. The two placeholders exist only because Compose +# evaluates the base file's required-variable guards before applying the +# override, which then drops both variables, so neither value reaches a +# container. Needs Compose v2.24+. +# +# Keep them inline on every command; do not write them into docker/.env. They +# are published values rather than secrets, and the token placeholder is +# deliberately shorter than the 32 bytes the Server requires, so if it ever +# reaches an authenticated Server that Server refuses to start instead of +# signing tokens with a key anyone can read here. +HUGEGRAPH_ADMIN_PASSWORD=non-auth-placeholder \ +HUGEGRAPH_AUTH_TOKEN_SECRET=non-auth-placeholder \ + docker compose -f docker-compose-3pd-3store-3server.yml \ + -f docker-compose-3x3.non-auth.yml up -d + +# Every graph request now succeeds without credentials: expect 200, not 401. +curl -s -o /dev/null -w '%{http_code}\n' \ + http://localhost:8080/graphs/hugegraph/schema/vertexlabels + +# Teardown. The base file's `:?` guards fire on every subcommand, `down` +# included, so the same two placeholders are required here. +HUGEGRAPH_ADMIN_PASSWORD=non-auth-placeholder \ +HUGEGRAPH_AUTH_TOKEN_SECRET=non-auth-placeholder \ + docker compose -f docker-compose-3pd-3store-3server.yml \ + -f docker-compose-3x3.non-auth.yml down -v +``` + +Hubble needs the matching configuration, because its own default is to demand +a login. Point it at the non-auth properties file when you attach it: + +```bash +HUBBLE_PROPERTIES=./hugegraph-hubble-3x3.non-auth.properties \ + docker compose -p hugegraph-hubble -f docker-compose-hubble.yml up -d +``` + +`HUBBLE_PROPERTIES` is not remembered between commands. It selects a bind +mount, so any later Compose command for Hubble that omits it silently +recreates the container against the authenticated properties file, and Hubble +comes back demanding a login the Servers cannot serve. Repeat the variable on +every Hubble command in this mode, including `up -d --no-deps hubble` and the +local-image commands below. + +<details> +<summary>Prompt for an AI assistant</summary> + +Copy this to an assistant instead of transcribing the commands by hand. + +```markdown +Start the Apache HugeGraph 3-node Docker cluster (3 PD, 3 Store, 3 Server) +with Hubble, from the `docker/` directory of the hugegraph repository. + +Use the authenticated default unless I say otherwise: +1. Follow "3-Node Cluster Quickstart" in docker/README.md to create + docker/.env with a generated admin password and JWT token secret, and to + create the external hugegraph-net network. +2. Start the cluster with docker-compose-3pd-3store-3server.yml, then attach + Hubble with docker-compose-hubble.yml. +3. Verify: an unauthenticated graph request returns 401, an authenticated one + returns 200, and Hubble answers on http://localhost:8088. +4. Tell me the admin password so I can sign in to Hubble. + +Do not weaken authentication to work around an error. If a Server never +becomes healthy, the image is probably older than the release this stack +needs; report that instead of disabling the healthcheck. Only if I explicitly +ask for an unauthenticated cluster, use the "Running without authentication" +section instead. +``` + +</details> + +--- + +## Hubble for the 3-Node Cluster + +`docker-compose-hubble.yml` defines only the Hubble service. It joins the +cluster's external network (`hugegraph-net` by default, override with +`HUGEGRAPH_NETWORK`) and has no `depends_on` on cluster services, so +starting, stopping, or upgrading Hubble never recreates or restarts PD, +Store, or Server containers. Hubble reads the cluster topology from +`hugegraph-hubble-3x3.properties`; adjust that file when attaching to a +cluster with different hostnames. Its `pd.server` is a single PD address +with no failover, so if that PD is down the operations view goes blind even +though the cluster still has quorum — repoint it at a surviving PD. The +operations view also reports one `SERVER` node, not three: it describes the +replica Hubble is currently talking to, not the whole Server tier. The add-on +stores Hubble's H2 database and uploaded files in named volumes +`hugegraph-hubble-db` (mounted at `/hubble/db`) and +`hugegraph-hubble-upload-files`. Those names are explicit, so the attach +and combined Compose projects share the same physical volumes. Hubble's +default H2 URL would write `/hubble/db.mv.db` (outside that mount); the +add-on sets `SPRING_DATASOURCE_URL` so the database file lives inside +`/hubble/db`. Recreating the container does not discard that state. + +Sign in at `http://localhost:8088` as `admin` with the +`HUGEGRAPH_ADMIN_PASSWORD` from `docker/.env`. Hubble binds to host +loopback by default (`HUBBLE_PUBLISH_HOST`, same caveats as the +single-node setup). + +Which flow to use: pick the attach flow when you do not have the cluster's +`docker/.env` — the add-on carries no `:?` guards, so it is the only flow +that runs without those credentials, which is what you want against a +cluster someone else started. Otherwise use the combined flow, including to +add Hubble to an already-running cluster (`up -d --no-deps hubble`). + +The two flows below create Hubble in different Compose projects, so manage +Hubble with the same flags you started it with: the attach flow always uses +`-p hugegraph-hubble -f docker-compose-hubble.yml`, the combined flow always +uses both `-f` flags. The explicit `-p` keeps the attach project independent +of the directory name and of other Compose projects. + +> [!IMPORTANT] +> Do not drop the `-p` from the attach flow. Without it Compose names the +> project after the current directory (`docker`), so Hubble starts in a +> third project that none of the commands below manage: `down` reports +> nothing to remove while `hg-hubble` keeps running, and every later `up` +> in either flow fails on the container name. If that happens, find it with +> `docker ps --filter name=hg-hubble` and remove it with +> `docker rm -f hg-hubble`. + +Run one Hubble per host: the single-node stack and both add-on flows all +publish `127.0.0.1:8088` and name their container `hg-hubble`. The two +add-on flows are therefore mutually exclusive — starting one while the +other's Hubble exists fails with a container-name conflict, so remove the +Hubble of the flow you are leaving before switching. The two directions are +not symmetric: + +```bash +cd docker +# leaving the attach flow (removes only Hubble) +docker compose -p hugegraph-hubble -f docker-compose-hubble.yml down + +# leaving the combined flow — remove ONLY Hubble; a plain `down` with both +# -f flags would stop all ten containers just to move one. +docker compose -f docker-compose-3pd-3store-3server.yml \ + -f docker-compose-hubble.yml rm -sf hubble +``` + +### Attach to a running cluster + +With the 3-node cluster already up: + +```bash +cd docker +docker compose -p hugegraph-hubble -f docker-compose-hubble.yml up -d Review Comment: Fixed in d2a12bc1, and thanks - this was a regression from making the volumes external. The attach section now creates both volumes before the `up`, honouring `HUBBLE_DB_VOLUME` and `HUBBLE_UPLOAD_VOLUME` when the cluster owner renamed them. It is inspect-then-create, so it is safe to repeat and never touches an existing volume. Reproduced your case first: with the volumes absent the attach fails with `external volume "hugegraph-hubble-upload-files" not found`, and with the block it reaches healthy. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
