Boost your Homelab Setup with Traefik Hub Part I: Portainer
Over the last few years, container management evolved a lot. We got better tooling, more providers, and more hosting options. Still, publishing container-based applications can be complicated and stressful.
Now, imagine that you run a homelab setup based on Docker and Docker Compose, and you’re looking for a way to manage your container environment remotely. Traefik Hub is the way to go!
Traefik Hub is a cloud native networking platform that effortlessly publishes and secures containers at the edge instantly. It provides a secured gateway to your services running on Docker Swarm or Kubernetes, taking away most of the difficulties related to publishing and securing applications.
And while Traefik Hub is super simple and straightforward to use, I still think that it is important to provide you with tutorials on how to leverage Traefik Hub in a variety of scenarios.
In our homelab & Traefik Hub series, we are going to dive deeper into the use of Hub with different technologies and setups. The first use case we will be looking at today is how to use Traefik Hub to publish and connect to a locally running Portainer instance.
Let’s get right to it!
What is Portainer
Portainer is a lightweight, easy-to-use Web UI for container management that helps you manage your local and remote Docker hosts, and takes away the complexity of having to use a CLI (Command-line interface). It follows the KISS principle, is quick to set up, and is super easy to use. The fact that it is innately simple to use — and provides seamless integration and setup with Docker and Kubernetes — makes Portainer one of the most loved and trusted container technologies, both by the community and big companies.
Portainer offers two different editions, Community Edition (CE) and Business Edition (BE). For the purposes of this tutorial, I will be using the Portainer CE.
⚠️ Note: The example configuration I use in this tutorial is not suited for production, as I only use minimal configuration for my example setup. This article does not contain topics such as using the Portainer API or setting up multiple environments. Please do not use this example setup and configuration in production! Head over to the official Portainer documentation to learn more about best practices for setting up Portainer for production.
To follow along with this tutorial, you will need the following:
- A registered account on Traefik Hub
- Docker, and Docker Compose installed on your machine
- Basic knowledge of using a Docker, Docker Compose, and a Command-line interface (CLI)
Note: This article is based on macOS; if you use Windows, you may need to adjust accordingly.
Step I: Setting up Portainer
Let’s start by using Docker Compose to deploy a local Portainer instance. Use the CLI to create the project structure, open a terminal window and create a project directory.
Now use the
cd command to change into this directory:
This will be your working directory for this tutorial, and you will run all terminal commands here.
Save the following snippet as
docker-compose-portainer.yaml. At the time of writing, the latest Portainer version is 2.17.1.
version: "3.9" 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"
This Docker Compose file will start a Portainer container based on the Portainer Community Edition (v2.17.1). It mounts port 9443 (HTTPS) to your localhost, and it exposes port 9000 (HTTP) to other containers in the same network.
It also mounts the
docker.sock file and the local
portainer_data directory (created by Docker Compose) for data persistence.
Your project structure should look like this:
├── portainer │ └── docker-compose-portainer.yaml
Excellent! You created the base structure and your first configuration file is in place. Now, let’s start the Portainer instance and get ready to set it up.
To start the container, run the following command in the terminal. It will start the container in detached (background) mode.
docker-compose -f ./docker-compose-portainer.yaml up -d
Depending on your machine and network connection, this will take a moment. You can check to see whether the Portainer container has started by running
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
After you have confirmed that the container is running, browse to
https://localhost:9443 and follow the steps in the browser to finish the initial Portainer setup.
Note: Portainer uses a self-signed SSL certificate to secure the web interface via HTTPS. Because of this, you will see a warning in your browser window.
In the next steps, you need to create the base configuration for Portainer. For more information about the configuration, please refer to the official Portainer documentation about the initial configuration.
Choose a username and a secure password, and select Create user.
Select Get Started in the dashboard to start using Portainer with your local Docker environment. The installation process automatically detects your local environment and sets it up.
Once installation is complete, your local Docker environment shows your containers.
And that, folks, is how you successfully use Docker Compose to spin up Portainer!
Step II: Installing the Traefik Hub agent
Now that you have Portainer up and running, it is time to deploy Traefik Proxy and the Traefik Hub agent.
First things first — log in to Traefik Hub and create your first agent by selecting Install my first Traefik Hub Agent and choose
Docker-compose as Platform.
Once you are logged in and you have selected
Docker-compose, the Traefik Hub UI will generate a code snippet with your token. Copy this code blog and paste it into your open terminal window.
This will create a Docker Compose file called
docker-compose-hub-agent.yaml and will start the Traefik Proxy and agent containers in background mode.
Your project structure in the terminal should look like this:
├── portainer │ ├── docker-compose-hub-agent.yaml │ └── docker-compose-portainer.yaml
Name the agent and save it, then select Go to the Agent Details.
I highly recommend you use a name that clearly identifies the service, but, of course, this is up to you and you can use whatever name you like!
In the service overview, you will see three listed services, all of them with the prefix
These are the services that are configured in the two Docker Compose files. 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, hence the
portainer-portainer under services — this is the Portainer instance you want to publish — and click
Publish the service.
Note: Make sure to use port 9000; this is the port you configured in the Portainer Docker Compose file.
Traefik Hub will automatically create and use an SSL certificate for the connection.
By default, Docker Compose sets up a single network for your application. 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.
Once again, 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_default — which was created by Docker Compose — and select
Save and Publish.
After a few moments, your service will be ready and published.
For the last part of this process, head over to the domain name shown in the UI and log in to Portainer.
Once you are logged in, you will see your Portainer dashboard.
That’s all! You successfully deployed a Portainer instance locally and made it remotely accessible via Traefik Hub.
Check our documentation to learn more about using Traefik Hub with custom domain names.
A note about Access Control Policies
Currently, it is not possible to use one of Traefik Hub’s most awesome features, Access Control Policies (ACPs), with Portainer. The reason for that is the way authentication works in Portainer.
For more information, please check the related GitHub issues 3893 and 6866. Of course, we will update this article once these issues are fixed!
If you want to learn more about access control and Traefik Hub, I recommend your check out the following sources.
- Achieve Zero Downtime Access Control for Your Applications
- Traefik Hub in a World of GitOps
- Create a secured gateway for your applications
Coming up next
In this first part of our homelab & Traefik Hub series, we covered 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
Stay tuned for Part II of the series, where I’ll walk you through how to use Traefik Hub with blog engines like Ghost and WordPress.