Building Rancher from Source

This guide covers building Rancher from source code, including development setup, build configuration, and testing procedures.

Prerequisites

Required Tools

Go 1.22+: Installation guide
Docker: For building container images
Docker Buildx: For cross-platform builds
kubectl: Kubernetes CLI tool
Helm 3: For deploying Rancher
Make: Build automation
Git: Version control

Optional Tools

k3d: For local Kubernetes clusters (Installation)
Dapper: Build environment tool

Build Configuration

Build Variables File

Location: build.yaml All build variables are defined in a single source of truth:

# Example build.yaml structure
webhookVersion: 2.0.6+up0.3.6-rc1
fleetVersion: 0.9.0
systemAgentVersion: 0.3.15-rc.3

Source: docs/build.md This file contains:

Component versions
Dependency versions
Build-time constants
Environment variable defaults

Updating Build Variables

Edit build.yaml:
```
vi build.yaml
```
Regenerate Go constants:
```
go generate
```
Rebuild:
```
make build
```

Adding New Build Variables

Add to build.yaml:
```
myNewVersion: 1.2.3
```

Update export-config script:

# In scripts/export-config
export CATTLE_MY_NEW_VERSION=$(grep -m1 'myNewVersion' < "$file" | cut -d ' ' -f2)

Run go generate:
```
go generate
```

Use in code:

import "github.com/rancher/rancher/pkg/buildconfig"

version := buildconfig.MyNewVersion

Common files that reference build variables:

scripts/build-server
scripts/build-agent
package/Dockerfile
package/Dockerfile.agent
pkg/settings/setting.go

Building Rancher

Quick Build (Local Development)

Generate a local container image for testing:

# Build for current architecture
REPO="localhost:5000/rancher" TAG="dev" make quick

Cross-platform build:

# Build for specific architecture
REPO="localhost:5000/rancher" \
  TAG="dev" \
  ARCH="amd64" \
  make quick

Supported architectures: amd64, arm64 Source: docs/development.md

Full Build

Build all components:

make build

This will:

Generate code from build.yaml
Build server binary
Build agent binary
Run code generators
Compile assets

Package for Distribution

Create distributable packages:

make package

This creates:

Docker images
Helm charts
Release artifacts

Build Targets

Available targets (from Makefile):

# CI build (full)
make ci

# Quick server image
make quick-server

# Quick agent image  
make quick-agent

# Binary only (no container)
make quick-binary-server

# K3s images
make quick-k3s-images

Development Workflow

Local Development Setup

Clone the repository:

git clone https://github.com/rancher/rancher.git
cd rancher

Install dependencies:
```
go mod download
```

Set up local Kubernetes cluster (k3d):

k3d cluster create rancher-dev \
  --api-port 6550 \
  --port '80:80@loadbalancer' \
  --port '443:443@loadbalancer'

Build and deploy:

# Build local image
REPO="localhost:5000/rancher" TAG="dev" make quick

# Push to local registry
docker push localhost:5000/rancher:dev

# Deploy via Helm (see below)

Iterative Development

Make code changes

Build incremental image:

REPO="localhost:5000/rancher" TAG="dev-$(date +%s)" make quick

Update deployment:

helm upgrade rancher rancher-latest/rancher \
  --namespace cattle-system \
  --reuse-values \
  --set rancherImage="localhost:5000/rancher" \
  --set rancherImageTag="dev-1234567890"

Hot Reload (Server Development)

For faster iteration during server development:

Build binary:
```
make quick-binary-server
```

Run locally (against remote cluster):

export KUBECONFIG=~/.kube/config
./bin/rancher --add-local=false

Deploying Custom Images

Using Helm

Deploy custom Rancher image:

helm upgrade --install rancher rancher-latest/rancher \
  --namespace cattle-system \
  --create-namespace \
  --set hostname=rancher.local \
  --set rancherImage="localhost:5000/rancher" \
  --set rancherImageTag="dev"

Additional useful flags:

--set bootstrapPassword="admin" \
--set replicas=1 \
--set debug=true \
--set extraEnv[0].name="CATTLE_DEV_MODE" \
--set extraEnv[0].value="true"

Using kubectl

Patch existing deployment:

kubectl set image deployment/rancher \
  rancher=localhost:5000/rancher:dev \
  -n cattle-system

Testing

Unit Tests

Run unit tests:

# All tests
go test ./...

# Specific package
go test ./pkg/catalogv2/...

# With coverage
go test -cover ./...

