Skip to content

[doc] align Docker Compose quick-start docs with required .env and loopback binding - #4359

Open
Duansg wants to merge 3 commits into
apache:masterfrom
Duansg:fix-doc
Open

[doc] align Docker Compose quick-start docs with required .env and loopback binding#4359
Duansg wants to merge 3 commits into
apache:masterfrom
Duansg:fix-doc

Conversation

@Duansg

@Duansg Duansg commented Sep 2, 2026

Copy link
Copy Markdown
Member

What's changed?

Follow-up to #4295 and #4257. The Docker Compose quick-start docs still describe the old flow, which no longer works:

  • docker compose up -d fails immediately because POSTGRES_PASSWORD is now required, but the docs never mention .env.
  • The docs say to open http://ip:1157/, but all published ports now bind to 127.0.0.1 by default.
  • .env.example is not included in the docker-compose.tar.gz assembly, so users of the release package have nothing to copy.

Changes:

  • docker-compose-deploy.md (en / zh-cn): add the cp .env.example .env step, switch the access URL to localhost:1157, and add a note on HERTZBEAT_BIND_ADDRESS / HERTZBEAT_OTLP_BIND_ADDRESS for remote access.
  • assembly-docker-compose.xml: ship .env.example with every variant.
  • hertzbeat-postgresql-victoria-metrics/README*.md: add the .env step and the same "Listener scope" section that maintenance: scope quick-start listeners #4295 added to the GreptimeDB variant; fix the title, which said IoTDB.
  • zh-cn upgrade.md: sync the loopback-binding notes already present in the English version.

Verified with markdownlint-cli2 (0 errors on the CI-linted files) and script/ci/check-quickstart-compose.sh.

Checklist

  • I have read the Contributing Guide
  • I have written the necessary doc or comment.
  • I have added the necessary unit tests and all cases have passed.

Add or update API

  • I have added the necessary e2e tests and all cases have passed.

@Duansg
Duansg requested a review from zqr10159 September 2, 2026 15:24
@github-actions github-actions Bot added doc Improvements or additions to documentation docker-compose docker build script labels Sep 2, 2026

@zqr10159 zqr10159 left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for aligning the quick-start documentation and release assembly. I verified the exact current head and found two items to address before approval:

  1. The newly added English and Chinese deployment notes run docker compose config, but then tell users to restart with docker-compose up -d. The documented prerequisite checks the Compose v2 plugin, and a v2-only installation is not guaranteed to provide the legacy docker-compose executable. Please use docker compose up -d consistently in both new notes.
  2. script/docker-compose/hertzbeat-postgresql-victoria-metrics/README_CN.md line 1 contains trailing whitespace, so the PR range fails git diff --check. Please remove it.

The substantive configuration and packaging behavior otherwise looks correct: all five Compose variants rendered successfully with the loopback defaults and independent bind overrides, the Java 25 startup/release package build passed, and the generated Docker Compose archive contains all five .env.example files with the expected fields.

…itespace

- Use the Compose v2 `docker compose up -d` form in the new loopback-binding
  notes (en/zh), matching the documented `docker compose version` prerequisite.
- Remove trailing whitespace on line 1 of the PostgreSQL+VictoriaMetrics
  README_CN.md so the PR range passes `git diff --check`.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01J5sdG2y5wVq8qwM4iez8wk
@Duansg

Duansg commented Sep 6, 2026

Copy link
Copy Markdown
Member Author

@zqr10159 Thanks for the careful review, both points are fixed in 30de922.

  1. docker compose up -d consistency — you're right, the new notes mixed the v2 plugin form (docker compose config) with the legacy standalone binary in the same sentence, which contradicts the documented docker compose version prerequisite. Both new notes now use docker compose up -d:

    • home/docs/start/docker-compose-deploy.md
    • home/i18n/zh-cn/docusaurus-plugin-content-docs/current/start/docker-compose-deploy.md
  2. Trailing whitespace — removed from line 1 of script/docker-compose/hertzbeat-postgresql-victoria-metrics/README_CN.md. git diff --check is now clean over the full PR range.

Re-verified after the fix: markdownlint-cli2 reports 0 errors across the CI-linted globs.

@zqr10159 zqr10159 left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Re-reviewed the remediation on the current head. The Compose v2 command is now consistent in both deployment notes, the trailing whitespace is removed, the full PR range passes git diff --check, all five Compose variants render successfully, and all current GitHub checks are green. No remaining blocking findings.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

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

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants