Portainer: How to Build a Home Lab Setup

Update: Tested and Validated 30th December 2023

Portainer is a lightweight, free, open-source Docker and Kubernetes management from a Web Browser. It provides a simple and user-friendly web interface to build and manage containers, images, networks, volumes, registries, services, and nodes. Portainer is very useful for anyone learning containers, docker, and K8s.

This article will focus on the portainer community edition, please note that a business edition is available if needed. Either edition is a great platfor to manager docker or docker swarm.

This post will show you how to install Portainer Docker UI on Debian 11. You can host it on whatever platform you want, and it’s available for Windows, Raspberry Pi, Ubuntu, etc. I prefer the Debian distribution. I find it rock solid for Portainer.

My Home Lab Setup

I have a half-decent PC running headless in my office. It used to be my gaming PC, but I sold the graphics card when prices rocketed in 2021 simply because I didn’t have time to play games as often as I would like. This left me with these modest specs to play with:

Step 1 – Preparing the Local Computer for Portainer

Note: Skip to Step 2 if you are already running Debian or another Linux flavour.

As I am running Windows 10, I have opted to use a HyperV virtual machine. How you spec the server depends on how you want to use it. Docker containers are very lightweight so start low and expand later if you need to.

Windows 10 Steps

• Open Windows Features. Simply search from the start bar

• Enable HyperV Service here as they are not enabled by default on Windows 10 or 11 Note: On Windows 10 its called HyperV, on Windows 11 its called Windows Hypervisor Service

• Once Installed, reboot your computer to apply the changes.

Step 2 – Prepare Virtual Machine for Portainer

This step will show how to create the VM needed for Debian and Portainer

• Start HyperV
• Right Click on HyperV Server (typically your PC hostname) and select New > Virtual Machine.
• Give the VM a Name and set the storage location to your preference.
• Select Generation 1
• Give it at least 4096MB of Memory
• Set the VM the required CPU allocation and assign it to your network preferences
• When setting disk size, consider what you are using portainer for. For example, do you need loads of local disk? or will you be running everything from NAS? I set mine to about 250GB.
• On Install Options, select Install Operating System from bootable CD/DVD. Then click the ISO Radio button.
• Point the browser to your Debian ISO image – you can download it here.
• For Instructions on how to install Debian – see installation instructions here.

Step 3 – Install Portainer on Debian 11

After you have installed Debian. Install portainer – this is how you do it.

SSH to your new Debian server

Step 4 – Update Debian

apt-get update -y

Step 5 – Install Docker CE

Before installing Portainer, Docker CE must be installed on your server. You can install Docker CE by following the below steps. If you encounter any issues, check out the official documentation – it’s likely they’ve changed something.

First, install the required dependencies:

apt-get update
apt-get install ca-certificates curl gnupg
install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/debian/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
chmod a+r /etc/apt/keyrings/docker.gpg

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/debian \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update

Next, update the repository and install Docker CE with the following command:

apt-get install docker-ce docker-ce-cli containerd.io -y

Once Docker is installed, verify the Docker installation using the following command:

docker version

Step 6 – Install Docker Compose (optional)

You will also need to install Docker Compose to your system. First, download the latest version of Docker Compose binary using the following command:

wget https://github.com/docker/compose/releases/download/v2.2.2/docker-compose-linux-x86_64

Next, copy the downloaded binary to the system path:

cp docker-compose-linux-x86_64 /usr/local/bin/docker-compose

Next, set executable permissions to the Docker Compose binary:

chmod +x /usr/local/bin/docker-compose

Next, verify the Docker Compose installation using the following command:

docker-compose --version

Step 7 – Install Portainer UI

First, create a volume to store Portainer data using the following command:

docker volume create portainer_data

Next, run the following command to download the Portainer image from the Docker Hub registry, create a container, and expose the container on port 9000:

docker run -d -p 8000:8000 -p 9000:9000 --name=portainer --restart=always -v /var/run/docker.sock:/var/run/docker.sock -v portainer_data:/data portainer/portainer

You can verify the running container using the following command:

docker ps

Step 8 – Access Portainer UI

Now, open your web browser and access the Portainer UI ip address. Use the URL http://your-server-ip:9000. You should see the following page:

Set your admin user and password and click on the Create user button. You will be asked to select the Docker environment that you want to manage:

Select the local environment and click on the Connect button. You should see the Portainer UI on the following page: