Install heimdall

Heimdall is shipped in multiple formats and architectures to suit a variety of deployment patterns. The following chapters describe the available installation options.

Source Code

You can always build a copy of heimdall by following the following instructions for your OS/environment.

Prerequisites

  • git

  • The Go programming language >= 1.25

Download

Retrieve the latest copy of heimdall source code by cloning the git repository

$ git clone git@github.com:dadrus/heimdall.git

Build with go

Build using a single line with go build

$ CGO_ENABLED=0 go build -trimpath -ldflags="-buildid= -w -s -X github.com/dadrus/heimdall/version.Version==my-custom-build"

The flags are set by intention. Using -trimpath and -buildid= as part of the -ldflags argument ensures the build is reproducible (See also Reproducible Builds). Other flags remove unused symbols and debug information.

Binary

Prebuild binaries are available with every released version on GitHub, as well as for every merged PR to the main branch. The version of the latter is set to the git SHA1. Supported operating systems/architectures are:

  • darwin/amd64

  • darwin/arm64

  • linux/amd64

  • linux/arm64

  • linux/armv6

  • linux/armv7

  • windows/amd64

For Linux and Darwin the binaries are archived with tar.gz and for Windows with zip. All archives are signed (see also Verifying Heimdall Binaries and Container Images section on how to verify the signatures).

Download

Retrieve the desired released version of heimdall binary for your operating system/architecture

ARCH=[your arch]
OS=[your os]
VERSION=[desired version]
curl -L https://github.com/dadrus/heimdall/releases/download/${VERSION}/heimdall-${VERSION}-${OS}-${ARCH}.tar.gz \
    | tar -z -x

Container Image

Heimdall utilizes a minimal container multi-arch image which you can find on DockerHub, or on GHCR. As with Binary releases, heimdall can be pulled in several flavors. These are however currently limited to the Linux OS. Supported architectures are:

  • amd64

  • arm64

  • arm/v7

All container images are rootless - so heimdall will always run as a non-root user within the container. Since Heimdall does not have any dependencies, the images are distroless as well and contain only the binary of heimdall and the settings related to the OS user and group permissions, heimdall is running with.

As with the binary distribution, all container images are signed (see also Verifying Heimdall Binaries and Container Images section on how to verify the signatures).

Prerequisites

  • Docker, Podman, or other container runtime of your choice (examples are however using docker).

Pull Image

The steps below will pull the images from DockerHub. If you want to pull them from GHCR, specify the ghcr.io registry in front of the repository.

Following tag patterns exist:

  • x.y.z[-<prerelease-identifier>] - will pull a specific tagged release.

    $ docker pull dadrus/heimdall:0.17.3 && docker run dadrus/heimdall:0.17.3 --version
heimdall version v0.17.3

  • latest - will pull the most recent tagged release.

    $ docker pull dadrus/heimdall:latest && docker run dadrus/heimdall:latest --version
heimdall version 0.17.3

Helm Chart

Heimdall can be installed using a Helm chart in just a few steps - whether you’re deploying it for the first time or upgrading an existing installation. The chart is available via a Helm chart repository hosted on GitHub or as an OCI image published to GHCR. For detailed instructions, refer to the chart documentation.

Autoscaling (HPA) is disabled by default to avoid misconfigured setups. If you enable it, be sure to define resource requests and limits appropriate for your production environment.

Prerequisites

  • A Kubernetes version >= 1.30

  • Helm 3.0+

Adding the Helm Repository

The heimdall Helm Chart is published at https://dadrus.github.io/heimdall/charts. You can add this repo with the following command:

$ helm repo add dadrus https://dadrus.github.io/heimdall/charts
$ helm repo update

Installing the Chart

This chart expects a heimdall configuration file with authentication, authorization and so on mechanisms, required for your particular setup, which can be passed by using the -f heimdall.yaml flag during the installation.

If you need to override the name of the heimdall resources such as the deployment or services, the traditional nameOverride and fullnameOverride properties are supported.

By default, heimdall requires custom resource definitions (CRDs) installed in the cluster. On first installations, these will be installed automatically.

To install the chart with the release name my-release (my-release is the name that you choose) and configure heimdall to operate in decision mode:

$ helm install my-release -f heimdall.yaml dadrus/heimdall

If you need proxy mode, install it with:

$ helm install my-release -f heimdall.yaml --set operationMode=proxy dadrus/heimdall

For more advanced configuration and details about helm values, please see the helm chart.

Post-Install Steps

Integration with Ingress

After having installed heimdall, you have to integrate it with your ingress controller. For decision mode that means setting corresponding annotations on Ingress resources to let the traffic first be verified by heimdall before it is forwarded to the upstream services by the Ingress Controller.

Nix Package Manager

See the nix package directory for instructions on how to install heimdall through the nix platform.

Last updated on Oct 25, 2025

Discover heimdall Protect an Application