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.

Please 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
  2. Update your Docker configuration to use the Traefik Hub image and token
  3. Deploy the updated configuration using Docker Compose

The Hub API Gateway maintains full compatibility with existing Traefik Proxy configurations, requiring only the addition of the Hub license token and image change.

Docker Swarm

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

Step 1: Obtain Your Traefik Hub Token​

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

warning

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 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

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
info

You must pass the token to the Traefik Hub API Gateway using the --hub.token command line argument.

Environment Variables

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
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-2 Compliance

Traefik Hub API Gateway is FIPS 140-2 compliant. You can use the dedicated image with the tag v3-fips.

More information in the dedicated installation guide

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.