Skip to content

docs: fix Docker 1C2D example path and pgxc configuration filename - #63

Open
Lycorius03 wants to merge 1 commit into
OpenTenBase:mainfrom
Lycorius03:docs/203-fix-1c2d-guide
Open

Lycorius03 wants to merge 1 commit into
OpenTenBase:mainfrom
Lycorius03:docs/203-fix-1c2d-guide

Conversation

@Lycorius03

Copy link
Copy Markdown

Related to OpenTenBase/OpenTenBase#203

Problem

Issue OpenTenBase/OpenTenBase#203 reports two defects on the published Docker 1C2D guide page
https://docs.opentenbase.org/guide/15-docker-deploy, and two independent readers confirmed
the second one. Both defects live in the source of that page, i.e. in this repository:

  1. Step 2 tells the reader to run cd ${SOURCECODE_PATH}/example/1c_2d_cluster. That directory
    does not exist on OpenTenBase/OpenTenBase@master: the whole example/ tree was deleted by
    commit aca7e2c
    ("Update basecode version from 2.6.0 to 5.0.0"). Steps 2 to 4 therefore cannot be run as
    written — only the image build used by step 1 (docker/buildImage.sh) still exists.

  2. Step 4 says deploy all uses /home/$USER/pgxc_ctl/pgxc.conf. That file name is wrong:
    pgxc_ctl reads pgxc_ctl.conf, and there is no rename step anywhere in the tool.

The source repository was corrected in OpenTenBase/OpenTenBase#312 (docker/README.md). This
PR applies the same findings to the page users actually read.

Changes

Two files, both locales, nothing else:

File Change
docs/guide/15-docker-deploy.md step 1: note that SOURCECODE_PATH must be replaced with your own clone path. step 2: add a note that example/1c_2d_cluster no longer exists on master, name the commit that removed it, point to the configuration template that is still published, and give the revision from which the removed Compose file can still be retrieved. step 4: correct pgxc.conf → pgxc_ctl.conf and add the source-level reason.
docs/guide/15-docker-deploy.en.md same changes, English.

The step 2 and step 4 shell code blocks are otherwise byte-identical: no command is added,
removed or reordered, and no new deployment procedure is introduced. mkdocs.yml is untouched
(no page is renamed, so the nav is unaffected).

Evidence

