Building and Testing Traefik

Set up your development environment, build Traefik from source, and run tests locally.

Building and Testing Traefik

This guide will help you compile your own Traefik binary from source and run the test suite locally.

Prerequisites

Before you begin, ensure you have the following tools installed:

Required Tools

• Docker - For building images and running integration tests
• make - Build automation tool
• Go - Go programming language (check .go-version file for required version)
• misspell - Spell checker for code
• shellcheck - Shell script linter

Docker Desktop Users: If you’re using Docker Desktop, you’ll also need Tailscale for certain integration tests.

Verify Installation

Check that your tools are properly installed:

Go Version

go version
# Should match version in .go-version file

Environment Setup

Clone the Repository

Recommended Location: Clone Traefik into ~/go/src/github.com/traefik/traefik. This follows the official Go workspace hierarchy and ensures dependencies resolve properly.

mkdir -p ~/go/src/github.com/traefik
cd ~/go/src/github.com/traefik
git clone https://github.com/traefik/traefik.git
cd traefik

Configure Go Environment

Set your GOPATH and PATH environment variables:

export GOPATH=~/go
export PATH=$PATH:$GOPATH/bin

Persist Settings: Add these exports to your .bashrc or .bash_profile to make them permanent.

Verify Environment

Run go env to verify your setup:

go env

You should see output similar to:

GOARCH="amd64"
GOBIN=""
GOEXE=""
GOHOSTARCH="amd64"
GOHOSTOS="linux"
GOOS="linux"
GOPATH="/home/yourusername/go"

Building Traefik

Generate WebUI Assets

Traefik includes a web UI that needs to be built first:

1. Build WebUI Docker Image

   make build-webui-image
   
2. Generate WebUI Static Files

   make generate-webui
   

   This creates static assets in webui/static/

Build the Binary

Now you can build the Traefik binary:

make binary

This command:

1. Runs code generation (make generate)
2. Generates WebUI assets (make generate-webui)
3. Compiles the binary with version information

The build process uses CGO_ENABLED=0 to create a static binary that doesn’t depend on C libraries.

Build Output

After building, you’ll find the executable in the dist directory:

ls dist/
# Output: dist/linux/amd64/traefik (or your platform)

You can run it directly:

./dist/linux/amd64/traefik version

Platform-Specific Builds

Build for specific platforms:

Linux ARM64

make binary-linux-arm64

Quick Build (Development)

For faster development iterations, use the default target:

make default

This runs make generate and make binary but skips WebUI regeneration if already built.

Running Tests

Test Suite Overview

Traefik has three main test suites:

• Unit Tests - Fast tests for individual packages
• Integration Tests - Tests with real infrastructure (Docker, Kubernetes, etc.)
• WebUI Unit Tests - Tests for the web interface

Run All Tests

make test

This runs all test suites: test-ui-unit, test-unit, and test-integration.

Unit Tests

Run only the unit tests:

make test-unit

Example output:

GOOS=linux GOARCH=amd64 go test -cover "-coverprofile=cover.out" -v ./pkg/... ./cmd/...
ok      github.com/traefik/traefik/v3/pkg/config   0.005s  coverage: 4.1% of statements
Test success

Integration Tests

Run integration tests (requires Docker):

make test-integration

Test Duration: Integration tests can take 20+ minutes as they spin up real infrastructure.

Pull Required Images

To avoid timeouts, pull Docker images before running integration tests:

make pull-images

Run Specific Tests

Run a specific test suite or test:

Specific Suite

TESTFLAGS="-test.run TestAccessLogSuite" make test-integration

WebUI Tests

Run WebUI unit tests:

make test-ui-unit

Gateway API Conformance Tests

Test Kubernetes Gateway API compatibility:

make test-gateway-api-conformance

This requires building a Docker image first with make build-image-dirty.

Knative Conformance Tests

Test Knative compatibility:

make test-knative-conformance

Code Validation

Linting

Run the linter using golangci-lint:

make lint

Traefik uses comprehensive linting rules defined in .golangci.yml, including:

• gofumpt - Stricter gofmt
• gci - Import organization
• govet - Go vet checks
• errcheck - Error handling verification

File Validation

Validate code and documentation:

make validate-files

This checks:

• Misspellings in code and docs
• Shell script syntax
• Vendor dependencies

Complete Validation

Run all validation checks:

make validate

This runs both make lint and make validate-files.

Pre-Commit Checklist

Before submitting a pull request, run these commands locally:

1. Generate Code

   make generate
   

   Generates dynamic and static configuration documentation.

2. Generate CRDs

   make generate-crd
   

   Generates Kubernetes CRD clientset and manifests.

3. Validate Code

   make validate
   

   Runs linters and file validation.

4. Pull Images

   make pull-images
   

   Ensures integration test images are ready.

5. Run Tests

   make test
   

   Runs all test suites.

Your PR will not be reviewed until all these checks pass on CI. Running them locally first saves time and ensures faster review.

Building Docker Images

Build Development Image

Build a local Docker image for testing:

make build-image

This:

1. Cleans the WebUI static directory
2. Builds binaries for linux/amd64 and linux/arm64
3. Creates a Docker image tagged traefik/traefik:latest

Quick Image Build

If you’ve already built the WebUI:

make build-image-dirty

This skips WebUI regeneration for faster builds.

Multi-Architecture Images

Build for multiple architectures:

make multi-arch-image-latest

Code Generation

Generate Configuration Docs

make generate-genconf

Generates code from dynamic configuration using github.com/traefik/genconf.

Generate CRD Resources

make generate-crd

Generates:

• Kubernetes CRD clientset
• CRD manifest files

Code Formatting

Format your code before committing:

make fmt

This runs gofmt with the -s flag for simplification.

Docker Desktop + Tailscale Setup

If you’re using Docker Desktop, some integration tests require Tailscale:

1. Create Auth Key

   Create a tailscale.secret file in the integration directory with a Tailscale auth key (ephemeral, reusable recommended).

2. Configure ACLs

   Add this to your Tailscale ACLs to auto-approve routes:

   "autoApprovers": {
     "routes": {
       "172.31.42.0/24": ["your_tailscale_identity"]
     }
   }
   

Troubleshooting

Build Fails

• Ensure Go version matches .go-version
• Check that GOPATH is set correctly
• Verify all dependencies are installed

Tests Timeout

• Run make pull-images before integration tests
• Check Docker is running and has sufficient resources
• For specific tests, use TESTFLAGS to run a subset

Linter Errors

• Run make fmt to auto-format code
• Check .golangci.yml for specific linter rules
• Fix errors one by one or disable specific rules if appropriate

Next Steps

Now that you can build and test Traefik:

1. Review the Contribution Guidelines for code standards
2. Pick an issue to work on
3. Make your changes and run the validation steps
4. Submit a pull request!

Additional Make Targets

View all available make targets:

make help

This displays all targets with descriptions.