From a7ae487f2cc8b306e8756c7155b59defc4bc05e2 Mon Sep 17 00:00:00 2001 From: Lycorius03 Date: Sat, 19 Sep 2026 17:21:43 +0800 Subject: [PATCH] docs: fix Docker 1C2D example path and pgxc configuration filename 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. --- docs/guide/15-docker-deploy.en.md | 20 +++++++++++++++++++- docs/guide/15-docker-deploy.md | 19 ++++++++++++++++++- 2 files changed, 37 insertions(+), 2 deletions(-) diff --git a/docs/guide/15-docker-deploy.en.md b/docs/guide/15-docker-deploy.en.md index 6eaa187..ba63ebc 100644 --- a/docs/guide/15-docker-deploy.en.md +++ b/docs/guide/15-docker-deploy.en.md @@ -12,7 +12,20 @@ cd ${SOURCECODE_PATH}/docker Commands above will build `opentenbasebase` and `opentenbase` images. +Replace `SOURCECODE_PATH` with the path of your local clone of this repository, for example `/data/opentenbase/OpenTenBase`. + ## 2.Start the example service and enter the CN contaioner + +> **Note**: the directory `${SOURCECODE_PATH}/example/1c_2d_cluster` no longer exists on the current `master` branch, so the commands below cannot be run as written. +> Its `docker-compose.yaml`, `README` and `pgxc_conf/` were removed together with the whole `example/` tree, by commit +> [`aca7e2c`](https://github.com/OpenTenBase/OpenTenBase/commit/aca7e2c34a25e1480548a20dc7462612fb8a17f7) ("Update basecode version from 2.6.0 to 5.0.0") in the OpenTenBase repository. +> The only part still present in that repository is the image build path used in step 1 (`docker/buildImage.sh`). +> +> The cluster configuration template used by this example is still published in this repository: +> . +> If you need the removed `docker-compose.yaml`, it can be retrieved from the revision just before the deletion: +> (historical file, no longer maintained). + ```shell cd ${SOURCECODE_PATH}/example/1c_2d_cluster docker-compose up -d @@ -39,12 +52,17 @@ cp ~/pgxc_conf/pgxc_ctl.conf ~/pgxc_ctl Use `pgxc_ctl` for deployment. Avoid using commands like `ls` or `echo` after entering `pgxc_ctl`. ```shell pgxc_ctl # This step will enter --home location, which is by default /home/$USER/pgxc_ctl. Type exit to exit or Ctrl + D -deploy all # This will use pgxc.conf located in /home/$USER/pgxc_ctl/pgxc.conf for deployment +deploy all # This will use /home/$USER/pgxc_ctl/pgxc_ctl.conf for deployment init all exit ``` +The configuration file name read by `pgxc_ctl` is fixed to `pgxc_ctl.conf`, located in the directory given by `--home` +(`$HOME/pgxc_ctl` by default); see `contrib/pgxc_ctl/pgxc_ctl.h` (`DEFAULT_CONF_FILE_NAME`) and +`contrib/pgxc_ctl/pgxc_ctl.c` (`build_configuration_path()`) in the OpenTenBase repository. +The file copied in step 4 therefore **must not be renamed**; `pgxc.conf` is the configuration file of a different, +unrelated tool, `pgxc_ddl`. ## 5.Connect OpenTenbase using psql diff --git a/docs/guide/15-docker-deploy.md b/docs/guide/15-docker-deploy.md index e15534a..9154b94 100644 --- a/docs/guide/15-docker-deploy.md +++ b/docs/guide/15-docker-deploy.md @@ -12,7 +12,20 @@ cd ${SOURCECODE_PATH}/docker 上述指令会构建`opentenbasebase`和 `opentenbase`两个镜像。 +其中 `SOURCECODE_PATH` 请替换为本仓库在本机的克隆路径，例如 `/data/opentenbase/OpenTenBase`。 + ## 2.启动 example 服务，进入 opentenbaseCN 容器 + +> **注意**：`${SOURCECODE_PATH}/example/1c_2d_cluster` 目录在当前 `master` 分支上已不存在，因此下面这段命令目前无法执行。 +> 该目录下的 `docker-compose.yaml`、`README` 和 `pgxc_conf/` 已随整个 `example/` 目录，在 OpenTenBase 仓库的提交 +> [`aca7e2c`](https://github.com/OpenTenBase/OpenTenBase/commit/aca7e2c34a25e1480548a20dc7462612fb8a17f7)（"Update basecode version from 2.6.0 to 5.0.0"）中被移除。 +> 目前仓库里保留的只有第 1 步的镜像构建路径（`docker/buildImage.sh`）。 +> +> 本次示例使用的集群配置模板仍发布在本仓库中： +> 。 +> 如果需要被移除的 `docker-compose.yaml`，可从删除前的历史版本获取： +> （历史文件，已不再维护）。 + ```shell cd ${SOURCECODE_PATH}/example/1c_2d_cluster docker-compose up -d @@ -39,12 +52,16 @@ cp ~/pgxc_conf/pgxc_ctl.conf ~/pgxc_ctl 使用 `pgxc_ctl` 进行部署，使用`pgxc_ctl`之后，不要敲 `ls` ,`echo` 这种命令。 ```shell pgxc_ctl # 这一步会进入 --home 位置，默认是/home/$USER/pgxc_ctl, 使用exit退出，或者ctrl + D -deploy all # 会使用/home/$USER/pgxc_ctl/pgxc.conf 这个配置文件 +deploy all # 会使用 /home/$USER/pgxc_ctl/pgxc_ctl.conf 这个配置文件 init all exit ``` +`pgxc_ctl` 读取的配置文件名固定为 `pgxc_ctl.conf`，位置为 `--home` 指定的目录（默认 `$HOME/pgxc_ctl`）， +可参考 OpenTenBase 仓库中的 `contrib/pgxc_ctl/pgxc_ctl.h`（`DEFAULT_CONF_FILE_NAME`）和 +`contrib/pgxc_ctl/pgxc_ctl.c`（`build_configuration_path()`）。 +因此第 4 步复制过去的文件**无需改名**；`pgxc.conf` 是另一个独立工具 `pgxc_ddl` 的配置文件，请不要与它混淆。 ## 5.使用psql连接OpenTenbase