This is an automated email from the ASF dual-hosted git repository.
djwang pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/cloudberry-site.git
commit 84e83f09a8450349374acda63ff3ab4e28cb9b80
Author: Dianjin Wang <wangdian...@gmail.com>
AuthorDate: Thu Jun 5 14:52:10 2025 +0800
Add new deployment docs for 2.x
---
docs/deployment/download-source-code.md | 10 +-
docs/deployment/index.md | 2 +-
versioned_docs/version-2.x/cbdb-macos-compile.md | 161 -----
.../version-2.x/cbdb-rockylinux8-ubuntu-compile.md | 229 -------
.../version-2.x/cbdb-rockylinux9-compile.md | 675 ---------------------
.../version-2.x/deployment/build-and-install.md | 76 +++
.../deployment/build-based-on-docker.md | 97 +++
versioned_docs/version-2.x/deployment/configure.md | 153 +++++
.../version-2.x/deployment/create-gpadmin-user.md | 89 +++
.../deployment/download-source-code.md | 17 +-
.../version-2.x}/deployment/index.md | 2 +-
.../deployment/install-required-packages.md | 154 +++++
.../version-2.x/deployment/post-installation.md | 75 +++
.../version-2.x/deployment/quick-build.md | 305 ++++++++++
.../version-2.x/deployment/set-demo-cluster.md | 193 ++++++
.../version-2.x/deployment/system-settings.md | 52 ++
versioned_sidebars/version-2.x-sidebars.json | 16 +-
17 files changed, 1217 insertions(+), 1089 deletions(-)
diff --git a/docs/deployment/download-source-code.md
b/docs/deployment/download-source-code.md
index 4e493328e..4acd91b52 100644
--- a/docs/deployment/download-source-code.md
+++ b/docs/deployment/download-source-code.md
@@ -44,12 +44,16 @@ export GNUTLS_CPUID_OVERRIDE=0x1
Alternatively, you can download the source code archive from the [Apache
Cloudberry releases page](https://github.com/apache/cloudberry/releases).
```bash
-tar xvzf cloudberry-<version>.tar.gz
-cd cloudberry-<version>
+tar xvzf apache-cloudberry-<version>-incubating.tar.gz
+cd apache-cloudberry-<version>-incubating
```
:::note
-You cannot use `git submodule update --init --recursive` to initialize
submodules for building with PAX support when you download the source code
archive. After unarchiving the source code archive, you need to download the
submodules manually at the root directory of the source code:
+The submodules are already included in the latest release source code archive,
so you don't need to download the submodules manually after extracting the
archive.
+:::
+
+:::caution
+If you download the [main branch source code
archive](https://github.com/apache/cloudberry/archive/refs/heads/main.zip) from
the GitHub, there is no submodules included in the archive. Also, you cannot
use `git submodule update --init --recursive` to initialize submodules for
building with PAX support in this case. After unarchiving the main branch
source code archive, you need to download the submodules manually at the root
directory of the source code:
```bash
git clone https://github.com/google/googletest.git
contrib/pax_storage/src/cpp/contrib/googletest
diff --git a/docs/deployment/index.md b/docs/deployment/index.md
index f64c8e65d..fe9b932ee 100644
--- a/docs/deployment/index.md
+++ b/docs/deployment/index.md
@@ -35,7 +35,7 @@ For those new to Cloudberry or PostgreSQL, we recommend
starting with a PostgreS
## Prerequisites
-### Provision a Rocky Linux 8+ / Ubuntu 22.04+ VM
+### Provision a Rocky Linux 8+ / Ubuntu 22.04+ Environment
- Use any platform to create a virtual machine or container:
diff --git a/versioned_docs/version-2.x/cbdb-macos-compile.md
b/versioned_docs/version-2.x/cbdb-macos-compile.md
deleted file mode 100644
index 9ec77e44f..000000000
--- a/versioned_docs/version-2.x/cbdb-macos-compile.md
+++ /dev/null
@@ -1,161 +0,0 @@
----
-title: On macOS
----
-
-# Compile and Install Apache Cloudberry on macOS
-
-:::info
-The source of this document is from the GitHub repository
[`apache/cloudberry`](https://github.com/apache/cloudberry/blob/main/deploy/build/README.macOS.md).
-:::
-
-This document shares how to build, compile, and install Apache Cloudberry on
macOS (single node) for development and trial purposes. Follow the steps below.
-
-According to our test, these steps work well on macOS Ventura 13.4+ with both
Intel and Apple silicon processors (M1 or M2). If you have an older version of
macOS, upgrading is recommended. Make sure that the Mac you use has at least 4
cores and 8 GB memory, and is connected to the Internet.
-
-:::caution
-DO NOT use this guide for production deployment.
-:::
-
-## Step 1. Install needed dependencies
-
-1. Clone the source code of Apache Cloudberry from GitHub to your local Mac.
-
- ```bash
- git clone g...@github.com:apache/cloudberry.git
- ```
-
-2. Enter the `cloudberry/` directory.
-
- ```bash
- cd cloudberry/
- ```
-
-3. Run the following command to install the needed dependencies. You will be
asked to enter the `sudo` password of your macOS system.
-
- ```bash
- source deploy/build/README.macOS.bash
- ```
-
- :::info
- This will install [Homebrew](https://brew.sh/) if missing.
- :::
-
-## Step 2. Enable password-free SSH connection to localhost
-
-1. Enable **Remote Login** on your macOS system by navigating to **System
Preferences** \> **General** \> **Sharing** \> **Remote Login**.
-2. Run the following command to verify whether password-free SSH connection to
localhost has been enabled on your operating system.
-
- ```bash
- ssh $(hostname)
- ```
-
- - If this command runs without error or requiring you to enter a password,
run `exit` and go to [Step 3. Configure, compile, and
install](#step-3-configure-compile-and-install).
- - If you are required to enter a password, take the following steps to set
up password-free SSH connection.
-
- 1. Run `ssh-keygen` and then `cat ~/.ssh/id_rsa.pub >>
~/.ssh/authorized_keys`.
- 2. Run `ssh $(hostname)` again to check whether password-free
connection is ready.
- 3. If ready, run `exit` and go to [Step 3. Configure, compile, and
install](#step-3-configure-compile-and-install).
-
-:::info
-
-- If it is the first time you are using `ssh` connection to localhost, you
might need to accept the trust on the first use prompt:
-
- ```bash
- The authenticity of host '<your hostname>' can't be established.
- ECDSA key fingerprint is SHA256:<fingerprint here>.
- Are you sure you want to continue connecting (yes/no)?
- ```
-
-- If your hostname does not resolve, try adding your machine name to
`/etc/hosts`:
-
- ```bash
- echo -e "127.0.0.1\t$HOSTNAME" | sudo tee -a /etc/hosts
- ```
-
-:::
-
-## Step 3. Configure, compile, and install
-
-```bash
-# Run the following commands under the `cloudberry/` dir.
-# 1. Configure the build environment.
-
-BREWPREFIX=$(brew --prefix); export
PATH="$BREWPREFIX/opt/gnu-sed/libexec/gnubin:$BREWPREFIX/opt/apr/bin:$PATH";
CXXFLAGS="-I $BREWPREFIX/include" CFLAGS="-ggdb -Og -g3 -fno-omit-frame-pointer
-I $BREWPREFIX/include" LDFLAGS="-L $BREWPREFIX/lib" CC=$(which gcc-13)
CXX=$(which g++-13) ./configure --enable-debug --prefix=$(cd ~;
pwd)/install/cbdb;
-
-# 2. Compile and install Apache Cloudberry.
-
-make -j8
-make -j8 install
-
-# 3. Bring in Greenplum environment for Apache Cloudberry into your running
shell.
-
-source $(cd ~; pwd)/install/cbdb/greenplum_path.sh
-
-# 4. Install the Python dependencies.
-
-pip3 install --user -r python-dependencies.txt
-
-# 5. Start a demo cluster.
-
-PORT_BASE=8000 make create-demo-cluster
-```
-
-Prepare the test by running the following command. This command will configure
the port and environment variables for the test. Environment variables such as
`PGPORT` and `COORDINATOR_DATA_DIRECTORY` will be configured, which are the
default port and the data directory of the coordinator node.
-
-```bash
-source gpAux/gpdemo/gpdemo-env.sh
-```
-
-## Step 4. Verify the cluster
-
-1. You can verify whether the cluster has started successfully by running the
following command. If successful, you will see many active `postgres` processes
with ports ranging from `8000` to `8007`.
-
- ```bash
- ps -ef | grep postgres
- ```
-
-2. Connect to the Apache Cloudberry and see the active segment information by
querying the system table `gp_segement_configuration`. For detailed description
of this table, see the Greenplum document
[here](https://docs.vmware.com/en/VMware-Greenplum/7/greenplum-database/ref_guide-system_catalogs-gp_segment_configuration.html).
-
- ```sql
- $ psql -p 8000 postgres
- postgres=# select version();
- postgres=# select * from gp_segment_configuration;
- ```
-
- Example output:
-
- ```shell
- $ psql -p 8000 postgres
- psql (14.4, server 14.4)
- Type "help" for help.
-
- postgres=# select version();
-
version
-
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
- PostgreSQL 14.4 (Apache Cloudberry 1.0.0+1c0d6e2224 build dev) on
x86_64-apple-darwin22.4.0, compiled by gcc-13 (Homebrew GCC 13.2.0) 13.2.0,
64-bit compiled on Sep 22 2023 10:56:01
- (1 row)
-
- postgres=# select * from gp_segment_configuration;
- dbid | content | role | preferred_role | mode | status | port |
hostname | address |
datadir |
warehouseid
-
------+---------+------+----------------+------+--------+------+-----------------------------+-----------------------------+----------------------------------------------------------------------------------------------------------+-------------
- 1 | -1 | p | p | n | u | 8000 |
cbdb.local | cbdb.local |
/Users/cbdb/Documents/GitHub/upstream/cloudberry/gpAux/gpdemo/datadirs/qddir/demoDataDir-1
| 0
- 8 | -1 | m | m | s | u | 8001 |
cbdb.local | cbdb.local |
/Users/cbdb/Documents/GitHub/upstream/cloudberry/gpAux/gpdemo/datadirs/standby
| 0
- 3 | 1 | p | p | s | u | 8003 |
cbdb.local | cbdb.local |
/Users/cbdb/Documents/GitHub/upstream/cloudberry/gpAux/gpdemo/datadirs/dbfast2/demoDataDir1
| 0
- 6 | 1 | m | m | s | u | 8006 |
cbdb.local | cbdb.local |
/Users/cbdb/Documents/GitHub/upstream/cloudberry/gpAux/gpdemo/datadirs/dbfast_mirror2/demoDataDir1
| 0
- 2 | 0 | p | p | s | u | 8002 |
cbdb.local | cbdb.local |
/Users/cbdb/Documents/GitHub/upstream/cloudberry/gpAux/gpdemo/datadirs/dbfast1/demoDataDir0
| 0
- 5 | 0 | m | m | s | u | 8005 |
cbdb.local | cbdb.local |
/Users/cbdb/Documents/GitHub/upstream/cloudberry/gpAux/gpdemo/datadirs/dbfast_mirror1/demoDataDir0
| 0
- 4 | 2 | p | p | s | u | 8004 |
cbdb.local | cbdb.local |
/Users/cbdb/Documents/GitHub/upstream/cloudberry/gpAux/gpdemo/datadirs/dbfast3/demoDataDir2
| 0
- 7 | 2 | m | m | s | u | 8007 |
cbdb.local | cbdb.local |
/Users/cbdb/Documents/GitHub/upstream/cloudberry/gpAux/gpdemo/datadirs/dbfast_mirror3/demoDataDir2
| 0
- (8 rows)
-
- postgres=#
- ```
-
-3. Now you can run `installcheck-world` to start the cluster:
-
- ```bash
- # In the folder where your cloned the source code
- make installcheck-world
- ```
-
-Congratulations 🎉! You've successfully installed and created a cloudberry
cluster. Happy Hacking! 😉
diff --git a/versioned_docs/version-2.x/cbdb-rockylinux8-ubuntu-compile.md
b/versioned_docs/version-2.x/cbdb-rockylinux8-ubuntu-compile.md
deleted file mode 100644
index 387fed943..000000000
--- a/versioned_docs/version-2.x/cbdb-rockylinux8-ubuntu-compile.md
+++ /dev/null
@@ -1,229 +0,0 @@
----
-title: On Rocky Linux 8 and Ubuntu
----
-
-import Tabs from '@theme/Tabs';
-import TabItem from '@theme/TabItem';
-
-# Compile and Install Apache Cloudberry on Rocky Linux 8 and Ubuntu
-
-:::info
-The source of this document is from the GitHub repository
[`apache/cloudberry`](https://github.com/apache/cloudberry/blob/main/deploy/build/README.Linux.md).
-:::
-
-This document shares how to compile and install Apache Cloudberry on Rocky
Linux 8, RHEL 8, and Ubuntu. Note that this document is for developers to try
out Apache Cloudberry in a single-node environments. **DO NOT use this document
for production environments**.
-
-To learn how to compile and install Apache Cloudberry on Rocky Linux 9, see
[Compile on Rocky Linux 9](/docs/cbdb-rockylinux9-compile.md).
-
-Take the following steps to compile and install Apache Cloudberry:
-
-1. [Clone GitHub repo](#step-1-clone-github-repo).
-2. [Install dependencies](#step-2-install-dependencies).
-3. [Perform prerequisite platform
tasks](#step-3-perform-prerequisite-platform-tasks).
-4. [Build Apache Cloudberry](#step-4-build-apache-cloudberry).
-5. [Verify the cluster](#step-5-verify-the-cluster).
-
-## Step 1. Clone GitHub repo
-
-Clone the GitHub repository `apache/cloudberry` to the target machine:
-
-```shell
-git clone https://github.com/apache/cloudberry.git
-```
-
-## Step 2. Install dependencies
-
-Enter the repository and install dependencies according to your operating
systems:
-
-<Tabs>
-<TabItem value="rockey-rhel-8" label="For RHEL 8 and Rocky Linux 8" default>
-
-1. Install Development Tools.
-
- ```bash
- sudo yum group install -y "Development Tools"
- ```
-
-2. Install dependencies:
-
- ```bash
- sudo yum install -y epel-release
-
- sudo yum install -y apr-devel bison bzip2-devel cmake3 flex gcc gcc-c++
krb5-devel libcurl-devel libevent-devel libkadm5 libxml2-devel libzstd-devel
openssl-devel perl-ExtUtils-Embed python3-devel python3-pip readline-devel
xerces-c-devel zlib-devel
- ```
-
-3. Install more dependencies by running the `README.Rhel-Rocky.bash` script.
-
- ```bash
- cd ~/cloudberry/deploy/build/
- ./README.Rhel-Rocky.bash
- ```
-
-</TabItem>
-<TabItem value="ubuntu-18.04" label="For Ubuntu 18.04 or later" default>
-
-1. Install dependencies by running the `README.Ubuntu.bash` script in the
`deploy/build` directory.
-
- ```shell
- ## You need to enter your password to run.
- sudo ~/cloudberry/deploy/build/README.Ubuntu.bash
- ```
-
- :::info
- - When you run the `README.Ubuntu.bash` script for dependencies, you will
be asked to configure `realm` for Kerberos. You can enter any realm, because
this is just for testing, and during testing, it will reconfigure a local
server/client. If you want to skip this manual configuration, run `export
DEBIAN_FRONTEND=noninteractive`.
- - If the script fails to download packages, we recommend that you can try
another one software source for Ubuntu.
- :::
-
-2. Install GCC 10. Ubuntu 18.04 and later versions should use GCC 10 or newer:
-
- ```bash
- ## Install gcc-10
- sudo apt install software-properties-common
- sudo add-apt-repository ppa:ubuntu-toolchain-r/test
- sudo apt install gcc-10 g++-10
- sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-10 100
- ```
-
-</TabItem>
-</Tabs>
-
-## Step 3. Perform prerequisite platform tasks
-
-After you have installed all the dependencies for your operating system, it is
time to do some prerequisite platform tasks before you go on building Apache
Cloudberry. These operation include manually running `ldconfig` on all
platforms, creating the `gpadmin` user, and setting up a password to start the
Apache Cloudberry and test.
-
-1. Make sure that you add `/usr/local/lib` and `/usr/local/lib64` to the
`/etc/ld.so.conf` file.
-
- ```bash
- echo -e "/usr/local/lib \n/usr/local/lib64" >> /etc/ld.so.conf
- ldconfig
- ```
-
-2. Create the `gpadmin` user and set up the SSH key. Manually create SSH keys
based on different operating systems, so that you can run `ssh localhost`
without a password.
-
- <Tabs>
- <TabItem value="rhel-rockey" label="For Rocky Linux 8 and RHEL 8" default>
-
- ```bash
- useradd gpadmin # Creates gpadmin user
- su - gpadmin # Uses the gpadmin user
- ssh-keygen # Creates SSH key
- cat ~/.ssh/id_rsa.pub >> ~/.ssh/authorized_keys
- chmod 600 ~/.ssh/authorized_keys
- exit
- ```
-
- </TabItem>
- <TabItem value="ubuntu" label="For Ubuntu" default>
-
- ```bash
- useradd -r -m -s /bin/bash gpadmin # Creates gpadmin user
- su - gpadmin # Uses the gpadmin user
- ssh-keygen # Creates SSH key
- cat ~/.ssh/id_rsa.pub >> ~/.ssh/authorized_keys
- chmod 600 ~/.ssh/authorized_keys
- exit
- ```
-
- </TabItem>
- </Tabs>
-
-## Step 4. Build Apache Cloudberry
-
-After you have installed all the dependencies and performed the prerequisite
platform tasks, you can start to build Apache Cloudberry. Run the following
commands in sequence.
-
-1. Configure the build environment. Enter the `cloudberry` directory and run
the `configure` script.
-
- ```bash
- cd ../..
- ./configure --with-perl --with-python --with-libxml --with-gssapi
--prefix=/usr/local/cloudberrydb
- ```
-
- :::info
- Apache Cloudberry is built with GPORCA by default. If you want to build
CBDB without GPORCA, add the `--disable-orca` flag in the `./configure` command.
-
- ```bash
- ./configure --disable-orca --with-perl --with-python --with-libxml
--prefix=/usr/local/cloudberry
- ```
-
- :::
-
-2. Compile the code and install the database.
-
- ```bash
- make -j8
- make -j8 install
- ```
-
-3. Bring in the Greenplum environment variables for your running shell.
-
- ```bash
- cd ..
- cp -r cloudberry/ /home/gpadmin/
- cd /home/gpadmin/
- chown -R gpadmin:gpadmin cloudberry/
- su - gpadmin
- cd cloudberry/
- source /usr/local/cloudberry/greenplum_path.sh
- ```
-
-4. Start the demo cluster.
-
- <Tabs>
- <TabItem value="ubuntu-rocky-rhel" label="For Ubuntu, Rocky Linux 8, and
RHEL 8" default>
-
- ```bash
- make create-demo-cluster
- ```
-
- </TabItem>
- </Tabs>
-
-5. Prepare the test by running the following command. This command will
configure the port and environment variables for the test.
-
- Environment variables such as `PGPORT` and `COORDINATOR_DATA_DIRECTORY`
will be configured, which are the default port and the data directory of the
coordinator node.
-
- ```bash
- source gpAux/gpdemo/gpdemo-env.sh
- ```
-
-## Step 5. Verify the cluster
-
-1. You can verify whether the cluster has started successfully by running the
following command. If successful, you might see multiple active `postgres`
processes with ports ranging from `7000` to `7007`.
-
- ```bash
- ps -ef | grep postgres
- ```
-
-2. Connect to the Apache Cloudberry and see the active segment information by
querying the system table `gp_segement_configuration`. For detailed description
of this table, see the Greenplum document
[here](https://docs.vmware.com/en/VMware-Greenplum/6/greenplum-database/ref_guide-system_catalogs-gp_segment_configuration.html).
-
- ```sql
- psql -p 7000 postgres
- psql (14.4, server 14.4)
- Type "help" for help.
- ```
-
- ```sql
- SELECT VERSION();
- version
-
-------------------------------------------------------------------------------------
- PostgreSQL 14.4 (Apache Cloudberry 1.6.0+dev.1383.g5cdbab19af build dev)
on x86_64-pc-li
- nux-gnu, compiled by gcc (GCC) 8.5.0 20210514 (Red Hat 8.5.0-23), 64-bit
compiled on Feb
- 26 2025 18:20:10
- (1 row)
- ```
-
- ```sql
- SELECT * FROM gp_segment_configuration;
-
- dbid | content | role | preferred_role | mode | status | port | hostname
| address | datadir
| warehouseid
-
------+---------+------+----------------+------+--------+------+------------+------------+------------------------------------------------------------------------------+-------------
- 1 | -1 | p | p | n | u | 7000 |
i-6wvpa9wt | i-6wvpa9wt |
/home/gpadmin/cloudberry/gpAux/gpdemo/datadirs/qddir/demoDataDir-1 |
0
- 8 | -1 | m | m | s | u | 7001 |
i-6wvpa9wt | i-6wvpa9wt |
/home/gpadmin/cloudberry/gpAux/gpdemo/datadirs/standby |
0
- 3 | 1 | p | p | s | u | 7003 |
i-6wvpa9wt | i-6wvpa9wt |
/home/gpadmin/cloudberry/gpAux/gpdemo/datadirs/dbfast2/demoDataDir1 |
0
- 6 | 1 | m | m | s | u | 7006 |
i-6wvpa9wt | i-6wvpa9wt |
/home/gpadmin/cloudberry/gpAux/gpdemo/datadirs/dbfast_mirror2/demoDataDir1 |
0
- 2 | 0 | p | p | s | u | 7002 |
i-6wvpa9wt | i-6wvpa9wt |
/home/gpadmin/cloudberry/gpAux/gpdemo/datadirs/dbfast1/demoDataDir0 |
0
- 5 | 0 | m | m | s | u | 7005 |
i-6wvpa9wt | i-6wvpa9wt |
/home/gpadmin/cloudberry/gpAux/gpdemo/datadirs/dbfast_mirror1/demoDataDir0 |
0
- 4 | 2 | p | p | s | u | 7004 |
i-6wvpa9wt | i-6wvpa9wt |
/home/gpadmin/cloudberry/gpAux/gpdemo/datadirs/dbfast3/demoDataDir2 |
0
- 7 | 2 | m | m | s | u | 7007 |
i-6wvpa9wt | i-6wvpa9wt |
/home/gpadmin/cloudberry/gpAux/gpdemo/datadirs/dbfast_mirror3/demoDataDir2 |
0
- (8 rows)
- ```
diff --git a/versioned_docs/version-2.x/cbdb-rockylinux9-compile.md
b/versioned_docs/version-2.x/cbdb-rockylinux9-compile.md
deleted file mode 100644
index 63e02253f..000000000
--- a/versioned_docs/version-2.x/cbdb-rockylinux9-compile.md
+++ /dev/null
@@ -1,675 +0,0 @@
----
-title: On Rocky Linux 9
----
-
-# Compile and Install Apache Cloudberry on Rocky Linux 9
-
-:::info
-The source of this document is from [Building Apache Cloudberry (Incubating):
A Development Environment
Guide](https://github.com/edespino/cloudberry/blob/rocky9-dev-readme/deploy/build/README-rockylinux9.md).
-:::
-
-This document is intended for developers interested in exploring and
potentially contributing to Apache Cloudberry. The build environment described
here is optimized for development and testing purposes only.
-
-To learn how to compile and install Apache Cloudberry on Rocky Linux 8 and
Ubuntu, see [Compile on Rocky Linux 8 and
Ubuntu](/docs/cbdb-rockylinux8-ubuntu-compile.md).
-
-## 1. Target audience
-
-- Developers interested in contributing to Apache Cloudberry.
-- PostgreSQL developers wanting to explore Cloudberry's extensions.
-- Database enthusiasts interested in learning about distributed query
processing.
-- Anyone considering joining the Apache Cloudberry community.
-
-The build process described here enables development activities such as:
-
-- Debugging and testing new features.
-- Exploring the codebase with development tools.
-- Running test suites and validation checks.
-- Making and testing code modifications.
-
-:::tip
-If you are new to Apache Cloudberry or PostgreSQL development:
-
-- Consider building PostgreSQL first to understand the basic workflow
-- Join the project's mailing lists to connect with other developers
-- Review the project's issue tracker to understand current development
priorities
-- Be prepared for longer build times and iterative testing as you explore the
codebase
-:::
-
-## 2. Process of building Apache Cloudberry
-
-The build process for Apache Cloudberry (Incubating) closely resembles that of
PostgreSQL. If you have previously set up development environments for
PostgreSQL, you'll find the steps for Cloudberry very familiar.
-
-For those new to Cloudberry or PostgreSQL, I recommend starting with a
PostgreSQL build first. The PostgreSQL development community has established
excellent documentation and tooling to guide you through the process.
Familiarizing yourself with PostgreSQL's build process will make transitioning
to Cloudberry significantly easier.
-
-## 3. Key differences between Cloudberry and PostgreSQL
-
-While the overall process is similar, there are a few additional
considerations when working with Cloudberry due to its distributed architecture:
-
-- **Extra Dependencies**: Certain libraries and tools are required, such as
`xerces-c` for the Orca query optimizer.
-- **Distributed Nature**: Cloudberry builds on PostgreSQL to support massively
parallel processing, which introduces extra configuration steps.
-
-Once you are familiar with PostgreSQL, setting up Cloudberry will be
straightforward. The following sections will guide you through the build and
runtime setup process for Cloudberry.
-
-## 4. Prerequisites
-
-### 4.1 Provision a Rocky Linux 9 VM
-
-- Use any platform to create a virtual machine or container:
-
- - **AWS EC2**: These instructions were validated using the
Rocky-9-EC2-Base-9.5-20241118.0.x86_64 AMI, but should work with any Rocky
Linux 9 variant.
- - **VirtualBox**: Use the official Rocky Linux 9 ISO or Vagrant boxes.
- - **Docker**: These instructions were validated using
`rockylinux/rockylinux:9`, but should work with any Rocky Linux 9 based
container.
-
- ```bash
- docker run -it --shm-size=2gb -h cdw rockylinux/rockylinux:9
- ```
-
- The hostname 'cdw' (Coordinator Data Warehouse) is just an example of
how we started the container for testing.
-
- To ensure test suites run successfully, you may need to increase the
container's shared memory using `--shm-size=2gb`. Test failures can occur when
the Cloudberry cluster lacks sufficient shared memory resources.
-
- - **Other cloud platforms**: Use an equivalent Rocky Linux 9 image.
-
-- Ensure the VM or container has:
- - Internet connectivity for package installation.
- - SSH or console access for user interaction.
- - Sufficient resources (CPU, memory, and storage) for a development
environment.
-
-:::note
-Specific steps to provision the environment are not covered in this guide
because they vary by platforms. This guide assumes you have successfully
created a VM or container and can log in as the default user (for example,
`rocky` for Rocky Linux on AWS).
-:::
-
-### 4.2 System requirements
-
-Minimum requirements for development environment:
-
-- CPU: 4 cores recommended (2 cores minimum)
-- RAM: 8GB recommended (4GB minimum)
-- Storage: 20GB free space recommended
-- Network: Broadband internet connection for package downloads
-
-### 4.3 Install `sudo` (if missing)
-
-If `sudo` is not already installed, run the following command to install it:
-
-```bash
-dnf install -y sudo
-```
-
-:::note
-In environments like Docker, the `root` user will be able to use `sudo`
without a password prompt once it is installed.
-:::
-
-### 4.4 Install required packages
-
-This step installs essential development tools, libraries, and dependencies
required for building Apache Cloudberry.
-
-#### 4.4.1 Install basic system packages
-
-The following command installs the primary packages required for Cloudberry
development:
-
-```bash
-sudo dnf install -y apr-devel autoconf bison bzip2 bzip2-devel cmake3
createrepo_c ed flex gcc gcc-c++ git glibc-langpack-en initscripts iproute
java-11-openjdk java-11-openjdk-devel krb5-devel less libcurl-devel
libevent-devel libuuid-devel libxml2-devel libzstd-devel lz4 lz4-devel m4 nc
net-tools openldap-devel openssh-clients openssh-server openssl-devel pam-devel
passwd perl perl-Env perl-ExtUtils-Embed perl-Test-Simple perl-core pinentry
python3-devel python3-lxml python3-psutil pyt [...]
-```
-
-#### 4.4.2 Install CodeReady Builder (CRB) packages
-
-The CRB repository provides additional development tools and libraries. On
Rocky Linux, this repository is disabled by default and must be explicitly
enabled.
-
-```bash
-sudo dnf install -y --enablerepo=crb libuv-devel libyaml-devel perl-IPC-Run
-```
-
-:::note
-In Red Hat Enterprise Linux (RHEL), this repository is called "PowerTools."
-:::
-
-### 4.5 Create and configure the 'gpadmin' user
-
-To prepare the environment for Apache Cloudberry (Incubating) development, we
need to create and configure a dedicated `gpadmin` user.
-
-1. Create a user 'gpadmin' with matching group, home directory, and bash shell:
-
- ```bash
- sudo useradd -U -m -s /bin/bash gpadmin
- ```
-
-2. Grant password-less sudo access to `gpadmin`:
-
- ```bash
- echo 'gpadmin ALL=(ALL) NOPASSWD:ALL' | sudo tee /etc/sudoers.d/90-gpadmin
- ```
-
-3. Verify the `gpadmin` user setup:
-
- ```bash
- sudo -u gpadmin sudo whoami
- ```
-
- If the output is `root`, the configuration is correct.
-
-#### 4.5.1 Set up the gpadmin user environment
-
-Optional steps to enhance gpadmin's development environment with Vim, Tmux,
and Oh My Bash configurations
-
-```bash
-sudo dnf install -y vim tmux
-
-sudo -u gpadmin bash <<'EOF'
-# Set up Vim configuration
-wget -nv -q
https://gist.githubusercontent.com/simonista/8703722/raw/d08f2b4dc10452b97d3ca15386e9eed457a53c61/.vimrc
-O /home/gpadmin/.vimrc
-
-# Set up Tmux configuration
-wget -nv -q
https://raw.githubusercontent.com/tony/tmux-config/master/.tmux.conf -O
/home/gpadmin/.tmux.conf
-
-# Install Oh My Bash
-bash -c "$(curl -fsSL
https://raw.githubusercontent.com/ohmybash/oh-my-bash/master/tools/install.sh)"
--unattended
-EOF
-```
-
-#### 4.5.2 Required configuration
-
-This script performs three main tasks as the `gpadmin` user:
-
-- Updates .bashrc to source Cloudberry environment variables
-- Sets up SSH key pair for passwordless login (if not already present)
-- Configures proper SSH directory permissions for security
-
-The script uses a heredoc (EOF) block to execute multiple commands under the
`gpadmin` user context. This will be used multiple time throughout these
instructions.
-
-```bash
-sudo -u gpadmin bash <<'EOF'
-# Add Cloudberry environment setup to .bashrc
-echo -e '\n# Add Cloudberry entries
-if [ -f /usr/local/cloudberry-db/greenplum_path.sh ]; then
- source /usr/local/cloudberry-db/greenplum_path.sh
-fi
-
-# US English with UTF-8 character encoding
-export LANG=en_US.UTF-8
-' >> /home/gpadmin/.bashrc
-
-# Set up SSH for passwordless access
-mkdir -p /home/gpadmin/.ssh
-if [ ! -f /home/gpadmin/.ssh/id_rsa ]; then
- ssh-keygen -t rsa -b 2048 -C 'apache-cloudberry-dev' -f
/home/gpadmin/.ssh/id_rsa -N ""
-fi
-cat /home/gpadmin/.ssh/id_rsa.pub >> /home/gpadmin/.ssh/authorized_keys
-
-# Set proper SSH directory permissions
-chmod 700 /home/gpadmin/.ssh
-chmod 600 /home/gpadmin/.ssh/authorized_keys
-chmod 644 /home/gpadmin/.ssh/id_rsa.pub
-EOF
-```
-
-### 4.6 Configure system settings
-
-Database systems like Apache Cloudberry require specific system resource
limits to operate efficiently. These limits should be configured for the
`gpadmin` user who runs the database processes.
-
-1. Create resource limits configuration
-
- Create user limits configuration file:
-
- ```bash
- sudo tee /etc/security/limits.d/90-db-limits.conf << 'EOF'
- # Core dump file size limits for gpadmin
- gpadmin soft core unlimited
- gpadmin hard core unlimited
- # Open file limits for gpadmin
- gpadmin soft nofile 524288
- gpadmin hard nofile 524288
- # Process limits for gpadmin
- gpadmin soft nproc 131072
- gpadmin hard nproc 131072
- EOF
- ```
-
-2. Understand the limits.
-
- The configuration sets the following types of resource limits:
-
- - **Core Dumps** (`core`):
-
- - Set to `unlimited` to enable complete core dumps
- - Essential for debugging and troubleshooting
- - Both soft and hard limits are unrestricted
-
- - **Open Files** (`nofile`):
-
- - Set to `524288` (512K) files
- - Required for handling many concurrent database connections
- - Critical for distributed operations and large workloads
-
- - **Process Limits** (`nproc`):
-
- - Set to `131072` (128K) processes
- - Enables parallel query execution
- - Supports Cloudberry's distributed architecture
-
-3. Verify resource limits.
-
- ```bash
- # Check current limits
- sudo -u gpadmin ulimit -a
- ```
-
-## 5. Retrieve and compile software
-
-From here on out we execute commands as the `gpadmin` user
-
-```bash
-sudo su - gpadmin
-```
-
-### 5.1 Download, build, and install Apache Xerces-C
-
-Apache Xerces-C is a required dependency for enabling the Orca query optimizer
in Cloudberry. The following steps download the source code, verify its
integrity, build the library, and install it.
-
-#### 5.1.1 Set variables (helper)
-
-To streamline the commands and make them reusable, define the following helper
variables:
-
-```bash
-XERCES_LATEST_RELEASE=3.3.0
-XERCES_INSTALL_PREFIX="/usr/local/xerces-c"
-```
-:::note
-These variables are used throughout the build process to specify the version
of Apache Xerces-C being installed (XERCES_LATEST_RELEASE) and its installation
directory (XERCES_INSTALL_PREFIX). This ensures consistency and simplifies the
commands.
-:::
-
-#### 5.1.2 Download and verify the source package
-
-```bash
-wget -nv
"https://dlcdn.apache.org//xerces/c/3/sources/xerces-c-${XERCES_LATEST_RELEASE}.tar.gz";
-echo "$(curl -sL
https://dlcdn.apache.org//xerces/c/3/sources/xerces-c-${XERCES_LATEST_RELEASE}.tar.gz.sha256)"
| sha256sum -c -
-```
-
-:::note
-Ensure the SHA-256 checksum validation passes (output: `xerces-c-3.3.0.tar.gz:
OK`). If it fails, do not proceed and verify the source package's integrity.
-:::
-
-#### 5.1.3 Extract, configure, build, test, and install
-
-```bash
-tar xf "xerces-c-${XERCES_LATEST_RELEASE}.tar.gz"
-rm "xerces-c-${XERCES_LATEST_RELEASE}.tar.gz"
-cd xerces-c-${XERCES_LATEST_RELEASE}
-
-./configure --prefix="${XERCES_INSTALL_PREFIX}-${XERCES_LATEST_RELEASE}" | tee
configure-$(date "+%Y.%m.%d-%H.%M.%S").log
-make -j$(nproc) | tee make-$(date "+%Y.%m.%d-%H.%M.%S").log
-make check | tee make-check-$(date "+%Y.%m.%d-%H.%M.%S").log
-sudo make install | tee make-install-$(date "+%Y.%m.%d-%H.%M.%S").log
-sudo ln -s ${XERCES_INSTALL_PREFIX}-${XERCES_LATEST_RELEASE}
${XERCES_INSTALL_PREFIX}
-```
-
-:::note
-- The `make` command is run in parallel (`-j$(nproc)`) to leverage all
available CPU cores for faster builds. The `nproc` command dynamically
retrieves the number of cores.
-- During `make check`, failures listed as **XFAIL** (expected failures) are
acceptable and do not indicate a problem with the build.
-- The output of the commands are saved to timestamped log files for future
reference or troubleshooting.
-:::
-
-### 5.2 Clone the Apache Cloudberry repository
-
-Clone the source code for Apache Cloudberry into the `gpadmin` user's home
directory:
-
-```bash
-git clone https://github.com/apache/cloudberry.git ~/cloudberry
-cd ~/cloudberry
-```
-
-### 5.3 Configure the build process
-
-#### 5.3.1 Prepare environment
-
-The build process requires the necessary libraries (e.g., Xerces-C) to be
available at the expected locations for configuration and runtime. Prepare the
environment using the following commands:
-
-```bash
-sudo rm -rf /usr/local/cloudberry-db
-sudo chmod a+w /usr/local
-mkdir -p /usr/local/cloudberry-db/lib
-sudo cp -v /usr/local/xerces-c/lib/libxerces-c.so \
- /usr/local/xerces-c/lib/libxerces-c-3.*.so \
- /usr/local/cloudberry-db/lib
-sudo chown -R gpadmin.gpadmin /usr/local/cloudberry-db
-```
-
-#### 5.3.2 Run `configure`
-
-The `configure` command sets up the build environment for Apache Cloudberry.
This configuration includes several development features and extensions.
-
-```bash
-cd ~/cloudberry
-export LD_LIBRARY_PATH=/usr/local/cloudberry-db/lib:LD_LIBRARY_PATH
-./configure --prefix=/usr/local/cloudberry-db \
- --disable-external-fts \
- --enable-debug \
- --enable-cassert \
- --enable-debug-extensions \
- --enable-gpcloud \
- --enable-ic-proxy \
- --enable-mapreduce \
- --enable-orafce \
- --enable-orca \
- --enable-pxf \
- --enable-tap-tests \
- --with-gssapi \
- --with-ldap \
- --with-libxml \
- --with-lz4 \
- --with-openssl \
- --with-pam \
- --with-perl \
- --with-pgport=5432 \
- --with-python \
- --with-pythonsrc-ext \
- --with-ssl=openssl \
- --with-openssl \
- --with-uuid=e2fs \
- --with-includes=/usr/local/xerces-c/include \
- --with-libraries=/usr/local/cloudberry-db/lib | tee
~/cloudberry/configure-$(date "+%Y.%m.%d-%H.%M.%S").log
-```
-
-:::note
-The output of the `configure` command is saved to a timestamped log file for
future reference or troubleshooting.
-:::
-
-### 5.4 Build and install Apache Cloudberry and contrib extensions
-
-#### 5.4.1 Compile the code
-
-```bash
-# Uses the following command to compile the core components of Apache
Cloudberry:
-make -j$(nproc) --directory=~/cloudberry | tee ~/cloudberry/make-$(date
"+%Y.%m.%d-%H.%M.%S").log
-
-# Compiles additional contrib modules, which provide optional features and
extensions:
-make -j$(nproc) --directory=~/cloudberry/contrib | tee
~/cloudberry/make-contrib-$(date "+%Y.%m.%d-%H.%M.%S").log
-```
-
-#### 5.4.2 Install the compiled binaries
-
-```bash
-# Installs the core components to the specified installation directory:
-make install --directory=~/cloudberry | tee ~/cloudberry/make-install-$(date
"+%Y.%m.%d-%H.%M.%S").log
-
-# Installs the contrib modules to the specified installation directory:
-make install --directory=~/cloudberry/contrib | tee
~/cloudberry/make-contrib-install-$(date "+%Y.%m.%d-%H.%M.%S").log
-```
-
-### 5.5 Verify installation
-
-After installation, verify the setup with these steps:
-
-#### 5.5.1 Check Cloudberry version
-
-```bash
-/usr/local/cloudberry-db/bin/postgres --gp-version
-/usr/local/cloudberry-db/bin/postgres --version
-```
-
-#### 5.5.2 Verify library dependencies
-
-```bash
-ldd /usr/local/cloudberry-db/bin/postgres
-```
-
-#### 5.5.3 Check library extensions
-
-```bash
-ls -al /usr/local/cloudberry-db/share/postgresql/extension
-```
-
-#### 5.5.4 Check core utilities
-
-```bash
-ls -l /usr/local/cloudberry-db/bin/
-```
-Expected output should show critical binaries like postgres, initdb, etc.
-
-### 5.6 Common issues
-
-- Configure fails with missing dependencies:
-
- 1. Verify all required packages are installed.
- 2. Check the configure log file for specific errors.
- 3. Ensure CRB repository is properly enabled.
-
-- Build fails with compilation errors:
-
- 1. Check make logs for specific errors.
- 2. Ensure sufficient system resources are available.
- 3. Verify Xerces-C installation is correct.
-
-- Library loading issues:
-
- 1. Verify `LD_LIBRARY_PATH` includes required directories.
- 2. Check library permissions.
-
-For detailed error messages, review the timestamped log files created during
the installation process.
-
-You have successfully built and installed Apache Cloudberry on Rocky Linux 9.
The installation directory is `/usr/local/cloudberry-db`.
-
-## 6. Set up a Cloudberry development cluster
-
-This guide walks through setting up a Cloudberry demo cluster, and testing
basic functionality. The demo cluster includes a coordinator, standby
coordinator, and multiple primary/mirror segments all running on a single
development host.
-
-### 6.1 Set up initial container (not required for all environments)
-
-Container environments typically don't start the SSH daemon process by
default. Since Cloudberry relies heavily on SSH for inter-process
communication, we need to initialize and start the SSH server:
-
-```bash
-if ! pgrep sshd > /dev/null; then
- echo "SSH daemon not running. Starting it now..."
- sudo ssh-keygen -A
- echo "PasswordAuthentication yes" | sudo tee -a /etc/ssh/sshd_config
- sudo /usr/sbin/sshd
-else
- echo "SSH daemon is already running"
-fi
-```
-
-### 6.2 Configure SSH for Cloudberry
-
-Cloudberry uses SSH for coordinator-segment communication. The following
commands ensure SSH is properly configured for the gpadmin user by adding the
host to known_hosts and verifying SSH connectivity:
-
-```bash
-ssh-keyscan $(hostname) >> ~/.ssh/known_hosts
-ssh $(hostname) date
-```
-
-### 6.3 Set up Cloudberry environment variables
-
-Load Cloudberry environment variables that set up paths for binaries,
libraries, and other essential components:
-
-```bash
-source /usr/local/cloudberry-db/greenplum_path.sh
-```
-
-### 6.4 Create development cluster
-
-Create a demo cluster that simulates a full Cloudberry deployment on a single
machine. This includes 1 coordinator, 1 standby coordinator, 3 primary
segments, and 3 mirror segments:
-
-```bash
-make create-demo-cluster --directory=~/cloudberry | tee
~/cloudberry/make-create-demo-cluster-$(date "+%Y.%m.%d-%H.%M.%S").log
-```
-
-### 6.5 Configure cluster environment
-
-After cluster creation, verify and load cluster-specific variables that point
to the coordinator port and data directory:
-
-```bash
-source ~/cloudberry/gpAux/gpdemo/gpdemo-env.sh
-```
-
-### 6.6 Validate cluster deployment
-
-Verify the cluster is running correctly with these essential commands:
-
-```bash
-# Displays detailed cluster state including segment status
-gpstate
-
-# Tests cluster shutdown and startup
-gpstop -a
-gpstart -a
-
-# Confirms Cloudberry version and build
-psql template1 -c 'SELECT version()'
-
-# Views segment configuration showing primary/mirror relationships
-psql template1 -c 'SELECT * from gp_segment_configuration'
-
-# Checks available PostgreSQL extensions
-psql template1 -c 'SELECT * FROM pg_available_extensions'
-```
-
-### 6.7 Extension Testing Example: pg_stat_statements
-
-This example demonstrates how to enable and test the `pg_stat_statements`
extension, which provides statistics about SQL query execution:
-
-```bash
-# Creates a database for testing
-createdb gpadmin
-
-# Enables the extension by adding it to shared libraries
-echo "shared_preload_libraries='pg_stat_statements'" >>
$COORDINATOR_DATA_DIRECTORY/postgresql.conf
-
-# Restarts cluster to load the new library (-r flag means "restart")
-gpstop -ar
-
-# Creates the extension in the database
-psql gpadmin -e -c 'CREATE EXTENSION pg_stat_statements'
-
-# Runs test queries to generate statistics
-psql gpadmin --echo-queries <<EOF
--- Create a sample table
-CREATE TABLE employees (
- id SERIAL PRIMARY KEY,
- name TEXT,
- department TEXT,
- salary NUMERIC
-);
-
--- Insert sample data
-INSERT INTO employees (name, department, salary)
-VALUES
-('Alice', 'HR', 60000),
-('Bob', 'Engineering', 80000),
-('Charlie', 'Marketing', 70000);
-
--- Query the data to generate some statistics
-SELECT * FROM employees WHERE department = 'Engineering';
-SELECT AVG(salary) FROM employees;
-
--- View most frequently called queries
-SELECT query, calls, total_exec_time AS total_time, rows
-FROM pg_stat_statements
-ORDER BY calls DESC
-LIMIT 5;
-
--- View most time-consuming queries
-SELECT query, calls, total_exec_time AS total_time, rows
-FROM pg_stat_statements
-ORDER BY total_exec_time DESC
-LIMIT 5;
-EOF
-```
-
-### 6.8 Destroy development cluster
-
-To clean up and start fresh, you can destroy the demo cluster:
-
-```bash
-make destroy-demo-cluster --directory=~/cloudberry | tee
~/cloudberry/make-create-demo-cluster-$(date "+%Y.%m.%d-%H.%M.%S").log
-```
-
-This command removes all cluster data and configuration, allowing you to
create a new clean cluster if needed.
-
-### 6.9 Troubleshoot SSH connection issues
-
-When running `create-demo-cluster`, the process may hang if SSH host
verification hasn't been completed. This typically manifests as a stalled
process waiting for user input to verify the host identity.
-
-This is why we run:
-
-```bash
-ssh-keyscan $(hostname) >> ~/.ssh/known_hosts
-```
-before creating the cluster. This command automatically adds the host's SSH
keys to the known_hosts file, preventing interactive prompts during cluster
creation.
-
-If you still encounter SSH issues:
-
-1. Verify that the SSH daemon is running
-2. Check that the known_hosts file exists and has the correct permissions
-3. Test SSH connectivity with `ssh $(hostname) date` before proceeding with
cluster creation
-
-## 7. Validate basic functionalities
-
-Run the installcheck test suite to verify basic functionality. It is
recommended to test with both Orca (the query optimizer) enabled and disabled:
-
-```bash
-# Run tests with Orca optimizer enabled
-PGOPTIONS='-c optimizer=on' make --directory=~/cloudberry installcheck
-
-# Run tests with Orca optimizer disabled
-PGOPTIONS='-c optimizer=off' make --directory=~/cloudberry installcheck
-```
-
-:::tip
-Even though Orca is the default Cloudberry optimizer, you must explicitly set
`optimizer=on` when running installcheck. Without this setting, the `explain`
test will fail due to missing the explicit configuration option.
-:::
-
-### 7.1 Test results
-
-The installcheck target provides a basic test of functionality. During
execution, you'll see output like this:
-
-```bash
-test tablespace ... ok 3236 ms (diff 76 ms)
-parallel group (20 tests): pg_lsn oid txid name char varchar int2 regproc
text ...
- boolean ... ok 862 ms (diff 56 ms)
- char ... ok 419 ms (diff 87 ms)
- explain ... FAILED 310 ms (diff 139 ms)
-```
-
-At the end, you'll see a summary, for example:
-
-```
-========================
- 1 of 658 tests failed.
-========================
-```
-
-If any tests fail:
-
-- `regression.diffs`: Shows differences between actual and expected results
-- `regression.out`: Contains the complete test execution output
-
-The files will be located in `/home/gpadmin/cloudberry/src/test/regress/`.
-
-:::note
-installcheck is just one of several test schedules available. This guide
focuses on basic development environment setup and validation.
-:::
-
-### 7.2 Troubleshoot test failures
-
-If a test fails, you might need to examine the log files from various cluster
components. You can locate the data directories containing these logs by
querying the segment configuration:
-
-```bash
-psql -P pager=off template1 -c 'SELECT * from gp_segment_configuration'
-```
-
-This shows the complete cluster configuration. The `content = -1` identifies
coordinator nodes:
-
-```sql
- dbid | content | role | preferred_role | mode | status | port | hostname |
address | datadir
| warehouseid
-------+---------+------+----------------+------+--------+------+----------+---------+----------------------------------------------------------------------------+-------------
- 1 | -1 | p | p | n | u | 7000 | mdw |
mdw | /home/gpadmin/cloudberry/gpAux/gpdemo/datadirs/qddir/demoDataDir-1
| 0
- 8 | -1 | m | m | s | u | 7001 | mdw |
mdw | /home/gpadmin/cloudberry/gpAux/gpdemo/datadirs/standby
| 0
- 2 | 0 | p | p | s | u | 7002 | mdw |
mdw | /home/gpadmin/cloudberry/gpAux/gpdemo/datadirs/dbfast1/demoDataDir0
| 0
- 5 | 0 | m | m | s | u | 7005 | mdw |
mdw |
/home/gpadmin/cloudberry/gpAux/gpdemo/datadirs/dbfast_mirror1/demoDataDir0 |
0
- 3 | 1 | p | p | s | u | 7003 | mdw |
mdw | /home/gpadmin/cloudberry/gpAux/gpdemo/datadirs/dbfast2/demoDataDir1
| 0
- 6 | 1 | m | m | s | u | 7006 | mdw |
mdw |
/home/gpadmin/cloudberry/gpAux/gpdemo/datadirs/dbfast_mirror2/demoDataDir1 |
0
- 4 | 2 | p | p | s | u | 7004 | mdw |
mdw | /home/gpadmin/cloudberry/gpAux/gpdemo/datadirs/dbfast3/demoDataDir2
| 0
- 7 | 2 | m | m | s | u | 7007 | mdw |
mdw |
/home/gpadmin/cloudberry/gpAux/gpdemo/datadirs/dbfast_mirror3/demoDataDir2 |
0
-```
-
-Each `datadir` contains log files that can help diagnose test failures. Review
the logs in the relevant component's directory based on which test failed.
\ No newline at end of file
diff --git a/versioned_docs/version-2.x/deployment/build-and-install.md
b/versioned_docs/version-2.x/deployment/build-and-install.md
new file mode 100644
index 000000000..a397f786c
--- /dev/null
+++ b/versioned_docs/version-2.x/deployment/build-and-install.md
@@ -0,0 +1,76 @@
+---
+title: Build and Install Apache Cloudberry and contrib extensions
+---
+
+## Compile the code
+
+```bash
+# Uses the following command to compile the core components of Apache
Cloudberry:
+make -j$(nproc) --directory=~/cloudberry
+
+# Compiles additional contrib modules, which provide optional features and
extensions:
+make -j$(nproc) --directory=~/cloudberry/contrib
+```
+
+## Install the compiled binaries
+
+```bash
+# Installs the core components to the specified installation directory:
+make install --directory=~/cloudberry
+
+# Installs the contrib modules to the specified installation directory:
+make install --directory=~/cloudberry/contrib
+```
+
+## Verify installation
+
+After installation, verify the setup with these steps:
+
+### 1. Check Cloudberry version
+
+```bash
+/usr/local/cloudberry-db/bin/postgres --gp-version
+/usr/local/cloudberry-db/bin/postgres --version
+```
+
+### 2. Verify library dependencies
+
+```bash
+ldd /usr/local/cloudberry-db/bin/postgres
+```
+
+### 3. Check library extensions
+
+```bash
+ls -al /usr/local/cloudberry-db/share/postgresql/extension
+```
+
+### 4. Check core utilities
+
+```bash
+ls -l /usr/local/cloudberry-db/bin/
+```
+Expected output should show critical binaries like postgres, initdb, etc.
+
+## Common issues
+
+- Configure fails with missing dependencies:
+
+ 1. Verify all required packages are installed.
+ 2. Check the configure log file for specific errors.
+ 3. Ensure CRB repository is properly enabled.
+
+- Build fails with compilation errors:
+
+ 1. Check make logs for specific errors.
+ 2. Ensure sufficient system resources are available.
+ 3. Verify Xerces-C installation is correct.
+
+- Library loading issues:
+
+ 1. Verify `LD_LIBRARY_PATH` includes required directories.
+ 2. Check library permissions.
+
+For detailed error messages, review the timestamped log files created during
the installation process.
+
+You have successfully built and installed Apache Cloudberry on Rocky Linux 9.
The installation directory is `/usr/local/cloudberry-db`.
\ No newline at end of file
diff --git a/versioned_docs/version-2.x/deployment/build-based-on-docker.md
b/versioned_docs/version-2.x/deployment/build-based-on-docker.md
new file mode 100644
index 000000000..7fd8b6b2a
--- /dev/null
+++ b/versioned_docs/version-2.x/deployment/build-based-on-docker.md
@@ -0,0 +1,97 @@
+---
+title: Build with Docker Dev Image
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+This guide provides instructions for building Apache Cloudberry using a
Docker-based development environment. This method is particularly useful for
ensuring a consistent build environment across different systems and for saving
setup time.
+
+## Prerequisites
+
+- Docker: Ensure you have Docker installed on your system. You can download
and install Docker from the official website:
[Docker](https://www.docker.com/get-started).
+- Harddisk space: Ensure you have at least 10 GB of free disk space available
for the Docker image and build artifacts.
+
+## Run the Docker Dev Image
+
+Run the following command to start a Docker container with the Apache
Cloudberry development image:
+
+<Tabs>
+<TabItem value="rocky-linux-8" label="Rocky Linux 8" default>
+```bash
+docker run --name cbdb-dev -it --rm -h cdw --shm-size=2gb
apache/incubator-cloudberry:cbdb-build-rocky8-latest
+```
+</TabItem>
+<TabItem value="rocky-linux-9" label="Rocky Linux 9">
+```bash
+docker run --name cbdb-dev -it --rm -h cdw --shm-size=2gb
apache/incubator-cloudberry:cbdb-build-rocky9-latest
+```
+</TabItem>
+<TabItem value="ubuntu-22" label="Ubuntu 22.04">
+:::note
+The official Docker development image for Apache Cloudberry is still in
development. Coming soon.
+:::
+</TabItem>
+</Tabs>
+
+Explaination:
+- `--name=cbdb-dev` will set the name of the container to `cbdb-dev`. You can
change it to any name you prefer.
+- `-it` will run the container in interactive mode, allowing you to execute
commands inside it.
+- `--rm` will remove the container after you exit it. If you want to keep the
container for further use, you can remove this option.
+- `-h cdw` will set the hostname of the container to `cdw` (Coordinator Data
Warehouse).
+- `--shm-size=2gb` is used to set the container's shared memory for test
suites run successfully. Test failures can occur when the Cloudberry cluster
lacks sufficient shared memory resources, then you may need to increase the
container's shared memory using this option.
+
+This development environment has done the following things for you:
+- Created a user named `gpadmin` with the necessary permissions.
+- Set up the environment variables and paths.
+- Configured the specific system resource limits.
+- Installed the necessary dependencies.
+
+Then you will be inside the Docker container with the Apache Cloudberry
development environment ready to use. Before you go on, you need to make sure
you have login the docker container as the `gpadmin` user like this:
+
+```
+======================================================================
+
+ ++++++++++ ++++++
+ ++++++++++++++ +++++++
+ ++++ +++++ ++++
+ ++++ +++++++++
+ =+==== =============+
+ ======== =====+ =====
+ ==== ==== ==== ====
+ ==== === === ====
+ ==== === === ====
+ ==== === ==-- ===
+ ===== ===== -- ====
+ ===================== ======
+ ============================
+ =-----=
+ ____ _ _ _
+ / ___|| | ___ _ _ __| || |__ ___ _ __ _ __ _ _
+ | | | | / _ \ | | | | / _` || '_ \ / _ \| '__|| '__|| | | |
+ | |___ | || (_) || |_| || (_| || |_) || __/| | | | | |_| |
+ \____||_| \____ \__,_| \__,_||_.__/ \___||_| |_| \__, |
+ |___/
+----------------------------------------------------------------------
+
+Welcome to the Apache Cloudberry Build Environment!
+
+Container OS ........ : Rocky Linux 9.5 (Blue Onyx)
+User ................ : gpadmin
+Container hostname .. : cdw
+IP Address .......... : 170.17.0.1
+CPU Info ............ : Intel(R) Xeon(R) Gold 6151 CPU @ 3.00GHz
+CPU(s) .............. : 8
+Memory .............. : 15Gi total
+======================================================================
+
+[gpadmin@cdw ~]$
+```
+
+## What's next?
+
+- [Download the source code](./download-source-code.md)
+- [Configure Apache Cloudberry Build](./configure.md)
+- [Build and Install Apache Cloudberry and contrib
extensions](./build-and-install.md)
+- [Set up a Cloudberry Demo Cluster](./set-demo-cluster.md) (start with the
step `Set up Cloudberry environment variables`)
+- [Post installation](./post-installation.md)
diff --git a/versioned_docs/version-2.x/deployment/configure.md
b/versioned_docs/version-2.x/deployment/configure.md
new file mode 100644
index 000000000..5a69c32a4
--- /dev/null
+++ b/versioned_docs/version-2.x/deployment/configure.md
@@ -0,0 +1,153 @@
+---
+title: Configure Apache Cloudberry Build
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+## Configure the build process
+
+<Tabs>
+<TabItem value="rocky-linux" label="For Rocky Linux 8+" default>
+
+### Prepare environment
+
+The build process requires the necessary libraries (e.g., Xerces-C) to be
available at the expected locations for configuration and runtime. Prepare the
environment using the following commands:
+
+```bash
+sudo rm -rf /usr/local/cloudberry-db
+sudo chmod a+w /usr/local
+mkdir -p /usr/local/cloudberry-db/lib
+sudo cp -v /usr/local/xerces-c/lib/libxerces-c.so \
+ /usr/local/xerces-c/lib/libxerces-c-3.*.so \
+ /usr/local/cloudberry-db/lib
+sudo chown -R gpadmin.gpadmin /usr/local/cloudberry-db
+```
+
+### Run `configure`
+
+The `configure` command sets up the build environment for Apache Cloudberry.
This configuration includes several development features and extensions.
+
+```bash
+cd ~/cloudberry
+export LD_LIBRARY_PATH=/usr/local/cloudberry-db/lib:LD_LIBRARY_PATH
+./configure --prefix=/usr/local/cloudberry-db \
+ --disable-external-fts \
+ --enable-debug \
+ --enable-cassert \
+ --enable-debug-extensions \
+ --enable-gpcloud \
+ --enable-ic-proxy \
+ --enable-mapreduce \
+ --enable-orafce \
+ --enable-orca \
+ --enable-pax \
+ --enable-pxf \
+ --enable-tap-tests \
+ --with-gssapi \
+ --with-ldap \
+ --with-libxml \
+ --with-lz4 \
+ --with-pam \
+ --with-perl \
+ --with-pgport=5432 \
+ --with-python \
+ --with-pythonsrc-ext \
+ --with-ssl=openssl \
+ --with-uuid=e2fs \
+ --with-includes=/usr/local/xerces-c/include \
+ --with-libraries=/usr/local/cloudberry-db/lib
+```
+</TabItem>
+<TabItem value="ubuntu-linux" label="For Ubuntu 22.04+" default>
+
+### Prepare environment
+
+Prepare the environment using the following commands:
+
+```bash
+sudo rm -rf /usr/local/cloudberry-db
+sudo chmod a+w /usr/local
+mkdir -p /usr/local/cloudberry-db
+sudo chown -R gpadmin.gpadmin /usr/local/cloudberry-db
+```
+
+### Run `configure`
+
+The `configure` command sets up the build environment for Apache Cloudberry.
This configuration includes several development features and extensions.
+
+```bash
+cd ~/cloudberry
+./configure --prefix=/usr/local/cloudberry-db \
+ --disable-external-fts \
+ --enable-debug \
+ --enable-cassert \
+ --enable-debug-extensions \
+ --enable-gpcloud \
+ --enable-ic-proxy \
+ --enable-mapreduce \
+ --enable-orafce \
+ --enable-orca \
+ --enable-pax \
+ --enable-pxf \
+ --enable-tap-tests \
+ --with-gssapi \
+ --with-ldap \
+ --with-libxml \
+ --with-lz4 \
+ --with-pam \
+ --with-perl \
+ --with-pgport=5432 \
+ --with-python \
+ --with-pythonsrc-ext \
+ --with-ssl=openssl \
+ --with-uuid=e2fs \
+ --with-includes=/usr/include/xercesc
+```
+</TabItem>
+</Tabs>
+
+## `configure` options
+
+The `configure` script is used to prepare the build environment for Apache
Cloudberry. It checks for required libraries and sets up the necessary
configuration options.
+
+You can run `./configure --help` to see a full list of options available for
configuring Apache Cloudberry. Below is a list of commonly used options with
their descriptions and notes.
+
+:::note
+The build dependencies vary based on which features you enable or disable
during configuration. While we've listed the basic required packages in the
[previous section](./install-required-packages), you may need additional
packages depending on your configuration choices. When you run the
`./configure` command, it will check and report any missing dependencies that
you'll need to install before proceeding with the build.
+
+Also, some packages names vary between different Linux distributions.
+:::
+
+| Option | Description | Notes |
+|--|--|--|
+| `--prefix=PREFIX` |Installation directory. `/usr/local/cbdb` is the default
value. `make install` will install all the files in `/usr/local/cbdb/bin`,
`/usr/local/cbdb/lib` etc. | You can specify an installation prefix other than
`/usr/local/cbdb` using `--prefix`. In this guide, we use
`/usr/local/cloudberry-db` as the installation directory. |
+| `--disable-gpfdist` | Do not use gpfdist | Enable gpfdist by default.
This requires apr lib and libevent to be installed.|
+| `--disable-pxf` | Do not build PXF. | Enable PXF by default. |PXF
is a query federation engine that accesses data residing in external systems
such as Hadoop, Hive, HBase, relational databases, S3, Google Cloud Storage,
among other external systems.|
+| `--enable-orafce` | Build with Oracle compatibility functions. | |
+| `--enable-debug` | Build all programs and libraries with debugging
symbols.| This means that you can run the programs in a debugger to analyze
problems. This enlarges the size of the installed executables considerably, and
on non-GCC compilers it usually also disables compiler optimization, causing
slowdowns. However, having the symbols available is extremely helpful for
dealing with any problems that might arise. Currently, this option is
recommended for production installati [...]
+| `--enable-profiling` | Build with profiling enabled.|This option is for
use only with GCC and when doing development work.|
+| `--enable-tap-tests` | Enable tests using the Perl TAP tools. | This
requires `Perl` and Perl module `IPC::Run` to be installed.|
+| `--enable-cassert` | Enable assertion checks (for debugging)|Enables
assertion checks in the server, which test for many “cannot happen” conditions.
This is invaluable for code development purposes, but the tests can slow down
the server significantly. This option is not recommended for production use,
but you should have it on for development work or when running a beta version.|
+| `--disable-orca` | Disable ORCA optimizer|ORCA is enabled by
default. ORCA requires xerces-c library to be installed.|
+| `--enable-mapreduce` | Enable Cloudberry Mapreduce support| This
requires libyaml to be installed.|
+| `--enable-gpcloud` | Enable gpcloud support||
+| `--enable-external-fts` | Enable external fts support||
+| `--enable-ic-proxy` | Enable interconnect proxy mode | This requires
libuv library to be installed. |
+| `--enable-pax` | Enable PAX support | gcc/gcc-c++ 11+, cmake3,
protobuf and ZSTD are required, see details
[here](https://github.com/apache/cloudberry/blob/main/contrib/pax_storage/doc/README.md#build).
|
+| `--with-includes=DIRS` | Look for additional header files in DIRS|The
Xerces-C is required to build with ORCA.|
+| `--with-libraries=DIRS` | Look for additional libraries in DIRS|The
library xerces-c is required to build with ORCA|
+| `--with-pgport=PORTNUM` | Set default port number [5432]|
`--with-pgport=5432` is used in this guide.|
+| `--with-llvm` | Build with LLVM based JIT support|This requires
the LLVM library to be installed.|
+| `--with-icu` | Build with ICU support | This requires the
ICU4C package to be installed. |
+| `--with-perl` | Build Perl modules (PL/Perl)|This requires Perl
devel packages to be installed.|
+| `--with-python` | Build Python modules (PL/Python)|This requires
Python3 devel packages to be installed.|
+| `--with-pythonsrc-ext` | Build Python modules for gpMgmt|Recommended
options. It's used for gpMgmt tools. If you don't build with this option, you
will need to install the Python packages from the Linux distros after
installing Cloudberry: `psutil`, `pygresql`, `pyyaml`. |
+| `--with-gssapi` | Build with GSSAPI support|The GSSAPI system is
usually a part of the Kerberos installation, so this requires the krb5 package
to be installed.|
+| `--with-pam` | Build with PAM (Pluggable Authentication
Modules) support.|This requires the PAM package to be installed.|
+| `--with-ldap` | Build with LDAP support for authentication and
connection parameter lookup.|This requires the OpenLDAP package to be
installed.|
+| `--with-uuid=LIB` | Build contrib/uuid-ossp module using LIB
(bsd,e2fs,ossp).| <ul><li>`bsd` to use the UUID functions found in FreeBSD and
some other BSD-derived systems</li><li>`e2fs` to use the UUID library created
by the e2fsprogs project; this library is present in most Linux systems and in
macOS, and can be obtained for other platforms as well</li><li>`ossp` to use
the OSSP UUID library</li></ul> So we use `--with-uuid=e2fs` in the build under
Linux/macOS - this requires [...]
+| `--with-libxml` | Build with libxml2, enabling SQL/XML
support.|This requires libxml2 to be installed.|
+| `--with-lz4` | Build with LZ4 compression support |This allows
the use of LZ4 for compression of table data and lz4 library is required to be
installed.|
+| `--with-quicklz` | Build with QuickLZ support |This requires
quicklz library to be installed. |
+| `--with-ssl=LIB` | Build with support for SSL (encrypted)
connections. | The only LIBRARY supported is openssl, so `--with-ssl=openssl`
is used in this guide. This requires the OpenSSL package to be installed. |
diff --git a/versioned_docs/version-2.x/deployment/create-gpadmin-user.md
b/versioned_docs/version-2.x/deployment/create-gpadmin-user.md
new file mode 100644
index 000000000..cfcec0200
--- /dev/null
+++ b/versioned_docs/version-2.x/deployment/create-gpadmin-user.md
@@ -0,0 +1,89 @@
+---
+title: Create and configure the gpadmin User
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+
+## Install `sudo` & `git` (if missing)
+
+If `sudo` & `git` command is not already installed, run the following command
to install it:
+
+<Tabs>
+<TabItem value="rocky-linux" label="For Rocky Linux 8+" default>
+```bash
+dnf install -y sudo git
+```
+</TabItem>
+<TabItem value="ubuntu" label="For Ubuntu 22.04+" default>
+```bash
+apt update && apt install -y sudo git
+```
+</TabItem>
+</Tabs>
+
+:::note
+In environments like Docker, the `root` user will be able to use `sudo`
without a password prompt once it is installed.
+:::
+
+## Create and configure the `gpadmin` user
+
+To prepare the environment for Apache Cloudberry development, we need to
create and configure a dedicated `gpadmin` user.
+
+1. Create a user 'gpadmin' with matching group, home directory, and bash shell:
+
+ ```bash
+ sudo useradd -U -m -s /bin/bash gpadmin
+ ```
+
+2. Grant password-less sudo access to `gpadmin`:
+
+ ```bash
+ echo 'gpadmin ALL=(ALL) NOPASSWD:ALL' | sudo tee /etc/sudoers.d/90-gpadmin
+ ```
+
+3. Verify the `gpadmin` user setup:
+
+ ```bash
+ sudo -u gpadmin sudo whoami
+ ```
+
+ If the output is `root`, the configuration is correct.
+
+
+## Required configuration
+
+This script performs three main tasks as the `gpadmin` user:
+
+- Updates `.bashrc` to source Cloudberry environment variables
+- Sets up SSH key pair for passwordless login (if not already present)
+- Configures proper SSH directory permissions for security
+
+The script uses a heredoc (EOF) block to execute multiple commands under the
`gpadmin` user context. This will be used multiple time throughout these
instructions.
+
+```bash
+sudo -u gpadmin bash <<'EOF'
+# Add Cloudberry environment setup to .bashrc
+echo -e '\n# Add Cloudberry entries
+if [ -f /usr/local/cloudberry-db/greenplum_path.sh ]; then
+ source /usr/local/cloudberry-db/greenplum_path.sh
+fi
+
+# US English with UTF-8 character encoding
+export LANG=en_US.UTF-8
+' >> /home/gpadmin/.bashrc
+
+# Set up SSH for passwordless access
+mkdir -p /home/gpadmin/.ssh
+if [ ! -f /home/gpadmin/.ssh/id_rsa ]; then
+ ssh-keygen -t rsa -b 2048 -C 'apache-cloudberry-dev' -f
/home/gpadmin/.ssh/id_rsa -N ""
+fi
+cat /home/gpadmin/.ssh/id_rsa.pub >> /home/gpadmin/.ssh/authorized_keys
+
+# Set proper SSH directory permissions
+chmod 700 /home/gpadmin/.ssh
+chmod 600 /home/gpadmin/.ssh/authorized_keys
+chmod 644 /home/gpadmin/.ssh/id_rsa.pub
+EOF
+```
\ No newline at end of file
diff --git a/docs/deployment/download-source-code.md
b/versioned_docs/version-2.x/deployment/download-source-code.md
similarity index 53%
copy from docs/deployment/download-source-code.md
copy to versioned_docs/version-2.x/deployment/download-source-code.md
index 4e493328e..7dd9cfbae 100644
--- a/docs/deployment/download-source-code.md
+++ b/versioned_docs/version-2.x/deployment/download-source-code.md
@@ -12,12 +12,13 @@ sudo su - gpadmin
## Clone the Apache Cloudberry repository
-Clone the source code for Apache Cloudberry into the `gpadmin` user's home
directory:
+Clone the release source code for Apache Cloudberry into the `gpadmin` user's
home directory:
```bash
git clone https://github.com/apache/cloudberry.git ~/cloudberry
cd ~/cloudberry
git submodule update --init --recursive
+git checkout tags/<release tag>
```
:::note
@@ -44,18 +45,10 @@ export GNUTLS_CPUID_OVERRIDE=0x1
Alternatively, you can download the source code archive from the [Apache
Cloudberry releases page](https://github.com/apache/cloudberry/releases).
```bash
-tar xvzf cloudberry-<version>.tar.gz
-cd cloudberry-<version>
+tar xvzf apache-cloudberry-<version>-incubating.tar.gz
+cd apache-cloudberry-<version>-incubating
```
:::note
-You cannot use `git submodule update --init --recursive` to initialize
submodules for building with PAX support when you download the source code
archive. After unarchiving the source code archive, you need to download the
submodules manually at the root directory of the source code:
-
-```bash
-git clone https://github.com/google/googletest.git
contrib/pax_storage/src/cpp/contrib/googletest
-git clone https://github.com/p-ranav/tabulate.git
contrib/pax_storage/src/cpp/contrib/tabulate
-git clone https://github.com/google/benchmark.git
contrib/pax_storage/src/cpp/contrib/googlebench
-git clone https://github.com/coolxv/cpp-stub.git
contrib/pax_storage/src/cpp/contrib/cpp-stub
-git clone https://github.com/ibireme/yyjson.git dependency/yyjson
-```
+The submodules are already included in the latest 2.0.0 release source code
archive, so you don't need to download the submodules manually after extracting
the archive.
:::
\ No newline at end of file
diff --git a/docs/deployment/index.md
b/versioned_docs/version-2.x/deployment/index.md
similarity index 98%
copy from docs/deployment/index.md
copy to versioned_docs/version-2.x/deployment/index.md
index f64c8e65d..fe9b932ee 100644
--- a/docs/deployment/index.md
+++ b/versioned_docs/version-2.x/deployment/index.md
@@ -35,7 +35,7 @@ For those new to Cloudberry or PostgreSQL, we recommend
starting with a PostgreS
## Prerequisites
-### Provision a Rocky Linux 8+ / Ubuntu 22.04+ VM
+### Provision a Rocky Linux 8+ / Ubuntu 22.04+ Environment
- Use any platform to create a virtual machine or container:
diff --git a/versioned_docs/version-2.x/deployment/install-required-packages.md
b/versioned_docs/version-2.x/deployment/install-required-packages.md
new file mode 100644
index 000000000..f1ba7faa3
--- /dev/null
+++ b/versioned_docs/version-2.x/deployment/install-required-packages.md
@@ -0,0 +1,154 @@
+---
+title: Install required packages
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+This step installs essential development tools, libraries, and dependencies
required for building Apache Cloudberry.
+
+## Install basic system packages
+
+The following command installs the full set of primary packages required for
Cloudberry development:
+
+<Tabs>
+<TabItem value="rocky-linux" label="For Rocky Linux 8+" default>
+
+```bash
+sudo dnf install -y apr-devel \
+ bison \
+ bzip2-devel \
+ cmake3 \
+ diffutils \
+ flex \
+ gcc \
+ gcc-c++ \
+ glibc-langpack-en \
+ glibc-locale-source \
+ iproute \
+ krb5-devel \
+ libcurl-devel \
+ libevent-devel \
+ libxml2-devel \
+ libuuid-devel \
+ libzstd-devel \
+ lz4-devel \
+ net-tools \
+ openldap-devel \
+ openssl-devel \
+ openssh-server \
+ pam-devel \
+ perl \
+ perl-ExtUtils-Embed \
+ perl-Test-Simple \
+ perl-Env \
+ python3-devel \
+ readline-devel \
+ rsync \
+ wget \
+ which \
+ zlib-devel
+```
+
+### Enable additional development tools and libraries
+
+For Rocky Linux, we also need to install `CodeReady Builder (CRB)` or `devel`
repos- they can provide additional development tools and libraries.
+
+On Rocky Linux, they are disabled by default and must be explicitly enabled.
+
+<Tabs>
+<TabItem value="rocky-linux-8" label="For Rocky Linux 8" default>
+```bash
+sudo dnf install -y --enablerepo=devel libuv-devel libyaml-devel perl-IPC-Run
protobuf-devel
+```
+</TabItem>
+<TabItem value="rocky-linux-9" label="For Rocky Linux 9">
+```bash
+sudo dnf install -y --enablerepo=crb libuv-devel libyaml-devel perl-IPC-Run
protobuf-devel
+```
+</TabItem>
+</Tabs>
+
+:::note
+In Red Hat Enterprise Linux (RHEL), this repository is called "PowerTools."
+:::
+
+### Install gcc/gcc-c++ 11+ for Rocky Linux 8 (Optional)
+
+For Rocky Linux 8, we need to install the higher version of gcc and gcc-c++ to
build Apache Cloudberry with PAX support:
+
+```bash
+sudo yum install -y gcc-toolset-11-gcc gcc-toolset-11-gcc-c++
+scl enable gcc-toolset-11 bash # for temprory use
+sudo echo "source /opt/rh/gcc-toolset-11/enable" >> /etc/profile.d/gcc.sh
+sudo source /etc/profile.d/gcc.sh # for permanent use
+```
+
+You can verify the gcc and gcc-c++ 11+ version by running:
+
+```bash
+gcc --version
+g++ --version
+```
+
+### Install Apache Xerces-C for ORCA
+
+Apache Xerces-C is a required dependency for enabling the Orca query optimizer
in Cloudberry. The following steps download the source code, verify its
integrity, build the library, and install it.
+
+1. Set variables (helper)
+
+ To streamline the commands and make them reusable, define the following
helper variables:
+
+ ```bash
+ XERCES_LATEST_RELEASE=3.3.0
+ XERCES_INSTALL_PREFIX="/usr/local/xerces-c"
+ ```
+
+:::note
+These variables are used throughout the build process to specify the version
of Apache Xerces-C being installed (XERCES_LATEST_RELEASE) and its installation
directory (XERCES_INSTALL_PREFIX). This ensures consistency and simplifies the
commands.
+:::
+
+2. Download and verify the source package
+
+ ```bash
+ wget -nv
"https://dlcdn.apache.org//xerces/c/3/sources/xerces-c-${XERCES_LATEST_RELEASE}.tar.gz";
+ echo "$(curl -sL
https://dlcdn.apache.org//xerces/c/3/sources/xerces-c-${XERCES_LATEST_RELEASE}.tar.gz.sha256)"
| sha256sum -c -
+ ```
+
+:::note
+Ensure the SHA-256 checksum validation passes (output: `xerces-c-3.3.0.tar.gz:
OK`). If it fails, do not proceed and verify the source package's integrity.
+:::
+
+3. Extract, configure, build, test, and install
+
+ ```bash
+ tar xf "xerces-c-${XERCES_LATEST_RELEASE}.tar.gz"
+ rm "xerces-c-${XERCES_LATEST_RELEASE}.tar.gz"
+ cd xerces-c-${XERCES_LATEST_RELEASE}
+
+ ./configure --prefix="${XERCES_INSTALL_PREFIX}-${XERCES_LATEST_RELEASE}" |
tee configure-$(date "+%Y.%m.%d-%H.%M.%S").log
+ make -j$(nproc) | tee make-$(date "+%Y.%m.%d-%H.%M.%S").log
+ make check | tee make-check-$(date "+%Y.%m.%d-%H.%M.%S").log
+ sudo make install | tee make-install-$(date "+%Y.%m.%d-%H.%M.%S").log
+ sudo ln -s ${XERCES_INSTALL_PREFIX}-${XERCES_LATEST_RELEASE}
${XERCES_INSTALL_PREFIX}
+ ```
+
+:::note
+- The `make` command is run in parallel (`-j$(nproc)`) to leverage all
available CPU cores for faster builds. The `nproc` command dynamically
retrieves the number of cores.
+- During `make check`, failures listed as **XFAIL** (expected failures) are
acceptable and do not indicate a problem with the build.
+- The output of the commands are saved to timestamped log files for future
reference or troubleshooting.
+:::
+
+</TabItem>
+<TabItem value="ubuntu" label="For Ubuntu 22.04+">
+
+For Ubuntu users:
+
+- The gcc and g++ versions in Ubuntu 22.04+ are sufficient for building Apache
Cloudberry.
+- We will use the default version of `libxerces-c` available in the Ubuntu
repositories, which is compatible with Apache Cloudberry.
+
+```bash
+sudo apt install -y gcc g++ libxml2-dev pkg-config bzip2 libzstd-dev bison
python3 flex python3-dev libreadline-dev libuv1-dev libkrb5-dev libapr1-dev
libevent-dev libyaml-dev libssl-dev libpam0g-dev libcurl4-gnutls-dev libbz2-dev
libldap2-dev libxerces-c-dev libperl-dev libipc-run-perl make cmake
libprotobuf-dev python3-setuptools iproute2 iputils-ping rsync liblz4-dev
protobuf-compiler language-pack-en locales
+```
+</TabItem>
+</Tabs>
\ No newline at end of file
diff --git a/versioned_docs/version-2.x/deployment/post-installation.md
b/versioned_docs/version-2.x/deployment/post-installation.md
new file mode 100644
index 000000000..9cec9df17
--- /dev/null
+++ b/versioned_docs/version-2.x/deployment/post-installation.md
@@ -0,0 +1,75 @@
+---
+title: Post installation
+---
+
+## Validate basic functionalities
+
+Run the installcheck test suite to verify basic functionality. It is
recommended to test with both Orca (the query optimizer) enabled and disabled:
+
+```bash
+# Run tests with Orca optimizer enabled
+PGOPTIONS='-c optimizer=on' make --directory=~/cloudberry installcheck
+
+# Run tests with Orca optimizer disabled
+PGOPTIONS='-c optimizer=off' make --directory=~/cloudberry installcheck
+```
+
+:::tip
+Even though Orca is the default Cloudberry optimizer, you must explicitly set
`optimizer=on` when running installcheck. Without this setting, the `explain`
test will fail due to missing the explicit configuration option.
+:::
+
+### 1. Test results
+
+The installcheck target provides a basic test of functionality. During
execution, you'll see output like this:
+
+```bash
+test tablespace ... ok 3236 ms (diff 76 ms)
+parallel group (20 tests): pg_lsn oid txid name char varchar int2 regproc
text ...
+ boolean ... ok 862 ms (diff 56 ms)
+ char ... ok 419 ms (diff 87 ms)
+ explain ... FAILED 310 ms (diff 139 ms)
+```
+
+At the end, you'll see a summary, for example:
+
+```
+========================
+ 1 of 658 tests failed.
+========================
+```
+
+If any tests fail:
+
+- `regression.diffs`: Shows differences between actual and expected results
+- `regression.out`: Contains the complete test execution output
+
+The files will be located in `/home/gpadmin/cloudberry/src/test/regress/`.
+
+:::note
+installcheck is just one of several test schedules available. This guide
focuses on basic development environment setup and validation.
+:::
+
+### 2. Troubleshoot test failures
+
+If a test fails, you might need to examine the log files from various cluster
components. You can locate the data directories containing these logs by
querying the segment configuration:
+
+```bash
+psql -P pager=off template1 -c 'SELECT * from gp_segment_configuration'
+```
+
+This shows the complete cluster configuration. The `content = -1` identifies
coordinator nodes:
+
+```sql
+ dbid | content | role | preferred_role | mode | status | port | hostname |
address | datadir
| warehouseid
+------+---------+------+----------------+------+--------+------+----------+---------+----------------------------------------------------------------------------+-------------
+ 1 | -1 | p | p | n | u | 7000 | mdw |
mdw | /home/gpadmin/cloudberry/gpAux/gpdemo/datadirs/qddir/demoDataDir-1
| 0
+ 8 | -1 | m | m | s | u | 7001 | mdw |
mdw | /home/gpadmin/cloudberry/gpAux/gpdemo/datadirs/standby
| 0
+ 2 | 0 | p | p | s | u | 7002 | mdw |
mdw | /home/gpadmin/cloudberry/gpAux/gpdemo/datadirs/dbfast1/demoDataDir0
| 0
+ 5 | 0 | m | m | s | u | 7005 | mdw |
mdw |
/home/gpadmin/cloudberry/gpAux/gpdemo/datadirs/dbfast_mirror1/demoDataDir0 |
0
+ 3 | 1 | p | p | s | u | 7003 | mdw |
mdw | /home/gpadmin/cloudberry/gpAux/gpdemo/datadirs/dbfast2/demoDataDir1
| 0
+ 6 | 1 | m | m | s | u | 7006 | mdw |
mdw |
/home/gpadmin/cloudberry/gpAux/gpdemo/datadirs/dbfast_mirror2/demoDataDir1 |
0
+ 4 | 2 | p | p | s | u | 7004 | mdw |
mdw | /home/gpadmin/cloudberry/gpAux/gpdemo/datadirs/dbfast3/demoDataDir2
| 0
+ 7 | 2 | m | m | s | u | 7007 | mdw |
mdw |
/home/gpadmin/cloudberry/gpAux/gpdemo/datadirs/dbfast_mirror3/demoDataDir2 |
0
+```
+
+Each `datadir` contains log files that can help diagnose test failures. Review
the logs in the relevant component's directory based on which test failed.
\ No newline at end of file
diff --git a/versioned_docs/version-2.x/deployment/quick-build.md
b/versioned_docs/version-2.x/deployment/quick-build.md
new file mode 100644
index 000000000..ca726973d
--- /dev/null
+++ b/versioned_docs/version-2.x/deployment/quick-build.md
@@ -0,0 +1,305 @@
+---
+title: Quick Build
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+In the following sections, we'll provide detailed, step-by-step instructions
for building Apache Cloudberry from source code. However, if you're familiar
with the process or prefer a quick start, you can simply copy and paste the
commands below to get Apache Cloudberry up and running.
+
+By this, you will get an Apache Cloudberry environment with a demo cluster
ready for testing and development.
+
+<Tabs>
+<TabItem value="rocky-linux" label="For Rocky Linux 8+" default>
+```bash
+
+# Install sudo & git
+dnf install -y sudo git
+
+# Create and configure the gpadmin user
+sudo useradd -U -m -s /bin/bash gpadmin
+echo 'gpadmin ALL=(ALL) NOPASSWD:ALL' | sudo tee /etc/sudoers.d/90-gpadmin
+sudo -u gpadmin sudo whoami # if the output is root, the configuration is
correct
+
+
+# Required configuration for gpadmin user
+sudo -u gpadmin bash <<'EOF'
+## Add Cloudberry environment setup to .bashrc
+echo -e '\n# Add Cloudberry entries
+if [ -f /usr/local/cloudberry-db/greenplum_path.sh ]; then
+ source /usr/local/cloudberry-db/greenplum_path.sh
+fi
+## US English with UTF-8 character encoding
+export LANG=en_US.UTF-8
+' >> /home/gpadmin/.bashrc
+## Set up SSH for passwordless access
+mkdir -p /home/gpadmin/.ssh
+if [ ! -f /home/gpadmin/.ssh/id_rsa ]; then
+ ssh-keygen -t rsa -b 2048 -C 'apache-cloudberry-dev' -f
/home/gpadmin/.ssh/id_rsa -N ""
+fi
+cat /home/gpadmin/.ssh/id_rsa.pub >> /home/gpadmin/.ssh/authorized_keys
+## Set proper SSH directory permissions
+chmod 700 /home/gpadmin/.ssh
+chmod 600 /home/gpadmin/.ssh/authorized_keys
+chmod 644 /home/gpadmin/.ssh/id_rsa.pub
+EOF
+
+
+# Configure system settings
+sudo tee /etc/security/limits.d/90-db-limits.conf << 'EOF'
+## Core dump file size limits for gpadmin
+gpadmin soft core unlimited
+gpadmin hard core unlimited
+## Open file limits for gpadmin
+gpadmin soft nofile 524288
+gpadmin hard nofile 524288
+## Process limits for gpadmin
+gpadmin soft nproc 131072
+gpadmin hard nproc 131072
+EOF
+
+# Verify resource limits.
+sudo -u gpadmin bash -c "ulimit -a"
+
+# Install required packages
+sudo dnf install -y apr-devel \
+ bison \
+ bzip2-devel \
+ cmake3 \
+ diffutils \
+ flex \
+ gcc \
+ gcc-c++ \
+ glibc-langpack-en \
+ glibc-locale-source \
+ iproute \
+ krb5-devel \
+ libcurl-devel \
+ libevent-devel \
+ libxml2-devel \
+ libuuid-devel \
+ libzstd-devel \
+ lz4-devel \
+ net-tools \
+ openldap-devel \
+ openssl-devel \
+ openssh-server \
+ pam-devel \
+ perl \
+ perl-ExtUtils-Embed \
+ perl-Test-Simple \
+ perl-Env \
+ python3-devel \
+ readline-devel \
+ rsync \
+ wget \
+ which \
+ zlib-devel
+
+# Enable additional development tools and libraries
+## For Rocky Linux 8
+sudo dnf install -y --enablerepo=devel libuv-devel libyaml-devel perl-IPC-Run
protobuf-devel
+## For Rocky Linux 9
+sudo dnf install -y --enablerepo=crb libuv-devel libyaml-devel perl-IPC-Run
protobuf-devel
+
+# Only for Rocky Linux 8, install the higher version of gcc and gcc-c++
+sudo yum install -y gcc-toolset-11-gcc gcc-toolset-11-gcc-c++
+scl enable gcc-toolset-11 bash # for temprory use
+sudo echo "source /opt/rh/gcc-toolset-11/enable" >> /etc/profile.d/gcc.sh
+sudo source /etc/profile.d/gcc.sh # for permanent use
+
+# Build Xerces-C source code
+XERCES_LATEST_RELEASE=3.3.0
+XERCES_INSTALL_PREFIX="/usr/local/xerces-c"
+wget -nv
"https://dlcdn.apache.org//xerces/c/3/sources/xerces-c-${XERCES_LATEST_RELEASE}.tar.gz";
+echo "$(curl -sL
https://dlcdn.apache.org//xerces/c/3/sources/xerces-c-${XERCES_LATEST_RELEASE}.tar.gz.sha256)"
| sha256sum -c -
+tar xf "xerces-c-${XERCES_LATEST_RELEASE}.tar.gz"
+rm "xerces-c-${XERCES_LATEST_RELEASE}.tar.gz"
+cd xerces-c-${XERCES_LATEST_RELEASE}
+./configure --prefix="${XERCES_INSTALL_PREFIX}-${XERCES_LATEST_RELEASE}"
+make -j$(nproc)
+make check
+sudo make install
+sudo ln -s ${XERCES_INSTALL_PREFIX}-${XERCES_LATEST_RELEASE}
${XERCES_INSTALL_PREFIX}
+
+# Switch to the gpadmin user from now on
+sudo su - gpadmin
+
+# Download Source Code
+git clone https://github.com/apache/cloudberry.git ~/cloudberry
+cd ~/cloudberry
+git submodule update --init --recursive
+
+# Prepare the build environment for Apache Cloudberry
+sudo rm -rf /usr/local/cloudberry-db
+sudo chmod a+w /usr/local
+mkdir -p /usr/local/cloudberry-db/lib
+sudo cp -v /usr/local/xerces-c/lib/libxerces-c.so \
+ /usr/local/xerces-c/lib/libxerces-c-3.*.so \
+ /usr/local/cloudberry-db/lib
+sudo chown -R gpadmin.gpadmin /usr/local/cloudberry-db
+
+# Run configure
+cd ~/cloudberry
+export LD_LIBRARY_PATH=/usr/local/cloudberry-db/lib:LD_LIBRARY_PATH
+./configure --prefix=/usr/local/cloudberry-db \
+ --disable-external-fts \
+ --enable-debug \
+ --enable-cassert \
+ --enable-debug-extensions \
+ --enable-gpcloud \
+ --enable-ic-proxy \
+ --enable-mapreduce \
+ --enable-orafce \
+ --enable-orca \
+ --enable-pax \
+ --enable-pxf \
+ --enable-tap-tests \
+ --with-gssapi \
+ --with-ldap \
+ --with-libxml \
+ --with-lz4 \
+ --with-pam \
+ --with-perl \
+ --with-pgport=5432 \
+ --with-python \
+ --with-pythonsrc-ext \
+ --with-ssl=openssl \
+ --with-uuid=e2fs \
+ --with-includes=/usr/local/xerces-c/include \
+ --with-libraries=/usr/local/cloudberry-db/lib
+
+# Build and install Cloudberry and its contrib modules
+make -j$(nproc) -C ~/cloudberry
+make -j$(nproc) -C ~/cloudberry/contrib
+make install -C ~/cloudberry
+make install -C ~/cloudberry/contrib
+
+# Verify the installation
+/usr/local/cloudberry-db/bin/postgres --gp-version
+/usr/local/cloudberry-db/bin/postgres --version
+ldd /usr/local/cloudberry-db/bin/postgres
+
+# Set up a Cloudberry demo cluster
+source /usr/local/cloudberry-db/greenplum_path.sh
+make create-demo-cluster -C ~/cloudberry
+source ~/cloudberry/gpAux/gpdemo/gpdemo-env.sh
+psql -P pager=off template1 -c 'SELECT * from gp_segment_configuration'
+psql template1 -c 'SELECT version()'
+```
+</TabItem>
+<TabItem value="ubuntu" label="For Ubuntu 22.04+">
+
+```bash
+
+# Install sudo & git
+apt update && apt install -y sudo git
+
+# Create and configure the gpadmin user
+sudo useradd -U -m -s /bin/bash gpadmin
+echo 'gpadmin ALL=(ALL) NOPASSWD:ALL' | sudo tee /etc/sudoers.d/90-gpadmin
+sudo -u gpadmin sudo whoami # if the output is root, the configuration is
correct
+
+# Required configuration
+sudo -u gpadmin bash <<'EOF'
+## Add Cloudberry environment setup to .bashrc
+echo -e '\n# Add Cloudberry entries
+if [ -f /usr/local/cloudberry-db/greenplum_path.sh ]; then
+ source /usr/local/cloudberry-db/greenplum_path.sh
+fi
+## US English with UTF-8 character encoding
+export LANG=en_US.UTF-8
+' >> /home/gpadmin/.bashrc
+## Set up SSH for passwordless access
+mkdir -p /home/gpadmin/.ssh
+if [ ! -f /home/gpadmin/.ssh/id_rsa ]; then
+ ssh-keygen -t rsa -b 2048 -C 'apache-cloudberry-dev' -f
/home/gpadmin/.ssh/id_rsa -N ""
+fi
+cat /home/gpadmin/.ssh/id_rsa.pub >> /home/gpadmin/.ssh/authorized_keys
+## Set proper SSH directory permissions
+chmod 700 /home/gpadmin/.ssh
+chmod 600 /home/gpadmin/.ssh/authorized_keys
+chmod 644 /home/gpadmin/.ssh/id_rsa.pub
+EOF
+
+# Configure system settings
+sudo tee /etc/security/limits.d/90-db-limits.conf << 'EOF'
+## Core dump file size limits for gpadmin
+gpadmin soft core unlimited
+gpadmin hard core unlimited
+## Open file limits for gpadmin
+gpadmin soft nofile 524288
+gpadmin hard nofile 524288
+## Process limits for gpadmin
+gpadmin soft nproc 131072
+gpadmin hard nproc 131072
+EOF
+
+# Verify resource limits
+sudo -u gpadmin bash -c "ulimit -a"
+
+# Install basic system packages
+sudo apt install -y gcc g++ libxml2-dev pkg-config bzip2 libzstd-dev bison
python3 flex python3-dev libreadline-dev libuv1-dev libkrb5-dev libapr1-dev
libevent-dev libyaml-dev libssl-dev libpam0g-dev libcurl4-gnutls-dev libbz2-dev
libldap2-dev libxerces-c-dev libperl-dev libipc-run-perl make cmake
libprotobuf-dev python3-setuptools iproute2 iputils-ping rsync liblz4-dev
protobuf-compiler language-pack-en locales
+
+# Use the gpadmin user from now on
+sudo su - gpadmin
+
+# Clone the Apache Cloudberry repository
+git clone https://github.com/apache/cloudberry.git ~/cloudberry
+cd ~/cloudberry
+git submodule update --init --recursive
+
+# Prepare the build environment for Apache Cloudberry
+sudo rm -rf /usr/local/cloudberry-db
+sudo chmod a+w /usr/local
+mkdir -p /usr/local/cloudberry-db
+sudo chown -R gpadmin.gpadmin /usr/local/cloudberry-db
+
+# Run configure
+cd ~/cloudberry
+./configure --prefix=/usr/local/cloudberry-db \
+ --disable-external-fts \
+ --enable-debug \
+ --enable-cassert \
+ --enable-debug-extensions \
+ --enable-gpcloud \
+ --enable-ic-proxy \
+ --enable-mapreduce \
+ --enable-orafce \
+ --enable-orca \
+ --enable-pax \
+ --enable-pxf \
+ --enable-tap-tests \
+ --with-gssapi \
+ --with-ldap \
+ --with-libxml \
+ --with-lz4 \
+ --with-pam \
+ --with-perl \
+ --with-pgport=5432 \
+ --with-python \
+ --with-pythonsrc-ext \
+ --with-ssl=openssl \
+ --with-uuid=e2fs \
+ --with-includes=/usr/include/xercesc
+
+# Build and install Cloudberry and its contrib modules
+make -j$(nproc) -C ~/cloudberry
+make -j$(nproc) -C ~/cloudberry/contrib
+make install -C ~/cloudberry
+make install -C ~/cloudberry/contrib
+
+# Verify the installation
+/usr/local/cloudberry-db/bin/postgres --gp-version
+/usr/local/cloudberry-db/bin/postgres --version
+ldd /usr/local/cloudberry-db/bin/postgres
+
+# Set up a Cloudberry demo cluster
+source /usr/local/cloudberry-db/greenplum_path.sh
+make create-demo-cluster -C ~/cloudberry
+source ~/cloudberry/gpAux/gpdemo/gpdemo-env.sh
+psql -P pager=off template1 -c 'SELECT * from gp_segment_configuration'
+psql template1 -c 'SELECT version()'
+```
+</TabItem>
+</Tabs>
diff --git a/versioned_docs/version-2.x/deployment/set-demo-cluster.md
b/versioned_docs/version-2.x/deployment/set-demo-cluster.md
new file mode 100644
index 000000000..fee5d0a3b
--- /dev/null
+++ b/versioned_docs/version-2.x/deployment/set-demo-cluster.md
@@ -0,0 +1,193 @@
+---
+title: Set up a Cloudberry demo cluster
+---
+
+This step walks through setting up a Cloudberry demo cluster, and testing
basic functionality. The demo cluster includes a coordinator, standby
coordinator, and multiple primary/mirror segments all running on a single
development host.
+
+## Set up initial container (not required for all environments)
+
+Container environments typically don't start the SSH daemon process by
default. Since Cloudberry relies heavily on SSH for inter-process
communication, we need to initialize and start the SSH server:
+
+```bash
+if ! pgrep sshd > /dev/null; then
+ echo "SSH daemon not running. Starting it now..."
+ sudo ssh-keygen -A
+ echo "PasswordAuthentication yes" | sudo tee -a /etc/ssh/sshd_config
+ sudo /usr/sbin/sshd
+else
+ echo "SSH daemon is already running"
+fi
+```
+
+## Configure SSH for Cloudberry
+
+Cloudberry uses SSH for coordinator-segment communication. The following
commands ensure SSH is properly configured for the gpadmin user by adding the
host to known_hosts and verifying SSH connectivity:
+
+```bash
+ssh-keyscan $(hostname) >> ~/.ssh/known_hosts
+ssh $(hostname) date
+```
+
+## Set up Cloudberry environment variables
+
+Load Cloudberry environment variables that set up paths for binaries,
libraries, and other essential components:
+
+```bash
+source /usr/local/cloudberry-db/greenplum_path.sh
+```
+
+## Create development cluster
+
+Create a demo cluster that simulates a full Cloudberry deployment on a single
machine. This includes 1 coordinator, 1 standby coordinator, 3 primary
segments, and 3 mirror segments:
+
+```bash
+make create-demo-cluster --directory=~/cloudberry
+```
+
+In the demo cluster, the cooradinator, standby coordinator and segments ports
will be as follows:
+
+```
+ COORDINATOR PORT (PGPORT). : 7000
+ STANDBY PORT ............. : 7001
+ SEGMENT PORTS ............ : 7002 7003 7004 7005 7006 7007
+```
+
+## Configure cluster environment
+
+After cluster creation, verify and load cluster-specific variables that point
to the coordinator port and data directory:
+
+```bash
+source ~/cloudberry/gpAux/gpdemo/gpdemo-env.sh
+```
+
+## Validate cluster deployment
+
+Verify the cluster is running correctly with these essential commands:
+
+```bash
+# Displays detailed cluster state including segment status
+gpstate
+
+# Tests cluster shutdown and startup
+gpstop -a
+gpstart -a
+
+# Confirms Cloudberry version and build
+psql template1 -c 'SELECT version()'
+
+# Views segment configuration showing primary/mirror relationships
+psql template1 -c 'SELECT * from gp_segment_configuration'
+
+# Checks available PostgreSQL extensions
+psql template1 -c 'SELECT * FROM pg_available_extensions'
+```
+
+## Connect to the default `postgres` database
+
+To connect to the default `postgres` database, use the following command:
+
+```bash
+psql -p 7000 postgres
+```
+
+Or
+
+```bash
+psql postgres
+```
+
+The output will be like this:
+
+```bash
+[gpadmin@cdw cloudberry]$ psql -p 7000 postgres
+psql (14.4, server 14.4)
+Type "help" for help.
+
+postgres=# select version();
+
version
+------------------------------------------------------------------------------------------------------------------------
+ PostgreSQL 14.4 (Apache Cloudberry 2.0.0-devel+dev.1959.g94a81765e6 build
dev) on x86_64-pc-linux-gnu, compiled by gcc (GCC
+) 11.5.0 20240719 (Red Hat 11.5.0-5), 64-bit compiled on May 28 2025 19:57:16
(with assert checking)
+(1 row)
+
+postgres=# \q
+```
+
+## Extension Testing Example: pg_stat_statements
+
+This example demonstrates how to enable and test the `pg_stat_statements`
extension, which provides statistics about SQL query execution:
+
+```bash
+# Creates a database for testing
+createdb gpadmin
+
+# Enables the extension by adding it to shared libraries
+echo "shared_preload_libraries='pg_stat_statements'" >>
$COORDINATOR_DATA_DIRECTORY/postgresql.conf
+
+# Restarts cluster to load the new library (-r flag means "restart")
+gpstop -ar
+
+# Creates the extension in the database
+psql gpadmin -e -c 'CREATE EXTENSION pg_stat_statements'
+
+# Runs test queries to generate statistics
+psql gpadmin --echo-queries <<EOF
+-- Create a sample table
+CREATE TABLE employees (
+ id SERIAL PRIMARY KEY,
+ name TEXT,
+ department TEXT,
+ salary NUMERIC
+);
+
+-- Insert sample data
+INSERT INTO employees (name, department, salary)
+VALUES
+('Alice', 'HR', 60000),
+('Bob', 'Engineering', 80000),
+('Charlie', 'Marketing', 70000);
+
+-- Query the data to generate some statistics
+SELECT * FROM employees WHERE department = 'Engineering';
+SELECT AVG(salary) FROM employees;
+
+-- View most frequently called queries
+SELECT query, calls, total_exec_time AS total_time, rows
+FROM pg_stat_statements
+ORDER BY calls DESC
+LIMIT 5;
+
+-- View most time-consuming queries
+SELECT query, calls, total_exec_time AS total_time, rows
+FROM pg_stat_statements
+ORDER BY total_exec_time DESC
+LIMIT 5;
+EOF
+```
+
+## Destroy development cluster
+
+To clean up and start fresh, you can destroy the demo cluster:
+
+```bash
+make destroy-demo-cluster --directory=~/cloudberry
+```
+
+This command removes all cluster data and configuration, allowing you to
create a new clean cluster if needed.
+
+## Troubleshoot SSH connection issues
+
+When running `create-demo-cluster`, the process may hang if SSH host
verification hasn't been completed. This typically manifests as a stalled
process waiting for user input to verify the host identity.
+
+This is why we run:
+
+```bash
+ssh-keyscan $(hostname) >> ~/.ssh/known_hosts
+```
+before creating the cluster. This command automatically adds the host's SSH
keys to the known_hosts file, preventing interactive prompts during cluster
creation.
+
+If you still encounter SSH issues:
+
+1. Verify that the SSH daemon is running
+2. Check that the known_hosts file exists and has the correct permissions
+3. Test SSH connectivity with `ssh $(hostname) date` before proceeding with
cluster creation
diff --git a/versioned_docs/version-2.x/deployment/system-settings.md
b/versioned_docs/version-2.x/deployment/system-settings.md
new file mode 100644
index 000000000..18b43ee0d
--- /dev/null
+++ b/versioned_docs/version-2.x/deployment/system-settings.md
@@ -0,0 +1,52 @@
+---
+title: Configure System settings
+---
+
+Database systems like Apache Cloudberry require specific system resource
limits to operate efficiently. These limits should be configured for the
`gpadmin` user who runs the database processes.
+
+1. Create resource limits configuration
+
+ Create user limits configuration file:
+
+ ```bash
+ sudo tee /etc/security/limits.d/90-db-limits.conf << 'EOF'
+ # Core dump file size limits for gpadmin
+ gpadmin soft core unlimited
+ gpadmin hard core unlimited
+ # Open file limits for gpadmin
+ gpadmin soft nofile 524288
+ gpadmin hard nofile 524288
+ # Process limits for gpadmin
+ gpadmin soft nproc 131072
+ gpadmin hard nproc 131072
+ EOF
+ ```
+
+2. Understand the limits.
+
+ The configuration sets the following types of resource limits:
+
+ - **Core Dumps** (`core`):
+
+ - Set to `unlimited` to enable complete core dumps
+ - Essential for debugging and troubleshooting
+ - Both soft and hard limits are unrestricted
+
+ - **Open Files** (`nofile`):
+
+ - Set to `524288` (512K) files
+ - Required for handling many concurrent database connections
+ - Critical for distributed operations and large workloads
+
+ - **Process Limits** (`nproc`):
+
+ - Set to `131072` (128K) processes
+ - Enables parallel query execution
+ - Supports Cloudberry's distributed architecture
+
+3. Verify resource limits.
+
+ ```bash
+ # Check current limits
+ sudo -u gpadmin bash -c "ulimit -a"
+ ```
\ No newline at end of file
diff --git a/versioned_sidebars/version-2.x-sidebars.json
b/versioned_sidebars/version-2.x-sidebars.json
index 48eda255f..4f34fe05d 100644
--- a/versioned_sidebars/version-2.x-sidebars.json
+++ b/versioned_sidebars/version-2.x-sidebars.json
@@ -16,13 +16,15 @@
"items": [
{
"type": "category",
- "label": "Build from Source Code",
- "items": [
- "cbdb-macos-compile",
- "cbdb-rockylinux8-ubuntu-compile",
- "cbdb-rockylinux9-compile"
- ]
- },
+ "label": "Build from Source (Complete Guide)",
+ "link":
+ {
+ "type": "doc",
+ "id": "deployment/index"
+ },
+ "items": ["deployment/quick-build", "deployment/create-gpadmin-user",
"deployment/system-settings", "deployment/install-required-packages",
"deployment/download-source-code", "deployment/configure",
"deployment/build-and-install", "deployment/set-demo-cluster",
"deployment/post-installation"]
+ },
+ "deployment/build-based-on-docker",
{
"type": "category",
"label": "Deploy on Physical or Virtual Machine",
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscr...@cloudberry.apache.org
For additional commands, e-mail: commits-h...@cloudberry.apache.org
