Skip to content

docs: align distributed startup requirements - #517

Draft
imbajin wants to merge 14 commits into
apache:masterfrom
hugegraph:fix/doc-startup-lifecycle
Draft

imbajin wants to merge 14 commits into
apache:masterfrom
hugegraph:fix/doc-startup-lifecycle

Conversation

@imbajin

@imbajin imbajin commented Oct 11, 2026 •

Copy link
Copy Markdown
Member

The guides mixed 1.7.0 package instructions with current-master launcher behavior. Both languages now distinguish launcher JDK declarations, explicit GC choices and download budgets by version, while retaining the foreground launcher, preserved exit statuses and startup/diagnostic budget guidance for builds containing those repairs.

The actual 1.7.0 PD and Store launchers declare Java 11 and reject explicit -g g1/-g G1; the repaired master launchers require Java 17 and accept those choices. The Store jemalloc connection/total deadlines apply to repaired master builds. Archive download examples are bounded separately. Passing a launcher check does not establish JDK compatibility.

The paired code repairs #3310, #3311, and #3316 are merged; explicit G1 support is in #3305.

Validation: link checks, diff checks, strict cached Hugo build, bilingual rendered-page checks and independent document reviews passed. New-head CI is pending. Source: the original org #42 branch, synchronized with current documentation master.

Service identity, graph-space settings and explicit server.testGraphAlias are proposed, unreleased changes paired with Server org #297 / ASF #3322. Use matching PR chart/image builds for validation and an existing graph's actual Gremlin binding. Current Apache master and released charts/images do not provide these settings. ASF #517 remains draft until Server #3322 merges and the guidance is rechecked against the merged code; non-default PD discovery, authentication and isolation acceptance remain open.

Signing-key upgrade guidance is paired with the auth property fix: explicitly resupply a key that an earlier image misread, and sign in again if the active key changes. Existing 1.7.0 limitations remain explicit.

The authentication upgrade note also distinguishes existing administrator accounts from fresh initialization: an older initializer locale could store an incorrect Unicode password. Upgrading or setting PASSWORD again does not rotate it; an authenticated administrator must use the user API, and this fix does not add automatic account recovery. The paired Server change is apache/hugegraph#3327.

Implementation overview

Conceptual deployment and upgrade guide. Version boundaries require a release containing the corresponding fixes; this diagram does not establish deployment acceptance.

Deployment and upgrade guide with corresponding fix version boundaries

- describe bounded jemalloc downloads and fallback
- preserve Server exit statuses and shutdown deadlines
- align Store GC and Java/Maven prerequisites
- explain independent polling and diagnostic budgets
- describe disabled limits and delayed exit observation
- align Chinese and English deployment guidance
- scope the timeout guarantee to patched builds
- document unbounded requests in earlier builds
- align the Chinese and English deployment guides
- merge current documentation master
- document JDK 17 build and tested runtime
- align PD Maven requirements with the build
@imbajin imbajin changed the title docs: align startup lifecycle guidance docs: align distributed startup requirements Oct 12, 2026
- document Server environment and Helm identity inputs
- explain defaults, aliases and supported name formats
- clarify graphspace creation and authentication scope
- require Java 17 in the PD startup instructions
- list G1 and ZGC launcher selections
- preserve caller or JVM selection when GC is omitted
- apply graphspace naming rules to environment inputs
- clarify validation of the effective legacy fallback
- retain the existing DEFAULT and mounted config contract
- require matching chart and Server image versions
- identify the shared service identity capability
- exclude unsupported earlier deployment examples
- point both Server quickstarts to the ASF repair
- retain the matching chart and image requirement
- connect the website update with its upstream PR
- describe literal dollar signs in Helm service IDs
- document reserved legacy identity environment names
- keep English and Chinese deployment guidance aligned
- document spaces and Unicode with fixed images
- require intended key resupply after prior misreading
- explain token renewal when the active key changes
- retain replica consistency and 1.7 limitations
- describe the persisted Unicode password risk
- distinguish image upgrades from credential rotation
- retain signing-key and older-image boundaries

@bitflicker64 bitflicker64 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Blocking: yes. Summary: The Docker entrypoint, partition-diagnostic, jemalloc and JDK/Maven statements match apache/hugegraph master, and the English and Chinese pages agree. Two things need changes before merge: the Server service identity section documents apache/hugegraph#3322, which is still open, and the new -g rows on the Store and PD pages describe master only while those pages install the 1.7.0 tarball, where -g g1 aborts. Evidence: read the full diff at f569d15 (8 files, +148/-22) against base 2d0b830; compared it with apache/hugegraph master 62faab73d (docker-entrypoint.sh, wait-partition.sh, start-hugegraph.sh, Store and PD launchers, Store util.sh, root pom.xml, .github/workflows/.java-version) and with tag 1.7.0; #3305, #3310, #3311, #3316 and #3327 are merged, #3322 is open; helm template of the master chart with the documented values fails schema validation; the four site build checks on this head pass (publish is skipped).


```bash
helm upgrade --install hg ./helm/hugegraph \
--set-string server.serviceId=analytics \

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Important: this section documents server.serviceId, server.graphSpace, HG_SERVER_SERVICE_ID and HG_SERVER_GRAPHSPACE, which exist only in apache/hugegraph#3322. That PR is still open (head bf33ef6e, review required), so no apache/hugegraph chart or image accepts these settings today.

Evidence: on apache/hugegraph master 62faab73d, git grep -E "HG_SERVER_SERVICE_ID|HG_SERVER_GRAPHSPACE|serviceId|graphSpace" over helm/ and hugegraph-server/hugegraph-dist/docker/ returns nothing, and the master chart rejects the command shown here:

$ helm template hg ./helm/hugegraph --set-string server.serviceId=analytics --set-string server.graphSpace=team_a
Error: values don't meet the specifications of the schema(s) in the following chart(s):
hugegraph:
- at '/server': additional properties 'graphSpace', 'serviceId' not allowed

Lines 131-134 do say to use a chart and image that include #3322, but no such build exists yet, the "Helm chart guide" link on line 159 points at a master README with no service identity section, and the rules written here match #3322 at bf33ef6e, which can still change in review.

Requested change: merge this section only after #3322 is merged, then re-check it against the merged code. If the rest of this PR should go in first, move the section (lines 126-166 here, lines 126-156 of the Chinese page) to a follow-up PR.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

The current head now labels these deployment settings as proposed and unreleased, links the actual paired Server #3322 proposal instead of a master README that lacks the feature, and requires matching PR chart/image builds. It also states the coordinated merge and merged-code recheck requirement. The default hook alias and the need to create the target graph separately from its graph space are explicit; a successful DEFAULT binding check does not establish non-default discovery.

The matching Server follow-up is now publicly available on org #297 / ASF #3322, but #3322 remains OPEN, not merged. ASF Doc #517 has been converted to draft and the draft state was read back. I am leaving this thread open until Server #3322 merges and this guidance is rechecked against the merged code, as requested. Full non-default PD discovery, authentication and isolation acceptance also remain open. Both language pages passed the strict Hugo/link/render checks and independent documentation review.

Comment thread content/en/docs/quickstart/hugegraph/hugegraph-hstore.md Outdated
@imbajin
imbajin marked this pull request as draft October 13, 2026 08:15
- qualify proposed Server deployment settings
- explain explicit existing-graph test aliases
- distinguish released and master launcher behavior
- bound archive download examples
- preserve complete service IDs in metadata reads
- match the case of existing Gremlin bindings
- retain paired unreleased build requirements

This branch has not been deployed

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

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants