How to install Portainer on Docker

Portainer is a con­ve­nient way to manage dis­trib­uted container en­vi­ron­ments. The software is installed as a Docker container and thus runs pretty much every­where. We show the in­stal­la­tion routine and provide useful tips.

What is Portainer?

We had already in­tro­duced Portainer as a flexible al­ter­na­tive to OpenShift. Unlike OpenShift, Portainer is not a Ku­ber­netes dis­tri­b­u­tion in its own right. Rather, the open source software cen­tral­izes 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 Ku­ber­netes de­ploy­ments. Portainer enables DevOps teams to centrally manage, configure, and secure multi-cluster en­vi­ron­ments. De­vel­op­ment teams also benefit from the software; for example, Portainer fa­cil­i­tates de­ploy­ment, man­age­ment and trou­bleshoot­ing of ap­pli­ca­tions.

Con­ve­nient­ly, Portainer is not only suitable as a man­age­ment interface for Ku­ber­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­stal­la­tion works in cloud en­vi­ron­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.

How do I install Portainer on Docker?

Let’s first look at the basic Portainer ar­chi­tec­ture. This comprises two com­po­nents that are installed in­di­vid­u­al­ly as Docker con­tain­ers:

1. A Portainer server as a cen­tral­ized instance. The Portainer server contains a database and requires a storage layer to store data. The Portainer server manages the local Docker en­vi­ron­ment and, if necessary, other en­vi­ron­ments connected via agents.
2. If necessary, multiple Portainer agents to manage ad­di­tion­al en­vi­ron­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­ni­cate 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­ni­cate with the server across network bound­aries. An encrypted TLS tunnel is used for this.

Next, we demon­strate the in­stal­la­tion of a Portainer server and agent under Docker (stand­alone). 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­stal­la­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­stal­la­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

2. Next, we verify that the Docker volume named “Portainer_data” exists:

docker volume ls

3. Now let’s move on to the in­stal­la­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 au­to­mat­i­cal­ly:

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

4. 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­ces­si­ble on the local host at the specified port. In our case, it is port 9443. Now it is time to configure the Portainer server.

Close

Close

Close

Close

Close

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­stal­la­tion uses a self-signed SSL cer­tifi­cate 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­stal­la­tion routine. Therefore, we show the process here as well:

1. First, we stop the running container of the Portainer server:

docker stop Portainer

2. Sub­se­quent­ly, we remove the container:

docker rm Portainer

3. In prepa­ra­tion for the upgrade, we download the latest Portainer server image:

docker pull cr.Portainer.io/Portainer/Portainer-ce:2.9.3

4. 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­stal­la­tion under Docker. If you want to manage multiple en­vi­ron­ments in a cen­tral­ized way, you install the agent on each machine to be connected. Since the Portainer agent is available as a Docker container, in­stal­la­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