Installing Portainter

for Graphical Docker container management

Portainer logo Portainer logo

See official Portainer installation documentation for Community Edition on Linux with Docker Swarm

A vanilla installation of Docker can be entirely managed through Docker’s command line tools, however graphical tools like Portainer offer a GUI representation of commands and are preferred by some administrators. Portainer’s GUI is a webgui, providing the additional benefit of managing your Docker installation through a web browser instead of a locally installed app.

Portainer is offered in a free community-support-only edition (Portainer CE) and an edition for business with paid tiers and direct support (Portainer BE). The business edition includes features that aren’t available in the community edition, though these features are typically of interest for business computing environments, including: tying to centralized access management systems, additional security and reporting, and auditing features. All editions of Portainer also support Docker Swarm, Kubernetes, and Azure ACI.

Installation

Portainer can be run with a one-line Docker command, however since I like to launch Portainer without needing to remember all the options, using a Docker Compose file is much better. This also allows me to add comments (like the previous image version of Portainer that I had running before I did an update) and provides a visually organized layout for the options I use.

Prerequisites

  • Docker Volume: I created a persistent volume to hold the data that Portainer uses to run, including the database it creates. If you’re starting from a fresh Docker or Portainer installation then you’ll need to create the Docker volume first; for all other runs of Portainer you’ll be referencing your previously created persistent volume.

docker volume create: replace portainer_data with whatever name you want for the volume, but be sure to continue replacing it in upcoming commands as well

docker volume create portainer_data
  • Docker Network: I prefer to keep network traffic for each container separated all the way through the network to the external firewall. In order to do this, separate Docker networks are created and VLAN tags specified. The Portainer container is also isolated into its own VLAN, so if you follow this same network design and you’re starting fresh you’ll need the following command. If you prefer standard Docker networking, where each container is connected to the network by specifing a port on the Docker host to expose, then you can skip this step (however my commands do not include the options for exposing docker host ports - see official Docker documentation here and official Portainer documentation here).

docker network create: be sure to set your own values for subnet, gateway, and parent (which should be the name of your network adapter that connects the docker host with your VLAN). portainer_network should be whatever name you want docker to know the network as.

docker network create --driver=macvlan --subnet=192.168.0.0/24 --gateway=192.168.0.1 -o parent=eth38.23 portainer_network
Note

See my short discussion on my preference for macvlan Docker networks when separating containers into externally routed VLANs here. TL;DR it enables secure isolation of containers when managing through an external firewall

  • Certificate: I also wanted the Portainer webgui to use proper HTTPS, however I’m not serving the webgui to the internet and can’t (and don’t want to) pull a LetsEncrypt certificate. A self-signed certificate would still throw an error in my browser (unless I also installed the certificate to my workstation), but I have a better solution since I run my own local certificate authority - i.e. generate my own server certificate and install the root certificate from my local CA. This is why you see options to include Portainer’s SSL certificate shown in the compose yaml below. Don’t forget to create and upload your certificate and key files to the Docker host! - put them in a folder named ssl/ in the directory where you have your Portainer docker-compose.yml file.

  • HTTPS: Lastly, to enable use of the certificates previously mentioned and turn on HTTPS the ’entrypoint’ section is added to the Portainer compose file. This line disables serving Portainer on HTTP while specifying the HTTPS port as 443 (Portainer’s default is port 9443).

docker-compose.yml

version: '3'

services:
  portainer:
    #image: portainer/portainer-ce:2.20.1 <-- previous version noted for easy rollback
    image: portainer/portainer-ce:2.20.2
    container_name: portainer
    restart: always
    networks:
      portainer_network:
    entrypoint:
      /portainer --http-disabled --bind-https :443
    command:
      --sslcert /data/ssl/cmgmt.crt
      --sslkey /data/ssl/cmgmt.key
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - portainer_data:/data
      - ./ssl:/data/ssl

networks:
  portainer_network:
    external: true

volumes:
  portainer_data:
    external: true

Starting and Stopping the Docker compose

This section assumes that you have Docker Compose available in your Docker host somehow. Contemporary Docker installation can include a native plugin to enable Docker Compose - in the past this would have required obtaining the source and running Docker Compose separately. See my article for Installing Docker to see how I add Docker Compose.

Once you have Docker Compose available make sure your current directory is the one containing your Portainer Docker Compose yaml file (docker-compose.yml), and your SSL directory containing your certificate and key inside.

Starting Portainer

docker-compose up -d

Stopping Portainer

docker-compose down