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://<portainer-host>:9443

Quick install (Docker on Linux)

# 1) Create a volume for persistent data
docker volume create portainer_data

# 2) Run Portainer CE (HTTPS on 9443, Edge tunnel on 8000)
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:lts

Notes:

• First launch creates an admin user; set a strong password.
• Port 8000 is for Edge compute features (optional); remove -p 8000:8000 if you don’t use Edge agents.
• Port 9000 can be added (-p 9000:9000) if you need legacy HTTP API access.
• If 9443 conflicts, map to another host port (for example, -p 443:9443).
• Keep /data on reliable storage; back it up with your usual host backups.

Use portainer/portainer-ce:lts for stable releases (latest tags available but not recommended for production).

---

🤖 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.

Agent install (Docker on Linux)

Use the wizard in Portainer Server to generate the exact command, or run manually:

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 \
  -v /:/host \
  portainer/agent:lts

Notes:

• Exposes port 9001; keep it firewalled so only the Portainer server can reach it.
• The -v /:/host mount enables optional host management features. Remove if not needed.
• If Docker volumes are at a non-standard location (not /var/lib/docker/volumes), adjust the mount accordingly. For example: -v /srv/data/docker:/var/lib/docker/volumes.
• If the host sits behind NAT and you cannot open 9001, consider the Edge Agent mode instead.
• If you set a custom AGENT_SECRET on the Portainer Server, provide it here: -e AGENT_SECRET=yoursecret.
• Upgrades: docker pull portainer/agent:lts followed by docker restart portainer-agent.

Warning: If you replace an existing Portainer CE instance with a Portainer Agent, all stacks previously created on that host will lose their Portainer metadata. These stacks will no longer be manageable through the Portainer UI, even if they were created by another Portainer CE instance, because the internal Portainer ID is lost during the replacement.

---

🌍 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 <host-ip>: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.

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.

---

🔗 Helpful Links

• Portainer CE install docs: https://docs.portainer.io/start/install/server/docker/linux
• Portainer Agent install docs: https://docs.portainer.io/start/install/agent/docker/linux
• Edge Agent overview: https://docs.portainer.io/admin/edge/overview

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