Portainer

Tutorial

Introduction¶

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:

An account registered on the Traefik Hub platform
Docker installed
Docker Compose

Important

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.

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.

Save the token in a secure place!

Select Copy and save your token.

1.1 Name the Agent¶

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

2. Portainer¶

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

version: "3.9"
### Services ###
services:
  # Portainer
  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
    security_opt:
      - "no-new-privileges:true"
    ports:
      # Make HTTPS port (9443) reachable from localhost
      - "9443:9443"
    expose:
      # Expose HTTP port (9000) to make it accessible for other containers in the same network
      - "9000"
    volumes:
      # 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"
    networks:
      - portainer_traefik-hub

### NETWORKS ###
networks:
  portainer_traefik-hub:
    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, 0.0.0.0:9443->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.

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.

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.

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

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.

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

Summary¶

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¶

Take the free Traefik Academy class about effortless and secure publishing with Traefik Hub
Browse the through documentation to learn more about Hub