Portainer Docker Homelab Setup: Install, Stacks and Agents

The Docker CLI is powerful, but there are times when a visual interface makes life easier: seeing all your containers at a glance, managing volumes, pulling new images, inspecting logs without memorizing flags. Portainer CE gives you all of this through a browser, and it runs as a Docker container itself.

This guide covers a clean Portainer installation, the most useful features, and how to use it alongside your existing Compose stacks. If you have not written one of those yet, start with your first self-hosted Docker Compose stack.

What Portainer CE Is (and Isn’t)

Portainer CE (Community Edition) is a free, open-source Docker management interface. It runs locally and connects to your Docker daemon. You access it through a browser at https://your-server:9443.

It is not a cloud service and does not require an account. All data stays on your server.

Portainer Business Edition adds features such as granular role-based access control. Agents are not exclusively a Business Edition feature: CE can manage remote environments too.

Portainer CE vs Business Edition

For one administrator, start by deciding whether you need a dashboard and stack editor or delegated permissions. CE covers container management, logs, networks, volumes, and stack deployment. Business Edition’s Docker roles allow more precise separation of who can observe an environment and who can change it.

Choose based on an actual permission requirement rather than the number of containers. A single administrator gains little from a complex role design. If someone only needs to inspect logs, compare the documented role permissions before sharing administrator access. Licensing and feature bundles can change; check the edition documentation at purchase time instead of treating a temporary free-node offer as permanent.

Installation

Standalone (No Traefik)

If you just want Portainer accessible via its built-in port:

mkdir -p ~/services/portainer
cd ~/services/portainer

Create docker-compose.yml:

services:
  portainer:
    image: portainer/portainer-ce:latest
    container_name: portainer
    restart: unless-stopped
    ports:
      - "9443:9443"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - portainer_data:/data

volumes:
  portainer_data:

Start it:

docker compose up -d

Access Portainer at https://your-server-ip:9443. Accept the self-signed certificate warning on first visit.

This local setup publishes only the HTTPS dashboard. Port 8000 is the optional Edge Agent tunnel port in Portainer’s installation documentation; it is not required to inspect the local Docker socket. Keep the dashboard reachable only from your management network or VPN.

Behind Traefik (Recommended)

If you have Traefik set up for automatic HTTPS, add labels to the Compose file instead:

services:
  portainer:
    image: portainer/portainer-ce:latest
    container_name: portainer
    restart: unless-stopped
    command: ["--http-enabled"]
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - portainer_data:/data
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.portainer.rule=Host(`portainer.yourdomain.com`)"
      - "traefik.http.routers.portainer.entrypoints=websecure"
      - "traefik.http.routers.portainer.tls.certresolver=letsencrypt"
      - "traefik.http.services.portainer.loadbalancer.server.port=9000"
    networks:
      - traefik-proxy

volumes:
  portainer_data:

networks:
  traefik-proxy:
    external: true

The --http-enabled option enables the internal HTTP upstream on port 9000 for this example; Traefik handles browser-facing TLS. Do not publish port 9000 on the host. The external proxy network must already exist, as shown in the Traefik setup guide.

First-Time Setup

On first access, Portainer prompts you to create an admin password. Set a strong one, because Portainer has full access to your Docker daemon.

After login, you’re presented with environment selection. Choose Docker (local) to manage the Docker daemon on the same host.

The Dashboard

The home screen shows your environments. Click the local Docker environment to enter the dashboard.

The left sidebar shows:

• Stacks: Docker Compose stacks
• Containers: all running and stopped containers
• Images: locally pulled images
• Networks: Docker networks
• Volumes: named volumes
• Configs/Secrets: Docker secrets (Swarm mode only)

Managing Compose Stacks

Portainer’s Stacks view is the most useful feature for homelab use. It shows your running Compose stacks and lets you:

• View all containers in a stack
• Stop/start/restart a whole stack at once
• Edit the Compose file in the browser
• Pull new images and redeploy

Deploying a New Stack from the UI

1. Go to Stacks → Add stack
2. Choose Web editor
3. Paste your docker-compose.yml content
4. Click Deploy the stack

Portainer starts the containers and shows you the result. Stacks deployed this way still follow the rules in our Docker Compose networking guide. Useful for one-off deployments without SSH.

Portainer Docker Compose conflicts: choose one source file

Portainer does not synchronize your original host-side compose.yaml with edits made in its web editor. If you deploy one definition from your terminal and a different definition from Portainer, the next recreation may restore settings you thought you had removed. Restarting a container does not resolve that disagreement.

Use one of these ownership patterns for each stack:

• CLI-owned: keep the Compose file on the Docker host and apply changes there. Use Portainer to inspect logs and status. Portainer marks resources deployed outside it as external and offers limited control; this does not mean the containers have lost their data.
• Web-editor-owned: make the Portainer stack definition the maintained copy. Save an exported copy with your recovery notes after edits. The old file in your home directory will not update itself.
• Repository-owned: edit the Compose file in its repository and pull/redeploy through Portainer. The stack editing documentation explains that detaching from the repository switches to local editing and ends repository updates; it is not a temporary preview mode.

