Installing Traefik Enterprise Edition On-Premise

This installation guide is for users who want to install a cluster on-premise.


In order to start a TraefikEE cluster with 1 controller and 2 proxies, ensure that:

  • There are at least 3 Hosts/Virtual Machines
  • Network stack allows communication on required ports
  • Controller Host/VM can reach
  • The teectl binary is installed, for cluster management


Only the hosts which run proxies have to be reachable from the internet. On Linux, root access is needed to bind to ports below 1024.

Default TraefikEE paths

The default configration paths for traefikee includes: - /var/run/traefikee - /var/lib/traefikee - /var/run/secrets Read and write access are required on then. See the teectl referece for customization options.

Please refer to the documentation for more information

Multiple instances on the same Host/VM

Running multiple controllers or proxies on the same host is not supported at the moment.

Installation behind a proxy

In order to be able to install TraefikEE behind a proxy, you must make sure that each TraefikEE instance has the proper HTTP_PROXY and HTTPS_PROXY environment variables defined.

State Directory Management

By default, the statedir path is /var/lib/traefikee.

  • The state directory's contents are used to recover a cluster's state in the event of a controller restart. It has to persist between two executions.
  • In order to re-initialize a cluster, you have to delete the state directory before re-installing it. If this is not done, it will recover its previous state.

Install traefikee

First, download traefikee on each virtual machine, by using one of the following links:

Check the integrity of the downloaded file

Use the sha256 checksums of the binaries:

# Compare this value to the one found in traefikee_checksums.txt
sha256sum ./traefikee_v2.2.1_linux_amd64.tar.gz
# Compare this value to the one found in traefikee_checksums.txt
shasum -a256 ./traefikee_v2.2.1_darwin_amd64.tar.gz
# Compare this value to the one found in traefikee_checksums.txt
Get-FileHash -Algorithm SHA256
Extract the downloaded archive

Use the following commands to extract the archive:

# Compare this value to the one found in traefikee_checksums.txt
tar -zxvf traefikee_v2.2.1_linux_amd64.tar.gz
# Compare this value to the one found in traefikee_checksums.txt
tar -zxvf -a256 ./traefikee_v2.2.1_darwin_amd64.tar.gz
# Compare this value to the one found in traefikee_checksums.txt

Copy the traefikee binary to your PATH or add its location to your environment ($PATH or %PATH% depending on your OS) and make sure it's executable:

# Example with /usr/local/bin
# These command may need sudo rights
cp traefikee /usr/local/bin/traefikee
chmod a+x /usr/local/bin/traefikee

# Should print "/usr/local/bin/traefikee"
command -v traefikee
# Example with C:\Program Files
Copy-Item "traefikee.exe" -Destination "C:\Program Files\traefikee.exe"

# Should print "C:\Program Files\traefikee.exe"
where traefikee

You can now test your installation by executing traefikee:

traefikee --help
traefikee    TraefikEE (Enterprise Edition) is a Cloud Native Edge Routing Platform based on Traefik,
a modern HTTP reverse proxy and load balancer made to deploy microservices with ease.
Complete documentation is available at

Usage: traefikee [command] [resource] [flags]

Use "traefikee [command] --help" for help on any command.

    controller    Start a new controller
    proxy         Start a new proxy
    tokens        Get tokens from the cluster
    version       Print version

Generating the teectl Configuration

To start the installation, teectl must first be configured:

teectl setup --onpremise.hosts="<ip1>,<ip2>,<ip3>"

The host IPs that will be used for controllers should also be set in the onpremise.hosts option.

This command creates a new teectl configuration under ~/.config/traefikee/default.yaml and generates a which carries a set of needed assets for the installation. The needs to be copied onto each controller host.

To further configure the teectl setup, please refer to the reference documentation.

Connecting to a Controller Locally

It is possible to connect to a cluster by using the socket (default /var/run/traefikee/teectl.sock) using the socket option on teectl commands. teectl must be used on the same host as a controller for this to work.

teectl get nodes --socket=/var/run/traefikee/teectl.sock

In this case, no is needed to start the Controller and the above step can be skipped.

Start the Controller(s)

Start a new controller by specifying the advertise address and TraefikEE license:

