Skip to main content

Migrate from Traefik Proxy on Docker

This guide walks you through migrating an existing Traefik Proxy Docker deployment to Traefik Hub API Gateway. The migration process preserves your existing configuration while adding Hub capabilities.

Before You Begin​

Before starting the migration, ensure you have a basic understanding of Docker and Docker Compose. You should have an existing Traefik Proxy v3+ installation running on Docker.

Make sure that you have the following:

Migration Overview​

The migration process involves three main steps:

  1. Obtain a Traefik Hub token from the Hub Dashboard to use licensed Hub features. Alternatively, skip it to run Traefik Hub in Proxy Mode. This means that you can access Traefik Proxy features but not Hub features, till you apply a valid license. Add a token later without redeploying.
  2. Update your Docker configuration to use the Traefik Hub image, adding the token if you have one.
  3. Deploy the updated configuration using Docker Compose.

The Hub API Gateway maintains full compatibility with existing Traefik Proxy configurations, requiring only an image change. Add the Hub license token as well if you want licensed Hub features.

Docker Swarm

This guide can also be used to migrate from Traefik Proxy on Docker Swarm.

Step 1: Obtain Your Traefik Hub Token (Optional)​

Skip this step if you don't have a Hub token yet. You'll run Traefik Hub in Proxy Mode instead, and you can add a token later without redeploying.

Log in to the Traefik Hub Online Dashboard and create a new Hub Gateway. If you don't yet have a Traefik Hub account, reach out to our sales team.

Copy only the token value and save it for the next step.

Store the token in an environment variable for convenient reference:

export TRAEFIK_HUB_TOKEN=your-token-from-hub

Replace your-token-from-hub with the actual token you copied from the Dashboard.

Step 2: Update Your Docker Configuration​

Basic Migration​

If you're using a Docker run command, update it as follows:

docker run -d \
  --name traefik \
  -p 80:80 \
  -p 443:443 \
  -p 8080:8080 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  traefik:v3 \
  --providers.docker \
  --api.dashboard=true \
  --entrypoints.web.address=:80 \
  --entrypoints.websecure.address=:443
Traefik Hub in Proxy Mode

If you don't have a Hub token yet, you can remove the hub.token parameter and deploy. This will install Traefik Hub in Proxy mode. This means that you can now access Traefik Proxy features but not Hub features, till you apply a valid license.

Docker Compose Migration​

For Docker Compose setups, update your docker-compose.yml file:

docker-compose.yml
services:
  traefik:
    image: traefik:v3
    container_name: traefik
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
      - "8080:8080"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - ./traefik.yml:/traefik.yml:ro
    command:
      - --providers.docker=true
      - --providers.docker.exposedbydefault=false
      - --entrypoints.web.address=:80
      - --entrypoints.websecure.address=:443
      - --api.dashboard=true

Replace ${TRAEFIK_HUB_TOKEN} with the Traefik Hub token from your new Gateway, or omit the --hub.token line to stay in Proxy Mode, as with the previous example. Passing the Hub token as an environment variable is recommended for security. See the Docker Compose environment variables guide for details.

Install Configuration File​

Alternatively, you can configure all parameters in a traefik.yml install configuration file instead of using command line arguments:

api:
  dashboard: true

entryPoints:
  web:
    address: ":80"
  websecure:
    address: ":443"

providers:
  docker:
    exposedByDefault: false

hub:
  token: YOUR_HUB_TOKEN_HERE

Omit the hub section entirely to run in Proxy Mode instead.

warning

When using a configuration file, all parameters must be defined in the file. You cannot mix install file configuration with command line arguments.

This approach keeps your Docker commands cleaner and centralizes configuration in a single file.

FIPS 140-3 compliance​

Traefik Hub can be used in a FIPS 140-3 compliant mode. Refer to the FIPS Compliance Reference document for details. Your Traefik Hub license must include the FIPS feature. Contact the sales team to add it.

Checking your subscription…

Network Connectivity​

By default, Traefik Hub API Gateway operates in connected mode and requires communication with the Traefik Hub online platform for license validation and feature synchronization. Please refer to the networking documentation for the connectivity requirement.

If your environment has strict firewall egress rules or limited internet connectivity, you can configure Traefik Hub API Gateway to run in offline mode. This allows the gateway to function without continuous connection to the Hub platform while maintaining core functionality.