Redesign Docker build system to two-stage architecture with builder/runtime separation

Redesigned the Docker build system from a single-stage monolithic design to a clean
two-stage architecture that separates build environment from compilation process while
maintaining library path compatibility.

## Architecture Changes

### Builder Image (docker/builder/Dockerfile)
- Provides base environment: CUDA 11.4, GCC 10, CMake 4, Go 1.25.3
- Built once, cached for subsequent builds (~90 min first time)
- Removed config file copying (cuda-11.4.sh, gcc-10.conf, go.sh)
- Added comprehensive comments explaining each build step
- Added git installation for runtime stage source cloning

### Runtime Image (docker/runtime/Dockerfile)
- Two-stage build using ollama37-builder as base for BOTH stages
- Stage 1 (compile): Clone source from GitHub → CMake configure → Build C/C++/CUDA → Build Go
- Stage 2 (runtime): Copy artifacts from stage 1 → Setup environment → Configure server
- Both stages use identical base image to ensure library path compatibility
- Removed -buildvcs=false flag (VCS info embedded from git clone)
- Comprehensive comments documenting library paths and design rationale

### Makefile (docker/Makefile)
- Simplified from 289 to 145 lines (-50% complexity)
- Removed: run, stop, logs, shell, test targets (use docker-compose instead)
- Removed: build orchestration targets (start-builder, copy-source, run-cmake, etc.)
- Removed: artifact copying (handled internally by multi-stage build)
- Focus: Build images only (build, build-builder, build-runtime, clean, help)
- All runtime operations delegated to docker-compose.yml

### Documentation (docker/README.md)
- Completely rewritten for new two-stage architecture
- Added "Build System Components" section with file structure
- Documented why both runtime stages use builder base (library path compatibility)
- Updated build commands to use Makefile
- Updated runtime commands to use docker-compose
- Added comprehensive troubleshooting section
- Added build time and image size tables
- Reference to archived single-stage design

## Key Design Decision

**Problem**: Compiled binaries have hardcoded library paths
**Solution**: Use ollama37-builder as base for BOTH compile and runtime stages
**Trade-off**: Larger image (~18GB) vs guaranteed library compatibility

## Benefits

-  Cleaner separation of concerns (builder env vs compilation vs runtime)
-  Builder image cached after first build (90 min → <1 min rebuilds)
-  Runtime rebuilds only take ~10 min (pulls latest code from GitHub)
-  No library path mismatches (identical base images)
-  No complex artifact extraction (multi-stage COPY)
-  Simpler Makefile focused on image building
-  Runtime management via docker-compose (industry standard)

## Files Changed

Modified:
- docker/builder/Dockerfile - Added comments, removed COPY config files
- docker/runtime/Dockerfile - Converted to two-stage build
- docker/Makefile - Simplified to focus on image building only
- docker/README.md - Comprehensive rewrite for new architecture

Deleted:
- docker/builder/README.md - No longer needed
- docker/builder/cuda-11.4.sh - Generated in Dockerfile
- docker/builder/gcc-10.conf - Generated in Dockerfile
- docker/builder/go.sh - Generated in Dockerfile

Archived:
- docker/Dockerfile → docker/Dockerfile.single-stage.archived

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Shang Chieh Tseng
2025-11-10 13:14:49 +08:00
parent 6dbd8ed44e
commit 4810471b33
9 changed files with 505 additions and 413 deletions

View File

@@ -1,3 +1,7 @@
# Ollama37 Builder Image
# This image provides the complete build environment for compiling Ollama with Tesla K80 (compute 3.7) support
# Includes: CUDA 11.4, GCC 10, CMake 4, Go 1.25.3
FROM rockylinux/rockylinux:8
# Install CUDA toolkit 11.4
@@ -9,13 +13,14 @@ RUN dnf -y install dnf-plugins-core\
&& dnf -y config-manager --add-repo https://developer.download.nvidia.com/compute/cuda/repos/rhel8/x86_64/cuda-rhel8.repo\
&& dnf -y install cuda-toolkit-11-4
# Post install, setup path
COPY cuda-11.4.sh /etc/profile.d/cuda-11.4.sh
# Setup CUDA path
RUN echo 'export PATH="${PATH}:/usr/local/cuda-11.4/bin"' > /etc/profile.d/cuda-11.4.sh
ENV PATH="$PATH:/usr/local/cuda-11.4/bin"
#ENV LD_LIBRARY_PATH="$LD_LIBRARY_PATH:/usr/lib64:/usr/local/lib64"
# Install gcc 10
RUN dnf -y install wget unzip bzip2\
# Install GCC 10 from source
# CUDA 11.4 requires GCC 10 maximum (enforced in host_config.h)
# GCC 11+ is incompatible with CUDA 11.4
RUN dnf -y install wget unzip bzip2 git\
&& dnf -y groupinstall "Development Tools"\
&& cd /usr/local/src\
&& wget https://github.com/gcc-mirror/gcc/archive/refs/heads/releases/gcc-10.zip\
@@ -28,17 +33,16 @@ RUN dnf -y install wget unzip bzip2\
&& make -j $(nproc)\
&& make install
# Post install, setup path
#COPY gcc-10.sh /etc/profile.d/gcc-10.sh
#ENV LD_LIBRARY_PATH="$LD_LIBRARY_PATH:/usr/lib64:/usr/local/lib64"
COPY gcc-10.conf /etc/ld.so.conf.d/gcc-10.conf
RUN ldconfig\
# Setup GCC 10 library path and update system compiler
# Configure ldconfig to find GCC 10 runtime libraries
# Replace default cc symlink to use our custom GCC 10
RUN echo '/usr/local/lib64' > /etc/ld.so.conf.d/gcc-10.conf\
&& ldconfig\
&& rm -f /usr/bin/cc\
&& ln -s /usr/local/bin/gcc /usr/bin/cc
# Install cmake
#ENV LD_LIBRARY_PATH="/usr/local/nvidia/lib:/usr/local/nvidia/lib64"
#ENV PATH="/usr/local/nvidia/bin:/usr/local/cuda/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
# Install CMake 4 from source
# Required for modern CMake features and CUDA architecture configuration
RUN dnf -y install openssl-devel\
&& cd /usr/local/src\
&& wget https://github.com/Kitware/CMake/releases/download/v4.0.0/cmake-4.0.0.tar.gz\
@@ -49,11 +53,11 @@ RUN dnf -y install openssl-devel\
&& make -j $(nproc)\
&& make install
# Install go
# Install go 1.25.3
RUN cd /usr/local\
&& wget https://go.dev/dl/go1.25.3.linux-amd64.tar.gz\
&& tar xvf go1.25.3.linux-amd64.tar.gz
# Post install, setup path
COPY go.sh /etc/profile.d/go.sh
# Setup Go path
RUN echo 'export PATH="${PATH}:/usr/local/go/bin"' > /etc/profile.d/go.sh
ENV PATH="$PATH:/usr/local/go/bin"