Sandbox: add -c local build mode

Introduce a new "local" codebase option to the sandbox run script so
developers can build Docker images directly from their current local
checkout without cloning Cloudberry again inside the container.

Usage:

    ./run.sh -c local #single node
    ./run.sh -c local -m #multi node

Key changes:

- Extend devops/sandbox/run.sh to accept CODEBASE_VERSION=local,
  compute the repository root as the Docker build context, and pass
  the version through to Docker as a build argument.
- For local builds, initialize git submodules only when both a .git
  directory exists under the repository root and the git command is
  available; otherwise print a clear warning so users know to prepare
  required submodules themselves.

Author: tuhaihe

devops/sandbox/Dockerfile.main.rockylinux9

@@ -19,13 +19,19 @@
 # --------------------------------------------------------------------
 # Multi-stage Dockerfile for Apache Cloudberry Sandbox Environment
 # --------------------------------------------------------------------
-# This Dockerfile uses pre-built Apache Cloudberry build images to
-# compile and install Cloudberry from the main branch, then creates
-# a runtime environment for testing and development.
+# This Dockerfile supports two source modes:
+#   - Main branch: clone the latest main from GitHub (CODEBASE_VERSION=main)
+#   - Local source: use the repository contents from the Docker build context
+#     (CODEBASE_VERSION=local), recommended for developers working from
+#     their current checkout.
+# In both modes it compiles and installs Cloudberry, then creates a
+# runtime environment for testing and development.
 # --------------------------------------------------------------------
 
 # Build stage: Use pre-built image to compile Cloudberry
+ARG CODEBASE_VERSION=main
 FROM rockylinux/rockylinux:9.6 AS builder
+ARG CODEBASE_VERSION
 
 # Install build toolchains and development headers (avoid coreutils/curl conflicts on arm64)
 RUN dnf makecache && \
@@ -118,8 +124,20 @@ RUN groupadd -r gpadmin && \
 USER gpadmin
 WORKDIR /home/gpadmin
 
-# Clone the latest Cloudberry source code
-RUN git clone --recurse-submodules --branch main --single-branch --depth=1 https://github.com/apache/cloudberry.git
+# Copy repository contents from build context
+# Note: This COPY always executes regardless of CODEBASE_VERSION due to Docker
+# layer caching behavior. For main branch builds, the copied content will be
+# removed and replaced by a fresh git clone in the RUN step below. This is an
+# acceptable tradeoff to keep the Dockerfile simple and maintainable.
+COPY --chown=gpadmin:gpadmin . /home/gpadmin/cloudberry
+
+# Obtain Cloudberry source code based on build mode
+RUN if [ "${CODEBASE_VERSION}" = "local" ]; then \
+        echo "Using local source from build context"; \
+    else \
+        rm -rf /home/gpadmin/cloudberry && \
+        git clone --recurse-submodules --branch main --single-branch --depth=1 https://github.com/apache/cloudberry.git; \
+    fi
 
 # Build Cloudberry using the official build scripts
 RUN cd /home/gpadmin/cloudberry && \
@@ -188,12 +206,12 @@ COPY --from=builder /usr/local/xerces-c/lib/libxerces-c.so /usr/local/cloudberry
 COPY --from=builder /usr/local/xerces-c/lib/libxerces-c-3.*.so /usr/local/cloudberry-db/lib/
 
 # Copy configuration files to their final destinations
-COPY ./configs/90-cbdb-limits.conf /etc/security/limits.d/90-cbdb-limits.conf
-COPY ./configs/90-cbdb-sysctl.conf /etc/sysctl.d/90-cbdb-sysctl.conf
-COPY ./configs/gpinitsystem_singlenode /tmp/gpinitsystem_singlenode
-COPY ./configs/gpinitsystem_multinode /tmp/gpinitsystem_multinode
-COPY ./configs/multinode-gpinit-hosts /tmp/multinode-gpinit-hosts
-COPY ./configs/init_system.sh /tmp/init_system.sh
+COPY devops/sandbox/configs/90-cbdb-limits.conf /etc/security/limits.d/90-cbdb-limits.conf
+COPY devops/sandbox/configs/90-cbdb-sysctl.conf /etc/sysctl.d/90-cbdb-sysctl.conf
+COPY devops/sandbox/configs/gpinitsystem_singlenode /tmp/gpinitsystem_singlenode
+COPY devops/sandbox/configs/gpinitsystem_multinode /tmp/gpinitsystem_multinode
+COPY devops/sandbox/configs/multinode-gpinit-hosts /tmp/multinode-gpinit-hosts
+COPY devops/sandbox/configs/init_system.sh /tmp/init_system.sh
 
 # Runtime configuration
 RUN echo "cdw" > /tmp/gpdb-hosts && \

devops/sandbox/README.md

@@ -54,8 +54,9 @@ When building and deploying Apache Cloudberry in Docker, you will have 2 differe
 
 **Build Options**
 
-1. Compile with the source code of the latest Apache Cloudberry (released in [Apache Cloudberry Release Page](https://github.com/apache/cloudberry/releases)). The base OS will be Rocky Linux 9 Docker image.
-2. Method 2 - Compile with the latest Apache Cloudberry [main](https://github.com/apache/cloudberry/tree/main) branch. The base OS will be Rocky Linux 9 Docker image.
+1. **Recommended for most users** – Build directly from your current local source code using `-c local`. This is the fastest way to get started as it reuses your existing checkout, avoiding the need to download the code again inside the container. It is also ideal for developers testing local changes.
+2. Compile with the source code of the latest Apache Cloudberry (released in [Apache Cloudberry Release Page](https://github.com/apache/cloudberry/releases)). The base OS will be Rocky Linux 9 Docker image.
+3. Compile with the latest Apache Cloudberry [main](https://github.com/apache/cloudberry/tree/main) branch. The base OS will be Rocky Linux 9 Docker image.
 
 Build and deploy steps:
 
@@ -69,18 +70,38 @@ Build and deploy steps:
 
 3. Enter the repository and run the `run.sh` script to start the Docker container. This will start the automatic installation process. Depending on your environment, you may need to run this with 'sudo' command.
 
+    - **Recommended: Build from your current local source code (single container)**
+
+        This is the most efficient option for both new users and developers. It uses your local checkout directly, saving time by skipping the code download step inside the container. It also allows you to immediately test any local code modifications.
+
+    ```shell
+    cd cloudberry/devops/sandbox
+    ./run.sh -c local
+    ```
+
+    - **Recommended: Build from your current local source code (multi-container)**
+
+        Same as above, but deploys a multi-container cluster. Ideal for testing distributed features or high availability with your local code.
+
+    ```shell
+    cd cloudberry/devops/sandbox
+    ./run.sh -c local -m
+    ```
+
     - For latest Apache Cloudberry release running on a single container
 
     ```shell
     cd cloudberry/devops/sandbox
     ./run.sh -c 2.0.0
     ```
+
     - For latest Apache Cloudberry release running across multiple containers
 
     ```shell
     cd cloudberry/devops/sandbox
     ./run.sh -c 2.0.0 -m
     ```
+
     - For latest main branch running on a single container
 
     ```shell

devops/sandbox/run.sh

@@ -38,7 +38,7 @@ PIP_INDEX_URL_VAR="${PIP_INDEX_URL_VAR:-$DEFAULT_PIP_INDEX_URL_VAR}"
 # Function to display help message
 function usage() {
     echo "Usage: $0 [-o <os_version>] [-c <codebase_version>] [-b] [-m]"
-    echo "  -c  Codebase version (valid values: main, or other available version like 2.0.0)"
+    echo "  -c  Codebase version (valid values: main, local, or other available version like 2.0.0)"
     echo "  -t  Timezone (default: America/Los_Angeles, or set via TIMEZONE_VAR environment variable)"
     echo "  -p  Python Package Index (PyPI) (default: https://pypi.org/simple, or set via PIP_INDEX_URL_VAR environment variable)"
     echo "  -b  Build only, do not run the container (default: false, or set via BUILD_ONLY environment variable)"
@@ -101,26 +101,50 @@ case "${OS_VERSION}" in
 esac
 
 # Validate CODEBASE_VERSION
-if [[ "${CODEBASE_VERSION}" != "main" && ! "${CODEBASE_VERSION}" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+if [[ "${CODEBASE_VERSION}" != "main" && "${CODEBASE_VERSION}" != "local" && ! "${CODEBASE_VERSION}" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
     echo "Invalid codebase version: ${CODEBASE_VERSION}"
     usage
 fi
 
+# Determine sandbox directory and repository root
+SANDBOX_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "${SANDBOX_DIR}/../.." && pwd)"
+
+# Ensure submodules are initialized for local builds
+if [[ "${CODEBASE_VERSION}" = "local" ]]; then
+    if [[ -d "${REPO_ROOT}/.git" ]] && command -v git >/dev/null 2>&1; then
+        # Check if any submodules are uninitialized (-), out of sync (+), or have conflicts (U)
+        if (cd "${REPO_ROOT}" && git submodule status --recursive | grep -qE "^[+-U]"); then
+            echo "Updating git submodules for local build..."
+            (cd "${REPO_ROOT}" && git submodule update --init --recursive)
+        else
+            echo "Git submodules are already up to date. Skipping update."
+        fi
+    else
+        echo "Warning: Skipping 'git submodule update --init --recursive' for local build because either '.git' directory or 'git' command is missing in ${REPO_ROOT}."
+        echo "If your Cloudberry checkout relies on git submodules, please ensure they have been populated before running with '-c local'."
+    fi
+fi
+
+
 # Build image
-if [[ "${CODEBASE_VERSION}" = "main"  ]]; then
-    DOCKERFILE=Dockerfile.${CODEBASE_VERSION}.${OS_VERSION}
+if [[ "${CODEBASE_VERSION}" = "main" || "${CODEBASE_VERSION}" = "local" ]]; then
+    DOCKERFILE="${SANDBOX_DIR}/Dockerfile.main.${OS_VERSION}"
 
-    # Single image build
+    # Single image build from main or local source
     docker build --file ${DOCKERFILE} \
                  --build-arg TIMEZONE_VAR="${TIMEZONE_VAR}" \
-                 --tag cbdb-${CODEBASE_VERSION}:${OS_VERSION} .
+                 --build-arg CODEBASE_VERSION="${CODEBASE_VERSION}" \
+                 --tag cbdb-${CODEBASE_VERSION}:${OS_VERSION} \
+                 ${REPO_ROOT}
 else
-    DOCKERFILE=Dockerfile.RELEASE.${OS_VERSION}
+    DOCKERFILE="${SANDBOX_DIR}/Dockerfile.RELEASE.${OS_VERSION}"
 
     docker build --file ${DOCKERFILE} \
                  --build-arg TIMEZONE_VAR="${TIMEZONE_VAR}" \
                  --build-arg CODEBASE_VERSION_VAR="${CODEBASE_VERSION}" \
-                 --tag cbdb-${CODEBASE_VERSION}:${OS_VERSION} .
+                 --tag cbdb-${CODEBASE_VERSION}:${OS_VERSION} \
+                 ${SANDBOX_DIR}
 fi
 
 # Check if build only flag is set