traefikee controller --advertise="" --license="<your-license-key>" --api.bundle="<path-to>/"
traefikee controller --advertise="" --license="<your-license-key>" --api.bundle="<path-to>/" --discovery.static.peers=",,"
traefikee controller --advertise="" --license="<your-license-key>" --api.bundle="<path-to>/" --discovery.dns.domain="traefikee.mydomain" --discovery.dns.port="4242" --discovery.dns.bootstrapexpected=2
INFO[2020-01-20T15:00:35-03:00] Using static discovery to discover other controllers  node=controller-0 role=controller
INFO[2020-01-20T15:00:35-03:00] Initializing a new node                       role=controller node=controller-0
INFO[2020-01-20T15:00:35-03:00] Discovering cluster                           node=controller-0 role=controller
INFO[2020-01-20T15:00:35-03:00] Found peers []                    node=controller-0 role=controller
INFO[2020-01-20T15:00:35-03:00] Initial leader runs at           node=controller-0 role=controller
INFO[2020-01-20T15:00:35-03:00] Initializing a new TraefikEE cluster          node=controller-0 role=controller
INFO[2020-01-20T15:00:35-03:00] API started                                   role=controller node=controller-0
INFO[2020-01-20T15:00:35-03:00] Node started                                  role=controller node=controller-0
INFO[2020-01-20T15:00:36-03:00] Node is ready                                 node=controller-0 role=controller
INFO[2020-01-20T15:00:36-03:00] Running the cluster info controller           service=provider node=controller-0 role=controller
INFO[2020-01-20T15:00:36-03:00] Running the cluster license controller with frequency "24h0m0s"  node=controller-0 role=controller service=cleanup
INFO[2020-01-20T15:00:36-03:00] Running the cluster cleanup controller        role=controller node=controller-0 service=cleanup

Node Name

By default TraefikEE will use the hostname as the node. This behavior can be overridden by specifying the --name flag on the controller command.

Multi Controller with DNS

When using DNS as the discovery method it is a good practice to set the flag discovery.dns.bootstrapexpected, as this will make the controllers wait until the specified number of nodes are reachable before bootstraping the cluster.

Get the Proxy Token

Get the proxy node token generated by the controller:

traefikee tokens | grep 'TRAEFIKEE_PROXY_TOKEN' | cut -d '=' -f2
How to use the token?

All proxies require a token to start. The token can be stored in an environment variable on each host machine, by setting it over SSH for example. In the following commands, the proxy token has been stored in an environment variable named ${PROXY_NODE_TOKEN}.

Start Proxies

Start a proxy by specifying the controller discovery method, static in this example, and the join token:

traefikee proxy --jointoken.value="$PROXY_NODE_TOKEN" --discovery.static.peers=""
traefikee proxy --jointoken.value="$PROXY_NODE_TOKEN" --discovery.dns.domain="traefikee.mydomain"
INFO[2020-01-20T15:09:47-03:00] Applying a new static configuration           node=proxy-0 role=proxy module=server
INFO[2020-01-20T15:09:47-03:00] Using static discovery                        node=proxy-0 role=proxy peers=""
INFO[2020-01-20T15:09:47-03:00] Discovering controllers                       node=proxy-0 role=proxy
INFO[2020-01-20T15:09:47-03:00] Found controllers []             node=proxy-0 role=proxy
INFO[2020-01-20T15:09:47-03:00] Waiting for the join tokens to be available   node=proxy-0 role=proxy
INFO[2020-01-20T15:09:47-03:00] Looking for a reachable peer                  role=proxy node=proxy-0
INFO[2020-01-20T15:09:47-03:00] Joining cluster                               role=proxy joined-peer="" node=proxy-0
INFO[2020-01-20T15:09:47-03:00] Node started                                  node=proxy-0 role=proxy
INFO[2020-01-20T15:09:47-03:00] Node is ready                                 node=proxy-0 role=proxy

Repeat the steps above for each proxy, then verify that the TraefikEE installation was successful:

teectl get nodes
ID                         NAME           STATUS  ROLE
mmc2qofw8hkudf8vcrs1k8cnw  controller-0   Ready   Controller (Leader)
oncgmk54uuipcj7jnt0lhwwqy  proxy-0        Ready   Proxy
u122z00fgr2cqrp78jc5em0fi  proxy-1        Ready   Proxy

Apply a Static Configuration

A TraefikEE cluster is created without any default configuration. To allow the controller to listen to a provider and proxies to manage incoming traffic, it is necessary to apply a static configuration.

Below is an example of a static configuration:

File provider

    address: ":80"
    address: ":443"

    filename: dynamic_conf.yml
    address = ":80"
    address = ":443"

    filename = "/etc/traefikee/dynamic_conf.toml"


When running multiple controllers, make sure to replicate the configuration file on all nodes at the same path.

Apply the configuration using the following command:

teectl apply --file=config.yaml
teectl apply --file=config.toml

What's Next?

Now that the cluster is ready, we recommend reading the various operating guides to dive into all features that TraefikEE provides.