Self-hosting | #2 | Portainer Server & Portainer Agent

This self-hosting mini series part 2, shows how to install Portainer Server and optionally Portainer Agents to quickly and easily deploy and manage your Docker containers.

Self-hosting | #2 | Portainer Server & Portainer Agent
I am not sponsored by any of the brands, software, or manufacturers mentioned in my posts. In these posts, I am not representing any party. I am simply sharing my journey, opinions, and experiences about running my home-lab environment.

I am running Docker in multiple machines, and a simple way to manage them is with Portainer Server and Portainer Agents. All you need is to install one instance of the Portainer Server, install Portainer Agents on all your other environments or nodes, and finally connect the agents to the server. This way, you can log in to your Portainer Server and deploy containers to all my servers as needed.

My use case

Most of the time, my goal is to enrich my Smart Home system (it's still pretty dumb though.) So I try out a bunch of hardware and self-hosted software to integrate them, mainly to Home Assistant, which I use as my primary smart home platform.

At the time of writing this, I have four Docker servers. I am running Intel NUC10i7FNH as my primary environment. The NUC is currently a VMware ESXi 7 host for four virtual machines. One of these VMs is an Ubuntu server running Docker. I also have an Unraid server screaming for an upgrade and two Raspberry Pis that run Docker.

To quickly spin up new software or test something, I extensively use the docker instances and the VMs. The easiest way to deploy docker containers has been using the Portainer Stack web editor. A Portainer Stack is pretty much equivalent to docker-compose. You can type in your configuration, upload your existing docker-compose files, or use a git repository or a custom template. I mainly use the web editor. I either type or paste in what I am working on and there on, it is really easy to edit or fix the content and then deploy or redeploy the stack of containers.

To go back and forth between different setups or versions, I use the ESXi snapshots and Veeam Backup & Replication to backup and revert setups/files or whole VMs if needed.

Getting started

If you only have one environment, you only need the Portainer Server, you can ignore the Portainer Agent installation.


  • The latest version of Docker is installed and working on all servers/environments
  • Administrator Access to all the servers/environments

My Docker Environments:

  • Intel NUC with virtualized Ubuntu 20.04.3 LTS (Portainer)
  • 2 x Raspberry Pi 4 with Ubuntu 21.10 (Portainer Agent)
  • UnRaid with Docker enabled (Portainer Agent)
A Tip: if you are using Windows, there is a fantastic free tool from SolarWinds, Solar-PuTTY, which you can use to SSH into your environments. You can store your sessions, share credentials between sessions, assign tags and search for your environments if you have a lot of them, and you can quickly open sessions into different tabs .. I only wish they had a Linux version or a web-based version to run in Docker.

Portainer Server

Installing Portainer in your primary instance is relatively straightforward IMHO. Just SSH into your primary instance using the tool of your choice and run the commands.

Starting from Portainer CE 2.9, HTTPS is enabled by default on port 9443, and HTTP (in port 9000) can be disabled completely after the install/upgrade.

Before you remote HTTP, make sure you have all your Agents already communicating using HTTPS.

Installing Portainer Server

Create a volume for Portainer

# volume for Portainer
docker volume create portainer_data

Download and install Portainer Server container

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 \

Check that the container is running with docker ps command

user@server:~$ docker ps

CONTAINER ID   IMAGE                          COMMAND                  CREATED       STATUS      PORTS                                                                                  NAMES             
de5b28eb2fa9   portainer/portainer-ce:2.11.0   "/portainer"             2 weeks ago   Up 9 days>8000/tcp, :::8000->8000/tcp,>9443/tcp, :::9443->9443/tcp   portainer

Upgrading Portainer Server

I would recommend always running the latest versions of the software you use, but always also remember to check the change log and breaking changes. If any of the breaking changes apply to your setup, then take the necessary actions before upgrading.

Always match the agent version to the Portainer Server version. If upgrading to Portainer 2.11.1 make sure all of your agents are also on version 2.11.1

To upgrade to the latest version, you need to stop Portainer and then remove the old version. Don't worry; all your containers and Portainer settings will stay intact unless otherwise stated in the changelog.

# stop portainer
docker stop portainer

# remove portainer
docker rm portainer

# pull the latest version
docker pull portainer/portainer-ce:2.11.1

Finally deploy the latest version

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 \

Check that the container is running with docker ps command

user@server:~$ docker ps

CONTAINER ID   IMAGE                                                  COMMAND                   CREATED                                                                                                                STATUS                  PORTS                                                                                                                                                                                                                                    NAMES
5ca3c8561951   portainer/portainer-ce:2.11.1                          "/portainer"              8 seconds ag                                                                                                       o   Up 6 seconds  >8000/tcp, :::8000->8000/tcp,>9000/tcp, :::9000->9000  

To login into Portainer, open web browser and go to https://your-server-address:9443 or http://your-server-address:9000.

Portainer Agent

Install Portainer Agent

SSH into the target environment and run the following command to deploy Portainer Agent.

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 portainer/agent:2.11.1

Adding the environment to Portainer Server

To add the environments with Portainer Agents to your Portainer Server, login to your Portainer Server and navigate to Environments.

Click Add environment and fill in the fields. If you have lots of environments you can group them and also set tags.

Upgrade Portainer Agent

To upgrade the Agent, SSH into the target environment. Stop and remove the old Agent version. Pull the latest version of the agent.

# stop portainer agent
docker stop portainer_agent

# remove portainer agent
docker rm portainer_agent

# pull the latest version
docker pull portainer/agent:2.11.1

Start the Agent with updated image

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 portainer/agent:2.11.1

Disable Portainer Server HTTP (port 900)

If you want to disable HTTP access, go to the Portainer Settings, and can force HTTPS. This will stop Portainer from listening on the port 9000 (HTTP).