How to Deploy the Latest Portainer Release

I’ve been working with Portainer for some time now and it has very quickly risen to the top of my favorite container management tools. And, like all good projects, Portainer frequently releases updates to the platform. However, the one thing you can’t do is simply log in to your Portainer instance, and click an upgrade button. Since Portainer is deployed as a container itself, you have to go through a few hoops to deploy the latest version.

And that’s what I’m going to show you how to do. This tutorial will assume you already have an out-of-date release of Portainer deployed. My current version is 2.11.1 and the current release is 2.13.1. This new release does include some important new features (as well as the usual bug fixes). The new features include the following:

• Kubernetes cloud provisioning (business edition only)
• Home page filtering (business and community editions)
• Registry browsing for non-admins (business edition only)
• Edge Agent Waiting Room (business edition only)
• Private registries for Edge stacks (business edition only)
• Environment variables from local system available in Edge Stacks (business and edition only)
• Enforcing strong passwords (business edition only)
• Dependency updates to resolve CVEs (business and community editions)

I want to walk you through the process of upgrading to the new release (community edition). The good news is that you shouldn’t lose any of your hard work. Of course, we’ll first back up Portainer, in case something goes a bit wrong.

With that said, let’s get to work.

Back up Portainer

The first thing we’ll do is back up our current Portainer deployment. Log into Portainer with an admin user and click Settings in the left navigation. Scroll down to the bottom of that page until you see Download backup (Figure 1).

Figure 1: The Download feature is found in the Settings window of Portainer.

We’re going to download the backup file to local storage, so click Download backup file and then click Download backup. This will save a .tar.gz file to your local storage. Make sure to save that file in a safe location and don’t lose or delete it.

Stop and Remove the Current Portainer Container

Now that we have our backup file, we can stop and remove the current Portainer container. Log in to the server hosting Portainer and locate the container ID of Portainer with the command:

docker ps -a|grep portainer

What we’ve done is pipe the output of the docker ps -a command into grep such that only those entries with portainer are displayed. You should see the container ID for the portainer deployment in the output. Stop the container with:

docker stop ID

Where ID is the ID of the Portainer container.

Next, remove the container with:

docker rm ID

Where ID is the ID of the Portainer container.

How to Deploy the Latest Version of Portainer

Now that the container has been removed, we can deploy the latest version. When I originally demonstrated deploying Portainer (see Deploy Portainer for Easier Container Management), I showed you how to do this with persistent storage using a volume named portainer_data. We’re going to make use of that same volume and deploy Portainer such that it can make use of the data.

First, we need to pull down the latest image with the command:

docker pull portainer/portainer-ce:latest

If you don’t pull down the latest version of Portainer, when you deploy the container it will use the current (outdated) image.

Once the image has been pulled down, deploy Portainer with:

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 portainer/portainer-ce

Give the container a moment to deploy and then point a web browser to http://SERVER:9443 (Where SERVER is the IP address or domain of the hosting server). You should be prompted for the Portainer login. Since we connected the deployment to our persistent storage volume, the previous login should work. And once you’ve successfully authenticated, you’ll find yourself on the Portainer Home, with all your previous work intact and the new version number clearly marked (Figure 2).

Figure 2: We’ve upgraded to the latest version of Portainer.

How to Restore a Backup

Should you find something has gone wrong and your work isn’t there, you can always restore a backup. This is only possible during a fresh deployment and is done during the installation. After deploying the Portainer container point your browser to the same address listed above and then, when prompted expand the Restore Portainer from Backup entry (Figure 3).

Figure 3: Deploying Portainer with the help of the backup we just downloaded from our previous installation.

Click Select file and navigate to the .tar.gz file you downloaded earlier. After selecting the file, click Restore Portainer and wait for the magic to happen. Once the backup has been restored, you should be able to log into Portainer and get to work.

And that, my friends, is all there is to upgrading Portainer to the latest version. No, it’s not nearly as easy as it could be but once you get the hang of it, you should be able to knock this out without any problems.