Getting started

This page covers the minimum to build, test, and run Traefik from this repository. For end-user installation, configuration, and operations, see the official documentation at https://doc.traefik.io/traefik/.

Prerequisites

• Go matching .go-version (currently 1.25). The Makefile expects Go on PATH.
• make. All common tasks are exposed as Makefile targets.
• Docker, if you want to build the dashboard or run integration tests.
• golangci-lint for linting (make lint).
• misspell and shellcheck for make validate-files.

Clone and build

git clone https://github.com/traefik/traefik
cd traefik
make binary

make binary runs go generate (which regenerates configuration reference docs and CRD code) and produces dist/<goos>/<goarch>/traefik.

To skip the dashboard build (useful for fast iteration):

go build -o /tmp/traefik ./cmd/traefik

The dashboard's static assets need to exist (even empty) because webui/embed.go uses //go:embed. The Makefile takes care of this; if you run go build directly and see embed errors, run make generate-webui once or copy the placeholder files in webui/static/.

Run it

The shipped sample configurations live at the repo root:

./traefik --configFile=traefik.sample.toml
# or
./traefik --configFile=traefik.sample.yml

Useful flags during development:

• --api.insecure=true exposes the dashboard on localhost:8080.
• --log.level=DEBUG makes the configuration loop verbose.
• --providers.file.directory=./conf watches a directory of YAML/TOML files for dynamic configuration.

Static configuration can come from a file, CLI flags, or environment variables. The same field name is used everywhere, e.g. entryPoints.web.address becomes --entrypoints.web.address or TRAEFIK_ENTRYPOINTS_WEB_ADDRESS. Loaders are stacked in this order in cmd/traefik/traefik.go: deprecation → file → flag → env.

Tests

Command	What it runs
make test-unit	Pure Go unit tests under ./pkg/... and ./cmd/.... Fast.
make test-integration	The full integration suite under ./integration (timeout 20m). Requires Docker.
make test-ui-unit	The Vue dashboard's unit tests, run inside a Docker container.
make test-gateway-api-conformance	Gateway API conformance tests against a built image.
make test-knative-conformance	Knative serving conformance tests.
make lint	golangci-lint run against .golangci.yml.
make validate-files	Vendor, misspell, and shell-lint checks.
make validate	Lint plus validate-files.

Integration tests pull a lot of Docker images. Run make pull-images once to fetch them in parallel.

Building the Docker image

make build-image

This wraps docker buildx build and uses Dockerfile at the repo root. The Makefile has dedicated targets for cross-arch builds (binary-linux-arm64, binary-linux-amd64, binary-windows-amd64).

Working on the dashboard

The Vue/Vite app is in webui/. From there:

cd webui
yarn install
yarn dev      # local Vite dev server
yarn test     # vitest
yarn build    # builds into webui/static, which is embedded in the Go binary

yarn dev proxies API calls to a running Traefik instance (configurable in webui/vite.config.ts).

Generated code

Several files are generated and should not be hand-edited:

• pkg/config/dynamic/zz_generated.deepcopy.go and pkg/tls/zz_generated.deepcopy.go — produced by controller-gen via make generate-crd.
• docs/content/reference/static-configuration/cli.md, env.md, file.md, etc. — produced by go generate at the repo root.
• pkg/provider/kubernetes/crd/generated/ — Kubernetes clientset/informers for the Traefik CRDs, regenerated by script/code-gen.sh.

Run make generate and make generate-crd when you change configuration types.

Project layout cheat sheet

Path	What lives here
cmd/traefik	Process entry point.
cmd/healthcheck	The traefik healthcheck subcommand.
pkg/config/static	Schema of the static configuration.
pkg/config/dynamic	Schema of the dynamic configuration.
pkg/config/runtime	Runtime mirror of dynamic configuration with status (used by the dashboard).
pkg/server	Lifecycle, configuration watcher, entry points, router factory.
pkg/provider/*	Each subdirectory is one provider implementation.
pkg/middlewares/*	Each subdirectory is one middleware.
pkg/muxer/{http,tcp}	Rule matchers for HTTP/TCP.
pkg/rules	Rule grammar parser.
pkg/tls	TLS manager, OCSP stapling, certificate generation.
pkg/proxy/{fast,httputil}	HTTP reverse-proxy implementations.
pkg/observability/*	Logs, metrics, tracing.
pkg/api	HTTP API consumed by the dashboard.
pkg/plugins	Wasm and Yaegi plugin loaders.
webui	Vue 3 + Vite + TypeScript dashboard.
integration	End-to-end tests that spawn a real binary.
docs	Source for https://doc.traefik.io/traefik/.

For more pointers, see Patterns and conventions.