For a planned move from CLI to Portainer, first record the project name, real Docker volume names, bind-mount paths, networks, and environment values. Docker prefixes ordinary named volumes with the project name, so a new stack name can create an empty volume instead of attaching the old one. A database starting with a setup screen is a reason to inspect mounts before writing more data.

An existing named volume can be declared explicitly, using its actual name from docker volume ls:

volumes:
  app_data:
    external: true
    name: existing_project_app_data

Back up persistent state and schedule downtime before replacing the old deployment. Preserve volumes, ensure the old and new database containers never write the same files together, and use the same absolute bind-mount paths on the target host. Do not include volume deletion in a migration. Portainer’s stack creation form can load environment values, but copying the YAML alone does not copy a host’s .env file or mounted directories.

After deployment, compare the container’s mounts and image with your inventory, open the application, and check existing records. Keep the original Compose definition until recovery from the maintained copy is verified.

Deploying Portainer agents for multiple Docker hosts

Run one Portainer Server for the dashboard and an agent on each additional host. In Environments → Add environment, select Docker Standalone and the Agent option. Use the deployment command displayed by your installed Portainer version on the target host, then enter that host’s reachable address and agent port in the wizard.

The standard agent accepts the server connection on TCP 9001. Keep that connection on a management LAN or VPN and limit access to the Portainer Server. The agent’s Docker socket and volume mounts grant management access to the target machine; they are not ordinary application data mounts. Inspect the generated command against the host’s Docker paths before running it, especially on a NAS.

Portainer’s agent upgrade guidance requires Server and Agent versions to match. Plan them as one maintenance change and record explicit release tags. If an environment stops responding after an update, check version alignment and connectivity before changing application containers.

Each host remains its own Docker environment. Adding an agent does not share volumes, combine bridge networks, or make a standalone Compose stack highly available. A mount under /srv/media must exist on the host that runs that service. For a NAS endpoint, first confirm the NAS models that actually run Docker and the platform’s supported container package.

Use an Edge Agent when the connection pattern requires the remote environment to connect back to the server, following that version’s Edge setup instructions. Do not expose the standard agent port publicly to solve a routing problem.

Viewing Logs

Click any container name to see its details page. The Logs tab shows container logs with optional real-time following, the same as docker logs -f but in the browser.

You can filter by keyword, download the log, and control how many lines to show.

Updating Containers

When a new image version is available:

1. Go to Containers → select the container
2. Click Recreate
3. Check Pull latest image
4. Click Recreate

Portainer stops the container, pulls the new image, and starts a fresh container with the same configuration. Your volumes (data) are preserved.

For Compose stacks, use Stacks → select stack → Pull and redeploy.

Exec Console

The Console tab on a container detail page opens an interactive terminal in the container, the same as docker exec -it container-name /bin/sh.

Useful for:

• Running database migrations
• Debugging configuration inside the container
• Running one-off commands without leaving the browser

Monitoring Resource Usage

The Stats tab shows real-time CPU and memory usage for a container. Not as detailed as Grafana or cAdvisor, but sufficient for quick checks.

For a fleet-level view, the Containers list shows CPU and memory columns for all containers at once. For hostname-based access to those containers, pair it with Nginx Proxy Manager.

When to Use CLI vs Portainer

Portainer is great for:

• Viewing status at a glance
• Reading logs quickly
• Restarting stuck containers
• Updating images

The CLI is better for:

• Initial stack setup (easier to version control)
• Scripted operations and automation
• Complex networking changes
• Debugging DNS and network issues between containers

Use both. They’re not mutually exclusive, and they see the same Docker state.

Portainer vs Dockge vs Yacht

These tools overlap, but the maintained configuration lives in different places. The comparison follows their own project documentation, not benchmark results.

Dockge’s project documentation emphasizes file-based stacks, so it is a useful candidate when keeping editable Compose files on the host is the priority. Yacht’s project guide describes its browser editor and project-folder layout. Check the current release and supported Compose features before importing an existing stack into either tool.

Portainer is the choice here when one dashboard for multiple Docker environments is the main requirement. Whichever interface you choose, keep application backups independent of its configuration store. Portainer’s /data volume preserves dashboard state; it does not back up the databases or media belonging to the containers it manages.

One Portainer quirk worth knowing before it confuses you: containers running with network_mode: host show no network attachment and no published ports in the Portainer UI, because from Docker’s point of view they have neither. That is expected rather than broken, and the Docker Compose host networking guide explains why.

See also

• Best Docker containers for a home server — what to deploy once Portainer is running
• Docker Compose networks — the bridge, DNS, and external-network model Portainer is showing you
• homelab firewall guide
• mini PC homelab builds