Skip to main content

Install Traefik Hub Gateway on Linux

Prerequisites​

You should have access to a working virtual machine/host, either on a cloud provider or on your own infrastructure.

Make sure that you have the following installed:

  • systemd
  • Traefik Hub binary
  • A Traefik Hub Gateway token to use licensed Hub features. If you don't have one yet, skip it to run Traefik Hub in Proxy Mode. This means that you can access Traefik Proxy features but not Hub features, until you add a valid token. You can add it later without redeploying.
  • Networking requirements if you're using a token and validating it online, so the gateway can reach Traefik Hub. For environments without outbound access, see Offline Mode.

Install with Systemd​

  1. Download the Traefik Hub binary for your architecture from the releases page:
curl -L -o traefik-hub.tar.gz https://github.com/traefik/hub/releases/download/<version>/traefik-hub_<version>_linux_amd64.tar.gz
tar -xzf traefik-hub.tar.gz
sudo mv traefik-hub-linux-amd64 /usr/local/bin/traefik-hub
  1. Create the traefik-hub system user and group, the configuration directory, and the log directory. The service in the next step runs as the traefik-hub user, and the gateway writes and rotates its log in /var/log/traefik-hub/:
sudo groupadd --system traefik-hub
sudo useradd --system --gid traefik-hub --no-create-home --shell /usr/sbin/nologin traefik-hub
sudo mkdir -p /etc/traefik-hub
sudo mkdir -p /var/log/traefik-hub
sudo chown traefik-hub:traefik-hub /var/log/traefik-hub
  1. Copy and paste the following instructions in /etc/systemd/system/traefik-hub.service:
Install Traefik Hub API Gateway
[Unit]
Description=Traefik Hub
After=network-online.target
Wants=network-online.target systemd-networkd-wait-online.service

[Service]
Restart=on-abnormal
User=traefik-hub
Group=traefik-hub
ExecStart=/usr/local/bin/traefik-hub --configfile=/etc/traefik-hub/traefik-hub.toml
; Use private /tmp and /var/tmp, which are discarded after traefik stops.
PrivateTmp=true
; Hide /home, /root, and /run/user. Nobody may have access to SSH-keys.
ProtectHome=true
; Make /usr, /boot, /etc and possibly some more folders read-only.
ProtectSystem=full
; The following additional security directives only work with systemd v229 or later.
; They further restrict privileges that can be gained by traefik. Uncomment if you like.
; Note that you may have to add capabilities required by any plugins in use.
CapabilityBoundingSet=CAP_NET_BIND_SERVICE
AmbientCapabilities=CAP_NET_BIND_SERVICE
NoNewPrivileges=true

[Install]
WantedBy=multi-user.target
  1. Create the configuration file at /etc/traefik-hub/traefik-hub.toml:
Traefik Hub API Gateway config file
[hub]
  token = "YOUR-TRAEFIK-HUB-TOKEN"

[entryPoints]
  [entryPoints.web]
    address = ":80"

  [entryPoints.websecure]
    address = ":443"

[log]
  level = "INFO"
  filePath = "/var/log/traefik-hub/traefik-hub.log"

# Enable API and dashboard
[api]

# Enable ping
[ping]

Replace YOUR-TRAEFIK-HUB-TOKEN with the token provided by Traefik Labs, or remove the [hub] token = "YOUR-TRAEFIK-HUB-TOKEN" line entirely to run in Proxy Mode.

The configuration file contains your token. Limit read access to root and the traefik-hub group:

sudo chown root:traefik-hub /etc/traefik-hub/traefik-hub.toml
sudo chmod 640 /etc/traefik-hub/traefik-hub.toml

For the full list of log options, including log rotation, see Logs and AccessLogs.

  1. Reload the daemon, enable, and start the service:
sudo systemctl daemon-reload
sudo systemctl enable traefik-hub
sudo systemctl start traefik-hub
  1. Check the service status:
sudo systemctl status traefik-hub
Troubleshooting: The gateway doesn't write to /var/log/traefik-hub/traefik-hub.log

Check the service output using the following command:

sudo journalctl -u traefik-hub -f

The following messages mean the traefik-hub user can't write to the log directory. The gateway keeps running, but it doesn't write logs:

zerolog: could not write event: can't make directories for new logfile: mkdir /var/log/traefik-hub: permission denied
zerolog: could not write event: can't open new logfile: open /var/log/traefik-hub/traefik-hub.log: permission denied

Create the log directory, give the traefik-hub user ownership of it, and restart the service:

sudo mkdir -p /var/log/traefik-hub
sudo chown traefik-hub:traefik-hub /var/log/traefik-hub
sudo systemctl restart traefik-hub
Offline Mode

Working in an air-gapped environment? Want to install Traefik Hub API Gateway in an offline mode?

Check out the Offline Mode documentation.

Related Content​