Skip to content

Advanced Installation of Traefik Enterprise Edition On-Premise

This installation guide is for experts who want to install their TraefikEE cluster (Traefik Enterprise Edition) on-premise.

Work In Progress

This documentation is a first version and will be improved in the next releases.


  • In order to start a Traefikee cluster with 1 control node and 2 data nodes, prepare 3 Virtual Machines:
    • VM1: → control-node-1
    • VM5: → data-node-1
    • VM6: → data-node-2

Virtual Machine networking

All of the virtual machines must be able to communicate with each other. Only the virtual machines which contain data nodes must be reachable from the internet.

Number of Virtual Machines

Multiple TraefikEE nodes can be installed on the same virtual machine. To allow it, each node must specify its:

  • advertise and listen address with its own port on the machine
  • sock
  • statedir

Please refer to the documentation for more details

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 directory path is /var/lib/traefikee_state.

  • The state directory's contents are used to recover a cluster's state in the event of a control node 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_v1.0.0_linux_amd64.tar.gz
# Compare this value to the one found in traefikee_checksums.txt
shasum -a256 ./traefikee_v1.0.0_darwin_amd64.tar.gz
# Compare this value to the one found in traefikee_checksums.txt
Get-FileHash -Algorithm SHA256
Extract the downloaded archive
# Compare this value to the one found in traefikee_checksums.txt
tar -zxvf traefikee_v1.0.0_linux_amd64.tar.gz
# Compare this value to the one found in traefikee_checksums.txt
tar -zxvf -a256 ./traefikee_v1.0.0_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:

Usage: traefikee [flags] <command> [<arguments>]

Use "traefikee <command> --help" for help on any command.

Install traefikeectl

The traefikeectl tool can be installed by following this documentation.

Initialize the Control Node

First, delete the statedir directory content (by default /var/lib/traefikee_state). Otherwise, the cluster will be started by keeping information from it and will be in an unexpected state.

The control node is responsible for bootstrapping the cluster with your license information. During the cluster life cycle, this node will listen to you providers API to discover the backends. It will share the backends with the data nodes which will expose them.

By default, the traefikee bootstrap command line deploys a cluster with 1 Control Node.

traefikee bootstrap \
    --advertise= \
    --listen= \
    --licensekey=fakeLicense \
Node hostname

Nodes names are equal to VM hostnames.

Customize the socket path

By default, the TraefikEE socket is created in /var/run/traefikee.sock. The option --sock allows customizing the path.

Customize the state directory

By default, the TraefikEE state directory is created in /var/lib/traefikee_state. The option --statedir allows customizing the path to the state directory.

Customize the API credential generation directory

By default, TraefikEE stores its generated credentials (certificates and keys) in ./.traefikee. The option --mtlscertsoutputdir allows customizing the path in which they are be stored.

Restoring a backup

In order to perform a backup restoration, specify the --archivepath=./your-backup.tar option instead of the --licensekey option. To find out more about the backup and restore system, see here.

API credentials

When installing your cluster, TraefikEE will generate credentials (certificates and keys) that are necessary to communicate with its API. Make sure never to loose those credentials as TraefikEE will only generate them once per cluster. If you lost them, you will need to re-install your TraefikEE cluster.

Dashboard security

The option --api allows exposing the TraefikEE dashboard on the port 8080 only on Control Nodes. TraefikEE does not manage the security to access to its dashboard.

Check if the control node started by listing the cluster nodes from the virtual machine which contains it:

traefikee list-nodes
Name                        Role
----                        --------------
control-node-1              CONTROL NODE (Current Leader)

Get the Data Node Token

Get the data node token generated by the bootstrap node:

traefikee env | grep 'DATA_NODE_TOKEN' | cut -d '"' -f2
How to use the token?

All data nodes require a token to start. The token can be stored in environment variable on each virtual machine, by setting it over SSH for example. In the following commands, the data node token has been stored in the environment variable named ${DATA_NODE_TOKEN}.

Create Data Nodes

Create the data nodes to handle your application traffic by launching the following commands on each data node virtual machine:

  • Data node 1
traefikee start-data-node \
    --peeraddresses= \
  • Data node 2
traefikee start-data-node \
    --peeraddresses= \

Check that the TraefikEE cluster contains the 2 data nodes:

traefikee list-nodes
Name                        Role
----                        --------------
control-node-1              CONTROL NODE (Current Leader)
data-node-1                 DATA NODE
data-node-2                 DATA NODE

Connect traefikeectl to the New Cluster

Configure traefikeectl to have access to the new cluster.

traefikeectl connect --onpremise.mtlscertsdir="/path/to/the/credentials" --onpremise.apiaddress="<CONTROL_NODE_IP>:55055"
Retrieving TraefikEE Control credentials...ok
Removing cluster credentials from platform...ok
Credentials saved in "$HOME/.config/traefikee/traefikee", please make sure to keep them safe as they can never be retrieved again.
✔ Successfuly gained access to the cluster. You can now use other traefikeectl commands.
Remotely connecting to an on-premise cluster

In order to access your cluster remotely with traefikeectl, you need to securely move the credentials to the file system of the machine from which you want to use traefikeectl. You can then provide the path to the certificates using the --onpremise.mtlscertsdir option. Do not forget to specify the --onpremise.apiaddress argument in order for traefikeectl to be able to communicate with the API.

One-time operation

When running traefikeectl connect, your credentials will be retrieved and it will not be possible to do it again in the future without re-installing a TraefikEE cluster. Remember to keep your credentials safe!

Check if the traefikeectl command is linked to the cluster by listing the cluster nodes:

traefikeectl list-nodes
Name                        Role             Leader
----                        ----              ------
control-node-1              Control Node      YES
data-node-1                 Data Node
data-node-2                 data Node

Deploy a Configuration

A TraefikEE cluster is created without any default configuration. To allow the control node to listen to a provider and data nodes to manage incoming Traefik, execute the following command:

traefikeectl deploy --entryPoints='Name:http Address::80' \
    --entryPoints='Name:https Address::443 TLS' \
    --defaultentrypoints=http,https \
    --consul.endpoint= \ \

The command described above allows the control node to get the backends and frontends stored in a Consul Key Value Store (reachable at the address, given to the --consul.endpoint option).

Data nodes expose these backends and frontends on the port 80 and 443 (in TLS).

Load balance between data nodes

TraefikEE does not manage load balancing between data nodes. It can be managed thanks to an IP table rule for example.

File provider

The Traefik File Provider is not implemented yet in TraefikEE.