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:
- Obtain a Traefik Hub token from the Hub Dashboard
- Update your Docker configuration to use the Traefik Hub image and token
- 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.
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.
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:
- Before (Traefik Proxy)
- After (Traefik Hub)
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 run -d \
--name traefik-hub \
-p 80:80 \
-p 443:443 \
-p 8080:8080 \
-v /var/run/docker.sock:/var/run/docker.sock \
ghcr.io/traefik/traefik-hub:v3 \
--providers.docker \
--api.dashboard=true \
--entrypoints.web.address=:80 \
--entrypoints.websecure.address=:443 \
--hub.token=${TRAEFIK_HUB_TOKEN}
Docker Compose Migration
For Docker Compose setups, update your docker-compose.yml
file:
- Before (Traefik Proxy)
- After (Traefik Hub)
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
services:
traefik-hub:
image: ghcr.io/traefik/traefik-hub:v3
container_name: traefik-hub
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
- --hub.token=${TRAEFIK_HUB_TOKEN}
You must pass the token to the Traefik Hub API Gateway using the --hub.token
command line argument.
Passing the Hub token as an environment variable is recommended for security. See the Docker Compose environment variables guide for details.
Static Configuration
You can also configure these parameters in your traefik.yml
static configuration file instead of using command line arguments. For example:
- traefik.yml
- Docker Compose
api:
dashboard: true
entryPoints:
web:
address: ":80"
websecure:
address: ":443"
providers:
docker:
exposedByDefault: false
services:
traefik-hub:
image: ghcr.io/traefik/traefik-hub:v3
container_name: traefik-hub
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:
- --hub.token=${TRAEFIK_HUB_TOKEN}
This approach keeps your Docker commands cleaner and centralizes configuration in a single file.
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.