Environment:Treeverse LakeFS Go Runtime Environment
| Knowledge Sources | |
|---|---|
| Domains | Infrastructure, Build_System |
| Last Updated | 2026-02-08 10:00 GMT |
Overview
Go 1.25+ build environment with Alpine Linux base, CGO disabled for static binaries, targeting linux/darwin/windows on amd64/arm64.
Description
This environment defines the Go toolchain requirements for building the lakeFS server (lakefs) and CLI (lakectl) binaries. The project uses Go modules with a pinned Go version of 1.25.5. Production builds use multi-stage Docker builds based on golang:1.25-alpine with CGO disabled (CGO_ENABLED=0) to produce fully static binaries. The build supports cross-compilation for multiple OS and architecture combinations.
Usage
Use this environment for building lakeFS from source, running Go tests, or developing new features. It is the mandatory prerequisite for compiling the lakefs server binary and the lakectl CLI tool. All CI/CD pipelines and local development workflows require this environment.
System Requirements
| Category | Requirement | Notes |
|---|---|---|
| OS | Linux, macOS, or Windows | Alpine 3.21 for Docker builds; Ubuntu 22.04 for CI runners |
| Hardware | amd64 or arm64 CPU | Both architectures supported via cross-compilation |
| Disk | 2GB+ free space | For Go module cache and build artifacts |
| CI Runner | ubuntu-22.04 (standard), ubuntu-22.04-8-cores (release builds) | GitHub Actions runners |
Dependencies
System Packages
- `build-base` (Alpine) or equivalent C toolchain (only for CGO-enabled local builds)
- `ca-certificates` (required in runtime image)
- `git` (required for module fetching)
Go Toolchain
- `go` >= 1.25.5 (pinned in go.mod)
Key Go Module Dependencies
- `cloud.google.com/go/storage` v1.53.0
- `github.com/aws/aws-sdk-go-v2` v1.39.2
- `github.com/Azure/azure-sdk-for-go/sdk/storage/azblob` v1.2.0
- `github.com/jackc/pgx/v5` v5.6.0 (PostgreSQL driver)
- `github.com/cockroachdb/pebble` v0.0.0-20230106 (embedded KV store)
- `github.com/spf13/viper` v1.20.1 (configuration)
- `github.com/getkin/kin-openapi` v0.131.0 (pinned; v0.132.0 has a read body bug)
Credentials
No credentials are required for the build environment itself. Runtime credentials are documented in Environment:Treeverse_LakeFS_LakeFS_Server_Environment.
Quick Install
# Install Go 1.25+ from https://go.dev/dl/
# Then build from source:
cd /path/to/lakefs
go build -o lakefs ./cmd/lakefs
go build -o lakectl ./cmd/lakectl
Code Evidence
Go version requirement from `go.mod:3`:
module github.com/treeverse/lakefs
go 1.25.5
Pinned dependency with bug comment from `go.mod:15`:
github.com/getkin/kin-openapi v0.131.0 // no not upgrade until the read body bug intruduced by v0.132.0 is fixed
Multi-stage Docker build from `Dockerfile:4-9`:
ARG BUILD_REPO=golang
ARG BUILD_TAG=1.25-alpine
ARG BUILD_PACKAGES="build-base ca-certificates"
ARG IMAGE_REPO=alpine
ARG IMAGE_TAG=3.21
Static binary build from `Dockerfile:26-29`:
RUN --mount=type=cache,target=/root/.cache/go-build \
--mount=type=cache,target=/go/pkg \
GOOS=$TARGETOS GOARCH=$TARGETARCH \
go build -ldflags "-X github.com/treeverse/lakefs/pkg/version.Version=${VERSION}" -o lakefs ./cmd/lakefs
CGO disabled for release builds from `.goreleaser.yml:15`:
env:
- CGO_ENABLED=0
Common Errors
| Error Message | Cause | Solution |
|---|---|---|
| `go: go.mod requires go >= 1.25.5` | Go version too old | Install Go 1.25.5 or newer from https://go.dev/dl/ |
| `cgo: C compiler not found` | Missing build-base on Alpine | Run `apk add build-base` or set `CGO_ENABLED=0` |
| `kin-openapi read body bug` | Upgraded to v0.132.0+ | Pin to v0.131.0 in go.mod |
Compatibility Notes
- Windows: Supported for lakectl CLI only. lakeFS server is primarily targeted at Linux.
- macOS (darwin): Supported for both amd64 and arm64 (Apple Silicon).
- Build tags: `//go:build !windows` excludes syslog on Windows (`pkg/logging/syslogs.go`). `//go:build !race` excludes certain tests under race detector (`pkg/local/sync_test.go`).