Portainer is a con­veni­ent way to manage dis­trib­uted container en­vir­on­ments. The software is installed as a Docker container and thus runs pretty much every­where. We show the in­stall­a­tion routine and provide useful tips.

Tip

Use Portainer to manage your Kuber­netes clusters – on a IONOS vServer.

What is Portainer?

We had already in­tro­duced Portainer as a flexible al­tern­at­ive to OpenShift. Unlike OpenShift, Portainer is not a Kuber­netes dis­tri­bu­tion in its own right. Rather, the open source software cent­ral­ises and unifies the man­age­ment of existing cluster in­fra­struc­tures. A web-based graphical user interface is used for this purpose. In addition to the free ‘Community Edition’ (CE), there is a paid version with en­ter­prise support.

The main focus of Portainer is to unify the man­age­ment of existing Kuber­netes de­ploy­ments. Portainer enables DevOps teams to centrally manage, configure, and secure multi-cluster en­vir­on­ments. De­vel­op­ment teams also benefit from the software; for example, Portainer fa­cil­it­ates de­ploy­ment, man­age­ment and troubleshoot­ing of ap­plic­a­tions.

Con­veni­ently, Portainer is not only suitable as a man­age­ment interface for Kuber­netes; cluster or container man­age­ment based on Docker and Docker Swarm is also part of the func­tion­al scope. The software can be installed just about anywhere. Thus, the in­stall­a­tion works in cloud en­vir­on­ments, on edge devices as well as on your own on-premises computing in­fra­struc­ture. We show how to install Portainer under Docker.

Tip

Follow our demon­strat­ive Docker tutorial to set up Docker on your local system.

How do I install Portainer on Docker?

Let’s first look at the basic Portainer ar­chi­tec­ture. This comprises two com­pon­ents that are installed in­di­vidu­ally as Docker con­tain­ers:

  1. A Portainer server as a cent­ral­ised instance. The Portainer server contains a database and requires a storage layer to store data. The Portainer server manages the local Docker en­vir­on­ment and, if necessary, other en­vir­on­ments connected via agents.
  2. If necessary, multiple Portainer agents to manage ad­di­tion­al en­vir­on­ments. One instance of the Portainer agent runs on each cluster node to be managed.

Both Portainer server and agents run as con­tain­ers on existing in­fra­struc­ture. The agents com­mu­nic­ate with the server; for this to work, the server and the agents must be on the same network. Fur­ther­more, there are the edge agents, which run as instances on remote devices. What is special about edge agents is that they com­mu­nic­ate with the server across network bound­ar­ies. An encrypted TLS tunnel is used for this.

Next, we demon­strate the in­stall­a­tion of a Portainer server and agent under Docker (stan­dalone). We refer to Portainer Community Edition (CE) version 2.9.3 and use Docker Desktop as a base. Docker Desktop runs on Windows and macOS; in­stall­a­tion on Linux is nearly identical. Note that in pro­duc­tion use, servers and agents run on different machines.

In­stalling Portainer Server under Docker Desktop

Since the Portainer server is available as a Docker image, in­stall­a­tion turns out to be quite simple. We will guide you through the process step by step.

  1. First, we create a Docker volume that will contain the data managed by the Portainer server:
docker volume create Portainer_data
  1. Next, we verify that the Docker volume named ‘Portainer_data’ exists:
docker volume ls
  1. Now let’s move on to the in­stall­a­tion of the actual Portainer server. We start the server as a Docker container from its Docker image. Unless the image is local, it will be down­loaded auto­mat­ic­ally:
docker run -d -p 8000:8000 -p 9443:9443 --name Portainer \
    --restart=always \
    -v /var/run/docker.sock:/var/run/docker.sock \
    -v Portainer_data:/data \
    cr.portainer.io/portainer/portainer-ce:2.9.3
  1. Next, we check if the Docker container named ‘Portainer’ is running:
docker ps

Configure the Portainer server under Docker

If the Portainer server was installed correctly, the Portainer web interface is ac­cess­ible on the local host at the specified port. In our case, it is port 9443. Now it is time to configure the Portainer server.

Image: Splash screen when accessing the Portainer web interface for the first time
Splash screen when accessing the Portainer web interface for the first time
Image: Portainer splash screen with admin user details entered
Portainer splash screen with admin user details entered
Image: Quick Setup Wizard of the Portainer web interface
Quick Setup Wizard of the Portainer web interface
Image: Home screen of the Portainer web interface
Home screen of the Portainer web interface
Image: Dashboard of the Portainer web interface.
Dashboard of the Portainer web interface.
  1. First, we call up the Portainer web interface in the browser: https://localhost:9443.
  2. When using Portainer for the first time, we create an admin user account and then set up Portainer.

By default, the Portainer in­stall­a­tion uses a self-signed SSL cer­ti­fic­ate to secure the web interface via HTTPS. When accessed, a warning message may be displayed in the browser, depending on the browser and operating system. This can be bypassed with a few clicks, as shown in the following screen­shots.

Upgrade Portainer server under Docker Desktop

The Portainer server upgrade process is closely related to the in­stall­a­tion routine. Therefore, we show the process here as well:

  1. First, we stop the running container of the Portainer server:
docker stop Portainer
  1. Sub­sequently, we remove the container:
docker rm Portainer
  1. In pre­par­a­tion for the upgrade, we download the latest Portainer server image:
docker pull cr.portainer.io/portainer/portainer-ce:2.9.3
  1. To perform the upgrade, we restart the Portainer server container from the current image:
docker run -d -p 8000:8000 -p 9000:9000 -p 9443:9443 \
    --name=Portainer --restart=always \
    -v /var/run/docker.sock:/var/run/docker.sock \
    -v Portainer_data:/data \
    cr.portainer.io/portainer/portainer-ce:2.9.3

In­stalling Portainer agent under Docker

The Portainer agent is not needed for a local in­stall­a­tion under Docker. If you want to manage multiple en­vir­on­ments in a cent­ral­ised way, you install the agent on each machine to be connected. Since the Portainer agent is available as a Docker container, in­stall­a­tion is straight­for­ward. All you need to do is run the following command on the target system:

docker run -d -p 9001:9001 --name Portainer_agent \
    --restart=always \
    -v /var/run/docker.sock:/var/run/docker.sock \
    -v /var/lib/docker/volumes:/var/lib/docker/volumes \
    cr.portainer.io/portainer/agent:2.9.3

Reviewer

Go to Main Menu