Skip to content

maintenance: scope quick-start listeners - #4295

Closed
zqr10159 wants to merge 1 commit into
apache:masterfrom
zqr10159:maintenance/compose-listener-scope
Closed

maintenance: scope quick-start listeners#4295
zqr10159 wants to merge 1 commit into
apache:masterfrom
zqr10159:maintenance/compose-listener-scope

Conversation

@zqr10159

@zqr10159 zqr10159 commented Jul 30, 2026

Copy link
Copy Markdown
Member

What changed?

  • rebase this PR directly onto master, removing its dependency on [fix] bind greptime compose data-store ports to localhost #4258;
  • bind the quick-start HertzBeat web/API listener (1157) and manager/collector transport (1158) to 127.0.0.1 by default;
  • keep the PostgreSQL and GreptimeDB host-published development endpoints on loopback as part of the same standalone change;
  • allow an explicit HERTZBEAT_BIND_ADDRESS override for the two HertzBeat listeners only;
  • document the port purposes, remote collector setup, wildcard-bind risk, credential replacement, TLS, and source-network controls in the English and Chinese quick-start guides;
  • add .env.example and a focused GitHub Actions workflow that validates the final Compose model for both default and explicit override cases.

Upgrade behavior

Ordinary local quick-start users do not need to change anything. Remote collectors must set HERTZBEAT_BIND_ADDRESS to a manager address they can reach and limit 1158 to collector source networks. Remote web/API access uses 1157, preferably behind a TLS reverse proxy. The datastore ports are intentionally unaffected by the override and remain loopback-only.

This branch now contains the required datastore listener scope itself and targets master; it no longer depends on #4258.

Regression proof

The new check-quickstart-compose.sh outcome contract was run before the datastore bindings were changed. It failed because the rendered PostgreSQL and GreptimeDB port objects had no host_ip and therefore were not loopback-scoped.

Validation

  • sh script/ci/check-quickstart-compose.sh — passed for default 127.0.0.1 and explicit 192.0.2.10 HertzBeat bindings, plus loopback-only datastore bindings;
  • HERTZBEAT_BIND_ADDRESS=0.0.0.0 docker compose ... config --format json | jq ... — passed and confirmed the override does not change datastore bindings;
  • Ruby YAML parsing for the Compose file and workflow — passed;
  • sh -n script/ci/check-quickstart-compose.sh — passed;
  • git diff --check and git diff --cached --check — passed.

AI assistance: used for draft implementation and test iteration.
Human validation: rendered and inspected the final Compose model for default, documentation-address, and wildcard-address cases.
Risk notes: remote quick-start access is now an explicit operator choice. Operators still need to replace bundled/default credentials and configure network and TLS controls before any non-loopback exposure.

@zqr10159
zqr10159 force-pushed the maintenance/compose-listener-scope branch from 5de02de to b468e3e Compare July 30, 2026 16:03
@zqr10159 zqr10159 changed the title [chore] scope quick-start service listeners maintenance: scope quick-start listeners Jul 30, 2026
@zqr10159
zqr10159 changed the base branch from fix/005-greptime-compose-port-binding to master July 30, 2026 16:03
@zqr10159

Copy link
Copy Markdown
Member Author

Author remediation update:

This PR is now standalone and directly targets master; it no longer depends on #4258. All quick-start host-published ports are loopback-scoped by default. HERTZBEAT_BIND_ADDRESS changes only HertzBeat 1157 and 1158, while PostgreSQL and GreptimeDB remain local. English and Chinese docs and .env.example cover the web and API port, manager and collector transport, remote collector setup, wildcard-bind risk, credential replacement, TLS, and source-network controls.

The executable Compose contract first failed because the datastore mappings had no host_ip, then passed for default, documentation-address, and wildcard-address renders. A path-scoped GitHub Actions workflow now checks the final Compose JSON. GitHub checks are still starting on the rebased head; maintainer review remains required.

@zqr10159
zqr10159 force-pushed the maintenance/compose-listener-scope branch from b468e3e to 44d55e0 Compare July 30, 2026 16:08
@github-actions github-actions Bot added doc Improvements or additions to documentation infra labels Jul 30, 2026
@zqr10159

Copy link
Copy Markdown
Member Author

CI follow-up: the dedicated quickstart-config job passed, and backend build, Maven E2E, image E2E, license, and label checks have all completed successfully on the rebased current head.

@zqr10159
zqr10159 marked this pull request as ready for review July 31, 2026 02:51
@zqr10159 zqr10159 closed this Aug 3, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

doc Improvements or additions to documentation docker docker-compose infra script

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant