docs: fix Docker 1C2D example path and pgxc configuration filename - #63
Open
Lycorius03 wants to merge 1 commit into
Open
Lycorius03 wants to merge 1 commit into
Lycorius03 wants to merge 1 commit into
Conversation
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.
Author
|
说的都队 |
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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:
Step 2 tells the reader to run
cd ${SOURCECODE_PATH}/example/1c_2d_cluster. That directorydoes not exist on
OpenTenBase/OpenTenBase@master: the wholeexample/tree was deleted bycommit
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.Step 4 says
deploy alluses/home/$USER/pgxc_ctl/pgxc.conf. That file name is wrong:pgxc_ctlreadspgxc_ctl.conf, and there is no rename step anywhere in the tool.The source repository was corrected in OpenTenBase/OpenTenBase#312 (
docker/README.md). ThisPR applies the same findings to the page users actually read.
Changes
Two files, both locales, nothing else:
docs/guide/15-docker-deploy.mdSOURCECODE_PATHmust be replaced with your own clone path. step 2: add a note thatexample/1c_2d_clusterno longer exists onmaster, 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: correctpgxc.conf→pgxc_ctl.confand add the source-level reason.docs/guide/15-docker-deploy.en.mdThe step 2 and step 4
shellcode blocks are otherwise byte-identical: no command is added,removed or reordered, and no new deployment procedure is introduced.
mkdocs.ymlis untouched(no page is renamed, so the nav is unaffected).
Evidence
example/1c_2d_clusteris not onmastergit ls-tree -r --name-only HEADinOpenTenBase/OpenTenBase(8419 paths) → 0 matches for1c_2d;git rev-list --all --objects→ 0 matches, so it was deleted rather than movedaca7e2cgit log --diff-filter=AD -- 'example/*'→aca7e2clistsDforexample/1c_2d_cluster/README,docker-compose.yaml,pgxc_conf/cn/pgxc_ctl.confdocker/buildImage.sh,docker/base/Dockerfile,docker/host/Dockerfileare still onmaster${SOURCECODE_PATH}is the user's clone pathOpenTenBase/OpenTenBaseREADME.mdline 78 anddocker/host/Dockerfileline 29 both set it to/data/opentenbase/OpenTenBasepgxc_ctlreadspgxc_ctl.confcontrib/pgxc_ctl/pgxc_ctl.h#define DEFAULT_CONF_FILE_NAME "pgxc_ctl.conf";contrib/pgxc_ctl/pgxc_ctl.csetDefaultIfNeeded(VAR_configFile, "pgxc_ctl.conf")andbuild_configuration_path()resolving<pgxc_ctl_home>/<configFile>, withpgxc_ctl_homedefaulting to$HOME/pgxc_ctlpgxc.confbelongs to another toolpgxc.confinOpenTenBase/OpenTenBasereturns onlycontrib/pgxc_ddl/*anddoc/src/sgml/pgxcddl.sgml;contrib/pgxc_ddl/pgxc_ddlsetsPGXC_CONF=$DATA_FOLDER/pgxc.confdocs/guide/pgxc_ctl_double.confanddocs/guide/pgxc_ctl_single.confValidation
Documentation only, and this repository's CI does not run on pull requests
(
.github/workflows/ci.ymlison: pushtomain/masteronly). So the deploy pipeline wasreproduced locally with the same two packages it installs —
mkdocs-material(9.7.7) andmkdocs-static-i18n(1.3.1) under mkdocs 1.6.1 — andmkdocs buildwas run twice:git checkout --both files), andResults:
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.pgxc_ctl/pgxc.confreference, the changed build no longer does, and the changed buildcontains the removal commit, the historical revision link and
pgxc_ctl_double.conf. Theadded note renders as a
<blockquote>, with no literal!!!and no unrendered**Note**.characters, and balanced code fences.
git diff --checkis clean andgit ls-files --others --exclude-standardis 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:
!!! note.mkdocs.ymlnestsmarkdown_extensionsinsidethe
theme:block, so theadmonition,tablesandattr_listextensions are not actuallyenabled. Confirmed against the live site: fetching
https://docs.opentenbase.org/contribution/docs-format-guide/ returns HTML containing a
literal
!!!and noclass="admonition", i.e. the existing admonition blocks render as plaintext. Note that fixing that nesting is a separate issue and is deliberately left alone here.
docs/contribution/docs-format-guide.mdasks for relative paths for in-site links, but
pgxc_ctl_double.confis published only forthe Chinese locale —
https://docs.opentenbase.org/guide/pgxc_ctl_double.confreturns 200while
https://docs.opentenbase.org/en/guide/pgxc_ctl_double.confreturns 404 — so arelative 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
psql -h 172.16.200.10 -p 30004targetedopentenbaseDN1, not the CN(
172.16.200.5) in the removed Compose file. Left alone: without the Compose file this cannotbe confirmed against a running cluster.
example/1c_2d_clustershould be restored, or this guide retired in favour of theKubeBlocks 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.