Portainer: How to Build a Docker 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, it’s called HyperV; on Windows 11, it’s 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 a lot of local disk space, 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.

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

SSH to your new Debian server

Step 3 – Update Debian

apt-get update -y

Step 4 – 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.

• 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 | gpg --dearmor -o /etc/apt/keyrings/docker.gpg
chmod a+r /etc/apt/keyrings/docker.gpg

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

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" | \
  tee /etc/apt/sources.list.d/docker.list > /dev/null
apt-get update

• Now Install Docker

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 5 – Install Docker Compose (optional)

You may also need to install Docker Compose on your system. This is optional, but I highly recommend it.

• First, download the latest version of Docker Compose binary using the following command:
• You will find the latest versions here: https://github.com/docker/compose/releases

wget https://github.com/docker/compose/releases/download/v2.28.1/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 6 – 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 7 – 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:

Portainer Q&A

Q1: What are the advantages of using Portainer over the command line interface (CLI) for Docker and Kubernetes management?

A1: Portainer offers a user-friendly web-based graphical user interface (GUI) that simplifies container management, making it more accessible for beginners and those who prefer a visual approach. It provides an intuitive dashboard for monitoring and managing containers, images, networks, and volumes, streamlining tasks that might be more complex via the CLI. Portainer also offers features like role-based access control (RBAC) in its business edition, enhancing security and control over container environments.

Q2: Can I use Portainer to manage Docker containers running on a remote server, or is it limited to the local machine?

A2: Yes, Portainer can manage Docker containers running on both local and remote servers. During the initial setup, you choose the environment to manage, allowing you to connect to remote Docker hosts by providing their endpoint details (IP address and port). This enables centralized management of containers across multiple servers or environments.

Q3: How does Portainer handle updates? Is there an automatic update mechanism, or do I need to manually update the Portainer container?

A3: Portainer does not have an automatic update mechanism within the application itself. You need to manually update the Portainer container to the latest version. This typically involves pulling the latest image from Docker Hub and recreating the Portainer container. However, Portainer provides notifications about new versions, making it easy to stay informed about updates.

Q4: What is the difference between Portainer Community Edition and Business Edition?

A4: Portainer Community Edition (CE) is a free and open-source version that provides essential features for managing Docker and Kubernetes environments. Business Edition (BE) builds upon CE with advanced features like:

• Advanced Role-Based Access Control (RBAC): Granular control over user permissions and access to resources.
• Support for multiple Kubernetes distributions: Manage various Kubernetes flavors from a single interface.
• Registry management: Securely manage and control access to private container registries.
• Dedicated support: Access to professional support from the Portainer team.

Q5: Can Portainer be used with Docker Compose, and if so, how does it integrate with Compose files?

A5: Yes, Portainer has excellent integration with Docker Compose. You can use Portainer to:

• Deploy stacks defined in Docker Compose YAML files directly through the interface.
• Manage existing stacks deployed via Compose, including scaling services, viewing logs, and restarting containers.
• Edit Compose files within Portainer.

Q6: Does Portainer support managing containers on different operating systems or architectures, such as Windows containers or ARM-based devices?

A6: Yes, Portainer supports managing containers across different operating systems and architectures. It can manage Docker containers running on Linux, Windows, and ARM-based devices like Raspberry Pis. This versatility makes Portainer a suitable choice for diverse container environments.

Q7: Is it possible to use Portainer to back up and restore my container configurations and data?

A7: While Portainer doesn’t have built-in features for comprehensive backups and restores, you can use it in conjunction with other tools to achieve this. For instance, you can use Portainer to manage volumes and then use external tools or scripts to back up those volumes, ensuring data persistence and recovery.

Q8: How secure is Portainer, and what measures are in place to protect my container environment?

A8: Portainer prioritizes security and offers several features to protect container environments:

• Authentication and authorization: Secure access to the Portainer interface with username/password authentication and, in the Business Edition, granular RBAC.
• TLS encryption: Secure communication between the Portainer server and clients using HTTPS.
• Regular security updates: Portainer releases updates to address potential vulnerabilities and security issues.

Q9: Are there any limitations to the number of containers or nodes that Portainer can manage?

A9: Portainer, particularly the Community Edition, is designed to be lightweight and can comfortably manage a substantial number of containers and nodes. However, for very large-scale deployments with thousands of containers or nodes, performance might be a consideration. In such cases, the Business Edition with its optimized architecture and support might be more suitable.

Q10: Where can I find more information and documentation about Portainer, including advanced usage and troubleshooting?

A10: The official Portainer website (www.portainer.io) is an excellent resource for comprehensive documentation, tutorials, and a community forum for support. You can also find detailed information and examples on the Portainer GitHub repository (github.com/portainer/portainer).

That’s it, you now have the latest version of Portainer running on Debian. We welcome all feedback, comments, and suggestions in the comments section below.