# Verbose output
go test -v ./pkg/...

Integration Tests

Location: tests/v2/integration/ Requirements (from tests/README.md):

Running Rancher instance
Admin access token
Go 1.22+
k3d for local clusters

Run integration tests:

cd tests/v2/integration
go test -v ./...

Configuration: Create cattle-config.yaml:

rancherConfig:
  host: https://rancher.local
  adminToken: token-xxxxx:xxxxxxxxxxxxxxxx
  insecure: true
  cleanup: true

Validation Tests

Location: tests/v2/validation/ Validation tests may require:

Cloud provider credentials
External service access
Specific configuration files

Check test suite README for specific requirements.

Controller Tests

Location: tests/controllers/

cd tests/controllers
make test

End-to-End Tests

Location: pkg/controllers/management/test/e2e/

cd pkg/controllers/management/test/e2e
go test -v ./...

Code Generation

Generate All

Regenerate all generated code:

go generate ./...

This generates:

Build config constants
Kubernetes client code
Deep copy methods
API schemas

Specific Generators

Build config:

go generate ./pkg/buildconfig

Kubernetes types:

# Requires code-generator tools
./scripts/generate-kubernetes-code

Using Dapper

Dapper provides a consistent build environment:

Install Dapper

make .dapper

Or manually:

curl -sL https://releases.rancher.com/dapper/latest/dapper-$(uname -s)-$(uname -m) > /usr/local/bin/dapper
chmod +x /usr/local/bin/dapper

Build with Dapper

# Use dapper for builds
dapper ci

# Specific target
dapper build

Build Optimization

Parallel Builds

Speed up Go builds:

export GOMAXPROCS=$(nproc)
go build -p $(nproc) ./...

Build Cache

Leverage Go build cache:

# Check cache location
go env GOCACHE

# Clear cache if needed
go clean -cache

Docker BuildKit

Enable BuildKit for faster Docker builds:

export DOCKER_BUILDKIT=1
make quick

Troubleshooting

Build Failures

Dependency issues:

# Update dependencies
go mod tidy
go mod download

# Verify go.mod and go.sum
go mod verify

Code generation issues:

# Regenerate all
go generate ./...

# Clean and rebuild
make clean
make build

Docker build failures:

# Clear build cache
docker builder prune -f

# Check disk space
df -h

# Clean up docker
docker system prune -a

Runtime Issues

Check logs:

kubectl logs -n cattle-system deployment/rancher -f

Debug mode:

# Enable debug logging
kubectl set env deployment/rancher \
  CATTLE_DEBUG=true \
  -n cattle-system

Performance Issues

Profile CPU:

go test -cpuprofile cpu.prof -bench .
go tool pprof cpu.prof

Profile Memory:

go test -memprofile mem.prof -bench .
go tool pprof mem.prof

Continuous Integration

Rancher uses GitHub Actions for CI: Workflows location: .github/workflows/ Local CI testing:

# Run full CI build
make ci

Best Practices

Always run go generate after changing build.yaml
Use Dapper for consistent builds across environments
Test locally before pushing
Keep dependencies updated: go get -u ./...
Run tests before committing: go test ./...
Follow Go conventions: Run gofmt and golint
Use feature branches for development
Clean up Docker images regularly
Document new build variables in comments
Tag dev images with timestamps for traceability

Build Configuration: docs/build.md
Development Guide: docs/development.md
Makefile: Makefile
Build Variables: build.yaml
Build Config Package: pkg/buildconfig/
Test Framework: tests/README.md
Contributing: See Contributing Guide

​Building Rancher from Source

​Prerequisites

​Required Tools

​Optional Tools

​Build Configuration

​Build Variables File

​Updating Build Variables

​Adding New Build Variables

​Building Rancher

​Quick Build (Local Development)

​Full Build

​Package for Distribution

​Build Targets

​Development Workflow

​Local Development Setup

​Iterative Development

​Hot Reload (Server Development)

​Deploying Custom Images

​Using Helm

​Using kubectl

​Testing

​Unit Tests

​Integration Tests

​Validation Tests

​Controller Tests

​End-to-End Tests

​Code Generation

​Generate All

​Specific Generators

​Using Dapper

​Install Dapper

​Build with Dapper

​Build Optimization

​Parallel Builds

​Build Cache

​Docker BuildKit

​Troubleshooting

​Build Failures

​Runtime Issues

​Performance Issues

​Continuous Integration

​Best Practices

​Related Resources