Claim Evidence
example/1c_2d_cluster is not on master git ls-tree -r --name-only HEAD in OpenTenBase/OpenTenBase (8419 paths) → 0 matches for 1c_2d; git rev-list --all --objects → 0 matches, so it was deleted rather than moved
It was deleted by aca7e2c git log --diff-filter=AD -- 'example/*' → aca7e2c lists D for example/1c_2d_cluster/README, docker-compose.yaml, pgxc_conf/cn/pgxc_ctl.conf
Only the image build survives in the source repo docker/buildImage.sh, docker/base/Dockerfile, docker/host/Dockerfile are still on master
${SOURCECODE_PATH} is the user's clone path OpenTenBase/OpenTenBase README.md line 78 and docker/host/Dockerfile line 29 both set it to /data/opentenbase/OpenTenBase
pgxc_ctl reads pgxc_ctl.conf contrib/pgxc_ctl/pgxc_ctl.h #define DEFAULT_CONF_FILE_NAME "pgxc_ctl.conf"; contrib/pgxc_ctl/pgxc_ctl.c setDefaultIfNeeded(VAR_configFile, "pgxc_ctl.conf") and build_configuration_path() resolving <pgxc_ctl_home>/<configFile>, with pgxc_ctl_home defaulting to $HOME/pgxc_ctl
pgxc.conf belongs to another tool repository-wide search for pgxc.conf in OpenTenBase/OpenTenBase returns only contrib/pgxc_ddl/* and doc/src/sgml/pgxcddl.sgml; contrib/pgxc_ddl/pgxc_ddl sets PGXC_CONF=$DATA_FOLDER/pgxc.conf
The 1C2D configuration template is in this repository docs/guide/pgxc_ctl_double.conf and docs/guide/pgxc_ctl_single.conf

Validation

Documentation only, and this repository's CI does not run on pull requests
(.github/workflows/ci.yml is on: push to main/master only). So the deploy pipeline was
reproduced locally with the same two packages it installs — mkdocs-material (9.7.7) and
mkdocs-static-i18n (1.3.1) under mkdocs 1.6.1 — and mkdocs build was run twice:

  • on the pristine tree (git checkout -- both files), and
  • on the changed tree.

Results:

  • Both builds exited 0.
  • The two build logs are identical after normalising the output directory and the reported
    duration. That includes the only two messages emitted, which are pre-existing anchor warnings
    in an unrelated file (contribution/docs-format-guide.md, links #中文文案排版指北 and
    #工具). No new warning or error is introduced.
  • The generated HTML was then inspected in both locales: the baseline contains the wrong
    pgxc_ctl/pgxc.conf reference, the changed build no longer does, and the changed build
    contains the removal commit, the historical revision link and pgxc_ctl_double.conf. The
    added note renders as a <blockquote>, with no literal !!! and no unrendered **Note**.
  • Every URL added was fetched and returns HTTP 200, including the historical revision link.
  • Encoding: both files remain valid UTF-8 with no BOM (matching the originals), no replacement
    characters, and balanced code fences. git diff --check is clean and
    git ls-files --others --exclude-standard is empty.

Not validated: no Docker image was built and no 1C2D cluster was deployed, so this PR does not
assert that the removed example can be reconstructed into a working deployment.

Note on style choices

Two deliberate departures from the obvious approach, both driven by measurement:

  • Plain blockquotes rather than !!! note. mkdocs.yml nests markdown_extensions inside
    the theme: block, so the admonition, tables and attr_list extensions are not actually
    enabled. Confirmed against the live site: fetching
    https://docs.opentenbase.org/contribution/docs-format-guide/ returns HTML containing a
    literal !!! and no class="admonition", i.e. the existing admonition blocks render as plain
    text. Note that fixing that nesting is a separate issue and is deliberately left alone here.
  • Absolute GitHub URLs rather than relative paths. docs/contribution/docs-format-guide.md
    asks for relative paths for in-site links, but pgxc_ctl_double.conf is published only for
    the Chinese locale — https://docs.opentenbase.org/guide/pgxc_ctl_double.conf returns 200
    while https://docs.opentenbase.org/en/guide/pgxc_ctl_double.conf returns 404 — so a
    relative link would be broken on the English page. Happy to switch the Chinese file to a
    relative path if you prefer.

Follow-up, not changed here

  • The guide's final psql -h 172.16.200.10 -p 30004 targeted opentenbaseDN1, not the CN
    (172.16.200.5) in the removed Compose file. Left alone: without the Compose file this cannot
    be confirmed against a running cluster.
  • Whether example/1c_2d_cluster should be restored, or this guide retired in favour of the
    KubeBlocks path, is a maintainer decision. This PR documents the current state and does not
    assume an answer.

AI Usage

Produced by an AI agent (WorkBuddy). Every statement added is traceable to a file/line, a
commit, or a live HTTP check; no parameter meaning was inferred from general knowledge.

The published page docs.opentenbase.org/guide/15-docker-deploy has two defects,
both reported in OpenTenBase/OpenTenBase#203 and confirmed there by two
independent readers:

1. Step 2 tells the reader to run cd ${SOURCECODE_PATH}/example/1c_2d_cluster.
   That directory does not exist on OpenTenBase/OpenTenBase@master: the whole
   example/ tree was deleted by commit aca7e2c ("Update basecode version from
   2.6.0 to 5.0.0"), so steps 2 to 4 cannot be run as written. Only the image
   build path used by step 1 (docker/buildImage.sh) survives.

2. Step 4 says deploy all uses /home/$USER/pgxc_ctl/pgxc.conf. pgxc_ctl reads
   pgxc_ctl.conf and there is no rename step anywhere in the tool
   (contrib/pgxc_ctl/pgxc_ctl.h DEFAULT_CONF_FILE_NAME, and
   contrib/pgxc_ctl/pgxc_ctl.c build_configuration_path()). pgxc.conf is the
   configuration file of the unrelated pgxc_ddl tool.

Both locale sources are corrected: docs/guide/15-docker-deploy.md and
docs/guide/15-docker-deploy.en.md.

Changes per file:

- step 1: state that SOURCECODE_PATH must be replaced with your own clone path;
- step 2: add a note naming the commit that removed the directory, point to the
  configuration template that is still published, and give the revision from
  which the removed Compose file can still be retrieved;
- step 4: correct the file name in the inline comment and add the source-level
  reason, so the "should this be renamed" question does not come back.

The step 2 and step 4 code blocks are otherwise unchanged: no command is added,
removed or reordered, and no new deployment procedure is introduced.

Notes:

- Plain blockquotes are used rather than admonitions, because mkdocs.yml nests
  markdown_extensions under theme:, so admonition is not actually enabled. This
  is verifiable on the live site, where the existing !!! note blocks render as
  literal text. Fixing the mkdocs.yml nesting is a separate issue and is left
  alone here.
- Links to other repositories and to pgxc_ctl_double.conf are absolute GitHub
  URLs. A relative path would be broken on the English page, because that file
  is not published under /en/.

Related to OpenTenBase/OpenTenBase#203 and to the source-repository change in
OpenTenBase/OpenTenBase#312.
@Lycorius03

Copy link
Copy Markdown
Author

说的都队

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.

1 participant