Managing a Small Docker Landscape with One Portainer CE Instance

Running Docker across multiple virtual machines or containers is very common in home labs — especially when Proxmox is involved. At some point, running docker ps over SSH no longer scales very well. This is where Portainer Community Edition (CE) shines: one lightweight management UI that can control all your Docker instances from a single place.

In this post, I’ll walk through how and why to set up one Portainer CE container to manage a small Docker landscape, such as a Proxmox-based home lab with multiple VMs, LXCs, and several VLANs. Along the way, I’ll explain the underlying concepts so you understand why things work the way they do.

---

🧠 What Problem Portainer Solves

Docker is intentionally decentralized. Every host manages its own containers, images, volumes, and networks. This design is powerful but leads to several pain points as environments grow:

• No central overview of running containers
• Repeated SSH access and credential handling
• Inconsistent workflows across hosts
• Harder onboarding for new users or family members

Portainer CE provides a central management plane without changing how Docker works internally.

Key characteristics:

• Open source and free
• Non-invasive (no custom runtime)
• Works with plain Docker Engine
• Supports users, teams, and access control

---

🧩 Typical Home Lab Architecture

A realistic Proxmox-based home lab often looks like this:

• Proxmox/VMware host
• Multiple VMs and LXCs
• Docker Engine inside each VM or LXC
• Multiple VLANs (management, services, DMZ)
• Central firewall or router (pfSense, OPNsense, VyOS, etc.)

Instead of installing Portainer everywhere, we deploy one central Portainer CE instance and connect all Docker hosts to it.

Important concept:

Portainer manages environments, not clusters. Each Docker host is isolated and managed individually.

---

🏗️ Core Concepts: Portainer Server vs Agent

Portainer consists of two components.

Portainer Server

• Provides the web UI
• Stores users, settings, and metadata
• Runs as a Docker container

Portainer Agent

• Lightweight helper container
• Runs on each Docker host
• Talks to the local Docker socket
• Exposes a secure API for the Portainer server

For multi-host environments, the agent-based setup is the recommended and actively maintained approach.

---

🚀 Deploying the Portainer CE Server

Choose one VM or LXC as your management node. Ideally, this system lives in a management VLAN with restricted access.

The setup consists conceptually of:

• A persistent Docker volume for Portainer data
• A container exposing HTTPS on port 9443
• The Docker socket mounted read/write

After startup, the UI is available at:

https://:9443

---

🤖 Installing the Portainer Agent on Each Docker Host

On every VM or LXC that runs Docker, the Portainer Agent runs as a small helper container.

The agent:

• Connects locally to Docker
• Exposes port 9001 for the Portainer server
• Does not require Docker’s TCP API to be enabled

This keeps the setup simple and secure.

---

🌍 Registering Docker Hosts as Environments

Inside the Portainer UI:

• Add a new environment
• Select Docker Standalone
• Choose Agent-based connection
• Provide a descriptive name
• Use tcp://:9001 as the endpoint

Repeat this for every Docker host, regardless of which VLAN it lives in.

---

🌐 VLAN, Firewall, and Routing Considerations

Multi-VLAN setups add flexibility, isolation, and security — but require deliberate planning.

Suggested VLAN Layout

• Management VLAN
  • Portainer CE
  • Admin workstations
• Services VLAN
  • Internal applications
  • Media services
• DMZ VLAN
  • Public-facing containers

---

Firewall Rules

Minimal required rules:

• Allow TCP port 9001 from the Portainer Server to Docker Hosts
• Allow TCP port 9443 from the Admin Network to the Portainer Server

Strongly recommended:

• Block inter-VLAN traffic by default
• Never expose the Portainer Agent port publicly
• Do not allow Docker hosts to talk to each other unless required

---

Routing and Addressing

• Portainer needs one-way connectivity to agents
• Agents do not need to communicate with each other
• Static IPs or DHCP reservations simplify administration
• Use environment tags to reflect VLAN placement

---

🧰 What You Can Manage Centrally

With all environments connected, Portainer allows you to:

• Manage container lifecycles
• Deploy Docker Compose stacks per host
• Manage images and volumes
• Configure Docker networks
• Control user and team access
• Monitor per-host resource usage

Important limitation:

Each stack belongs to one environment. Portainer CE does not orchestrate workloads across hosts.

---

🔐 Security Best Practices

Even in a home lab, good habits matter:

• Use HTTPS only
• Avoid shared admin accounts
• Use tags to document purpose and VLAN
• Restrict agent ports at the firewall
• Consider Edge Agents for NATed or remote sites

---

🧠 Final Thoughts

A single Portainer CE instance is fully sufficient to manage a multi-host, multi-VLAN Docker home lab. With clean network design and proper firewall rules, you gain central visibility and control without sacrificing isolation or security.

For Proxmox-based labs, personal projects, and self-hosted services, this setup provides a modern and maintainable foundation — allowing you to focus on building and running services instead of managing terminals.

Want to help fuel more posts? You know what to do: