Skip to content



In this tutorial, you'll learn how to use Traefik Hub to connect to a Portainer instance to manage Docker environments.

By the end of this tutorial, you'll have learned how to:

  • Use Docker Compose to run a Portainer demo setup (not suited for production)
  • Set up a Traefik Agent
  • Configure and publish a service (Portainer) through Traefik Hub

This tutorial uses the stand-alone method to install and configure the Traefik Hub Agent.

Before you begin

Before you start, please make sure to have the following:


The Portainer setup used in this tutorial only shows only a minimal needed basic configuration.

Do not use it in production!

To learn more about Portainer, please head over to the official Portainer documentation.

In this tutorial Portainer uses port 9000 (HTTP) and not port 9443 (HTTPS). The reason for that is the way how authentication works in Portainer.

Your later connection via Traefik Hub will be using HTTPS!

For security reasons it is important to first start and configure the Portainer instance.

1. Setup Traefik Hub Agent

First, open a terminal, create a directory with the name portainer and change into it. This will be your working directory for this tutorial.

Now, login to Traefik Hub and create your first Agent by selecting Install my first Traefik Hub Agent.

Choose Docker-compose as platform.

Choose Compose as platform

Select Copy and paste the code block into your CLI.

This will create a Docker Compose file called docker-compose-hub-agent.yaml and will start the Traefik Proxy and Agent container in background mode.

Install Hub Agent via Compose

Save the token in a secure place!

Select Copy and save your token.

Save the token in a secure place

1.1 Name the Agent

Name the Agent and select Save, followed by selecting Go to the Agent Details.

Name the Hub Agent

2. Portainer

Save the following code block as docker-compose-portainer.yml in the same directory (portainer).

version: "3.9"
### Services ###
  # Portainer
    # Use the Portainer image (Community Edition) v2.17.1 (at time of writing)
    image: "portainer/portainer-ce:2.17.1"
    # Specify a custom container name, rather than a generated default name.
    container_name: portainer
    # Run an init process (PID 1) inside the container that forwards signals and reaps processes.
    init: true
    # Restart a container irrespective of the exit code but will stop restarting when the service is stopped or removed
    restart: unless-stopped
    # Prevent the application processes inside the container from gaining new privileges during runtime
      - "no-new-privileges:true"
      # Make HTTPS port (9443) reachable from localhost
      - "9443:9443"
      # Expose HTTP port (9000) to make it accessible for other containers in the same network
      - "9000"
      # Add Docker as a mounted volume, so that Traefik can read the labels of other services
      - "/var/run/docker.sock:/var/run/docker.sock:ro"
      # Mount the local Portainer portainer_data directory to the data directory of the container
      - "./portainer_data:/data"
      - portainer_traefik-hub

### NETWORKS ###
    external: true

Use this Docker Compose file to bring up Portainer.

Open a terminal and run:

docker-compose -f ./docker-compose-portainer.yml up -d

You can check to see whether the Portainer container has started by running:

[email protected]:~# docker ps
CONTAINER ID   IMAGE                           COMMAND        CREATED         STATUS         PORTS                                        NAMES
ddfd5c0076d9   portainer/portainer-ce:2.17.1   "/portainer"   9 seconds ago   Up 8 seconds   8000/tcp, 9000/tcp,>9443/tcp   portainer

Once you have confirmed that the container is running, browse to https://localhost:9443 and follow the steps on the screen to finish the setup.

SSL certificate

By default Portainer uses a self-signed certificate to secure port 9443.

1.1 Set the initial administrator user

Choose a username and a secure password and select Create user.

Portainer install, choose username and password

1.2 Configure the environment

Select Get Started.

For more information, please refer to the official Portainer documentation about the initial configuration.

The installation process automatically detects your local environment and sets it up for you. Select Get Started to start using Portainer with your local Docker environment.

Setup Portainer environment

Now you will see your local Docker environment showing your containers.

3. Publish the service

Now, it's time to publish the service (your Portainer instance). Change back into the Traefik Hub UI and select portainer~portainer under services.

This is your Portainer instance you want to publish.

Choose Portainer service in UI

Select Publish the service.

Publish the service

Before you publish, check that the service port and the network are configured properly.

Make sure to use port 9000, this is the port you configured in the Portainer Docker Compose file.

By default, Docker Compose sets up a single network for your app. Each container for a service joins the default network and is both reachable by other containers on that network, and discoverable by them at a hostname identical to the container name.

Your app’s network is given a name based on the project name, which is based on the name of the directory it lives in.

Appoint the network portainer_traefik-hub, which was created by Docker Compose.

Select Save and Publish.

Service port and network

After a few moments, your service will be ready and published.

In the last step, head over to the domain name shown in the UI and login to Portainer.

Service is published

Once you are logged in, you will see your Portainer dashboard.

Login to Portainer via Traefik Hub


In this tutorial, you learned how to:

  • Use Docker Compose to run a local Portainer instance
  • Set up and configure Traefik and the Traefik Hub Agent
  • Publish a service (Portainer) with Traefik Hub

What's next