Portainer Complete Setup Guide 2026: Docker Management for Home Labs

Published on January 12, 2026

1. Introduction

1.1 What is Portainer?

Portainer is an open-source, lightweight management UI that simplifies the management of Docker, Docker Swarm, and Kubernetes environments. It provides an intuitive web-based graphical interface that allows users to deploy, manage, and troubleshoot containerized applications without extensive command-line knowledge.

Key Features:

• Container Management: Deploy, start, stop, restart, and remove containers with a click
• Stack Deployment: Deploy multi-container applications using Docker Compose (YAML) files
• Image Management: Pull, push, and manage Docker images from registries
• Volume & Network Management: Create and configure persistent storage and networking
• User Access Control: Role-based access control (RBAC) for team environments
• Multi-Environment Support: Manage Docker standalone, Swarm, and Kubernetes from one UI
• App Templates: One-click deployment of popular applications
• Real-time Monitoring: View logs, stats, and container console access

1.2 Portainer Versions (January 2026)

As of January 2026, the latest stable releases are Portainer Core v2.33.6 LTS and v2.38 STS. Always check the official GitHub releases for the most current version before installation.

[!NOTE] This guide uses Portainer CE (Community Edition) with the LTS (Long Term Support) tag for maximum stability. The LTS version is recommended for production and home lab environments.

1.3 Portainer Editions Comparison

[!TIP] Home Lab Recommendation: Portainer CE is perfect for home labs and personal use. Business Edition offers a “Home & Student” license (up to 15 nodes) for non-commercial use and a “3 Nodes Free” program for trying BE features.

1.4 Why Use Portainer for Home Labs?

1.5 What This Guide Covers

This comprehensive guide will walk you through:

1. Understanding Portainer — Architecture and core concepts
2. System Requirements — Hardware and software prerequisites
3. Installation Methods — Docker, Docker Swarm, Kubernetes, NAS devices
4. Platform-Specific Setup — Windows, macOS, Linux, Raspberry Pi
5. Initial Configuration — First-time setup and user management
6. Container Management — Deploying and managing containers
7. Stack Deployment — Using Docker Compose with Portainer
8. App Templates — Using and creating custom templates
9. Reverse Proxy Integration — Traefik, Nginx Proxy Manager, Caddy
10. Monitoring Integration — Grafana, Prometheus, cAdvisor
11. Edge Agent Deployment — Managing remote/IoT devices
12. Home Lab Use Cases — Practical deployment examples
13. Backup & Restore — Protecting your Portainer configuration
14. Troubleshooting — Common issues and solutions

2. System Requirements

2.1 Hardware Requirements

Portainer Server (Minimum)

[!NOTE] Portainer itself is very lightweight (~50MB). The requirements above include headroom for the Docker engine and a few containers. Your actual needs depend on the containers you run.

Recommended Home Lab Configurations

2.2 Supported Operating Systems

For Docker Host (Server)

2.3 Network Requirements

[!IMPORTANT] Portainer 2.x defaults to HTTPS on port 9443 with a self-signed certificate. Port 9000 (HTTP) can be enabled for legacy compatibility but is not recommended for security.

2.4 Docker Version Compatibility

3. Installing Docker

Portainer runs as a Docker container, so Docker must be installed first. Follow the instructions for your operating system.

3.1 Linux (Debian/Ubuntu)

These commands work for Debian 11+, Ubuntu 20.04+, and derivatives like Linux Mint.

Step 1: Update System Packages

# Update package lists and upgrade existing packages
sudo apt update && sudo apt upgrade -y

What this does: Ensures your system has the latest security patches before installing new software.

Step 2: Install Prerequisites

# Install packages required for Docker's repository
sudo apt install -y ca-certificates curl gnupg lsb-release

Step 3: Add Docker’s Official GPG Key

# Create directory for apt keyrings
sudo install -m 0755 -d /etc/apt/keyrings

# Download and add Docker's GPG key
curl -fsSL https://download.docker.com/linux/$(. /etc/os-release && echo "$ID")/gpg | 
  sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

# Set correct permissions
sudo chmod a+r /etc/apt/keyrings/docker.gpg

Step 4: Add Docker Repository

# Add Docker's official apt repository
echo 
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg]   https://download.docker.com/linux/$(. /etc/os-release && echo "$ID")   $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | 
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Update package lists with new repository
sudo apt update

Step 5: Install Docker Engine

# Install Docker and all required components
sudo apt install -y docker-ce docker-ce-cli containerd.io 
  docker-buildx-plugin docker-compose-plugin

Step 6: Add User to Docker Group

# Add current user to docker group (avoids needing sudo)
sudo usermod -aG docker $USER

# Apply group changes (or log out and back in)
newgrp docker

[!WARNING] You must log out and log back in for group changes to take effect.

Step 7: Verify Installation

# Check Docker version
docker --version

# Check Docker Compose version
docker compose version

# Run test container
docker run hello-world

3.2 Linux (RHEL/Fedora/CentOS)

Fedora

# Install Docker
sudo dnf -y install dnf-plugins-core
sudo dnf config-manager --add-repo https://download.docker.com/linux/fedora/docker-ce.repo
sudo dnf install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

# Start and enable Docker
sudo systemctl start docker
sudo systemctl enable docker

# Add user to docker group
sudo usermod -aG docker $USER
newgrp docker

RHEL/CentOS/Rocky Linux/AlmaLinux

# Install prerequisites
sudo yum install -y yum-utils

# Add Docker repository
sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo

# Install Docker
sudo yum install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

# Start and enable Docker
sudo systemctl start docker
sudo systemctl enable docker

# Add user to docker group
sudo usermod -aG docker $USER
newgrp docker

3.3 Windows (Docker Desktop with WSL2)

Prerequisites

• Windows 10 version 2004+ (Build 19041+) or Windows 11
• 64-bit processor with virtualization support
• Hardware virtualization enabled in BIOS/UEFI
• Minimum 4 GB RAM (8 GB+ recommended)

Step 1: Enable WSL2

Open PowerShell as Administrator:

# Enable WSL feature
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart

# Enable Virtual Machine Platform
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

Restart your computer after these commands.

Step 2: Set WSL2 as Default

After restart, open PowerShell as Administrator:

# Set WSL2 as the default version
wsl --set-default-version 2

# Update WSL to latest version
wsl --update

# Verify WSL version
wsl --version

Step 3: Install a Linux Distribution (Recommended)

# List available distributions
wsl --list --online

# Install Ubuntu (recommended)
wsl --install -d Ubuntu

Step 4: Download and Install Docker Desktop

1. Download from docker.com/products/docker-desktop
2. Run the installer (Docker Desktop Installer.exe)
3. Ensure “Use WSL 2 instead of Hyper-V” is checked
4. Complete installation and restart if prompted

Step 5: Configure Docker Desktop

1. Launch Docker Desktop
2. Go to Settings → General: Enable “Use the WSL 2 based engine”
3. Go to Settings → Resources → WSL Integration: Enable for your Linux distro
4. Click Apply & Restart

Step 6: Verify Installation

# Check Docker version
docker --version

# Check Docker Compose version
docker compose version

# Run test container
docker run hello-world

3.4 macOS (Docker Desktop)

Prerequisites

• macOS 12 (Monterey) or later
• Apple Silicon (M1/M2/M3/M4) or Intel processor
• Minimum 4 GB RAM (8 GB+ recommended)

Step 1: Download Docker Desktop

1. Go to docker.com/products/docker-desktop
2. Select the correct version:
   • Apple Silicon for M1/M2/M3/M4 Macs
   • Intel for older Intel-based Macs

Step 2: Install Docker Desktop

1. Open the downloaded .dmg file
2. Drag Docker to Applications
3. Launch Docker from Applications
4. Accept the license agreement

Step 3: Install Rosetta 2 (Apple Silicon Only)

# Install Rosetta 2 for x86 emulation
softwareupdate --install-rosetta

Step 4: Verify Installation

# Check Docker version
docker --version

# Check Docker Compose version
docker compose version

# Run test container
docker run hello-world

Alternative: Install via Homebrew

# Install Docker Desktop using Homebrew
brew install --cask docker

# Launch Docker Desktop
open /Applications/Docker.app

3.5 Raspberry Pi (64-bit OS)

Prerequisites

• Raspberry Pi 4 (4GB+ RAM recommended) or Raspberry Pi 5
• Raspberry Pi OS (64-bit) Lite or Full
• microSD card (32GB+) or SSD via USB

Step 1: Update System

# Update and upgrade packages
sudo apt update && sudo apt full-upgrade -y

# Reboot if kernel was updated
sudo reboot

Step 2: Install Docker

# Install Docker using convenience script
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# Add user to docker group
sudo usermod -aG docker $USER

# Apply changes (or reboot)
newgrp docker

Step 3: Verify Installation

# Check Docker version
docker --version

# Check architecture (should show arm64)
docker info | grep Architecture

# Run test container
docker run hello-world

[!TIP] For better performance on Raspberry Pi, use an SSD connected via USB instead of a microSD card. This significantly improves I/O performance for databases and Docker volumes.

4. Installing Portainer

Now that Docker is installed, let’s deploy Portainer. Choose the method that matches your environment.

4.1 Docker Standalone (Single Host)

This is the most common installation for home labs managing a single Docker host.

Method 1: Using Docker Run (Quick Start)

Linux/macOS:

# Create a volume for Portainer data
docker volume create portainer_data

# Deploy Portainer CE with LTS tag
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

Windows (PowerShell):

# Create a volume for Portainer data
docker volume create portainer_data

# Deploy Portainer CE with LTS tag
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

Command Breakdown:

Method 2: Using Docker Compose (Recommended)

Create a directory for your Portainer stack:

Linux/macOS:

mkdir -p ~/docker/portainer && cd ~/docker/portainer

Windows (PowerShell):

New-Item -ItemType Directory -Force -Path "$env:USERPROFILEdockerportainer"
Set-Location "$env:USERPROFILEdockerportainer"

Create docker-compose.yml:

services:
  portainer:
    image: portainer/portainer-ce:lts
    container_name: portainer
    restart: always
    ports:
      - "8000:8000"    # Edge Agent tunnel
      - "9443:9443"    # HTTPS Web UI
      # - "9000:9000"  # HTTP Web UI (optional, not recommended)
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - portainer_data:/data
    environment:
      - TZ=UTC  # Set your timezone

volumes:
  portainer_data:
    name: portainer_data

networks:
  default:
    name: portainer_network

Deploy the stack:

# Deploy Portainer
docker compose up -d

# View logs
docker compose logs -f portainer

Verify Portainer is Running

# Check container status
docker ps | grep portainer

# Expected output:
# CONTAINER ID   IMAGE                          ...   PORTS                    NAMES
# abc123...      portainer/portainer-ce:lts     ...   0.0.0.0:9443->9443/tcp   portainer

4.2 Docker Swarm Deployment

For managing a Docker Swarm cluster with Portainer.

Prerequisites

• A running Docker Swarm cluster (at least one manager node)
• SSH access to the Swarm manager

Step 1: Initialize Swarm (If Not Already Done)

On your manager node:

# Initialize Docker Swarm
docker swarm init --advertise-addr <MANAGER_IP>

# Note the join token for worker nodes
docker swarm join-token worker

Step 2: Deploy Portainer Agent Stack

Download and deploy the official stack file:

# Download the Portainer Agent stack file
curl -L https://downloads.portainer.io/ce-lts/portainer-agent-stack.yml 
  -o portainer-agent-stack.yml

# Deploy the stack
docker stack deploy -c portainer-agent-stack.yml portainer

Or create the stack file manually:

# portainer-agent-stack.yml
version: '3.8'

services:
  agent:
    image: portainer/agent:lts
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - /var/lib/docker/volumes:/var/lib/docker/volumes
    networks:
      - agent_network
    deploy:
      mode: global
      placement:
        constraints: [node.platform.os == linux]

  portainer:
    image: portainer/portainer-ce:lts
    command: -H tcp://tasks.agent:9001 --tlsskipverify
    ports:
      - "9443:9443"
      - "9000:9000"
      - "8000:8000"
    volumes:
      - portainer_data:/data
    networks:
      - agent_network
    deploy:
      mode: replicated
      replicas: 1
      placement:
        constraints: [node.role == manager]

networks:
  agent_network:
    driver: overlay
    attachable: true

volumes:
  portainer_data:

Step 3: Verify Deployment

# Check stack status
docker stack services portainer

# Check Portainer service
docker service logs portainer_portainer

4.3 Kubernetes Deployment

For managing Kubernetes clusters with Portainer.

Method 1: Using Helm (Recommended)

# Add Portainer Helm repository
helm repo add portainer https://portainer.github.io/k8s/
helm repo update

# Install Portainer (with NodePort)
helm install --create-namespace -n portainer portainer portainer/portainer

# Install with LoadBalancer (for cloud providers)
helm install --create-namespace -n portainer portainer portainer/portainer 
  --set service.type=LoadBalancer

Method 2: Using YAML Manifests

# Deploy using official manifests (NodePort)
kubectl apply -n portainer -f https://raw.githubusercontent.com/portainer/k8s/master/deploy/manifests/portainer/portainer.yaml

# Create namespace first if needed
kubectl create namespace portainer

Access Portainer

# Get the NodePort
kubectl get svc -n portainer

# Access via: https://<NODE_IP>:<NODEPORT>

5. Initial Configuration

5.1 First-Time Setup

1. Access Portainer: Open your browser and navigate to:

   • https://localhost:9443 (local access)
   • https://<SERVER_IP>:9443 (remote access)

2. Accept Security Warning: Portainer uses a self-signed certificate by default. Click “Advanced” → “Proceed” to continue.

3. Create Admin User:

   • Username: Choose a username (default: admin)
   • Password: Must be at least 12 characters
   • Click Create user

[!IMPORTANT] Choose a strong password for the admin account. This is your primary security layer. Use a password manager to generate and store a complex password.

5.2 Connect Your Environment

After creating your admin account, you’ll see the Environment Wizard.

For Docker Standalone (Local Docker Socket)

1. Select Docker → Connect
2. Choose Socket connection
3. Click Connect
4. Portainer will automatically detect your local Docker engine

For Remote Docker Host (TCP)

1. Select Docker → Connect
2. Choose API connection
3. Enter the Docker API URL: tcp://<DOCKER_HOST_IP>:2375
4. Configure TLS if enabled
5. Click Connect

[!WARNING] Exposing the Docker API over TCP without TLS is a security risk. Always use TLS certificates for remote Docker connections or use Portainer Agent instead.

5.3 Portainer Agent (Recommended for Remote Hosts)

The Portainer Agent is a lightweight container that provides secure communication between Portainer Server and remote Docker hosts.

Deploy Agent on Remote Host

# On the REMOTE Docker host, run:
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 
  portainer/agent:lts

Connect Agent in Portainer

1. Go to Environments → Add environment
2. Select Docker → Agent
3. Enter:
   • Name: Descriptive name for this environment
   • Environment URL: <REMOTE_HOST_IP>:9001
4. Click Connect

6. Managing Containers

6.1 Container Dashboard Overview

The Containers view shows all running and stopped containers with key information:

6.2 Deploying a Container

Method 1: Using the Web Form

1. Go to Containers → Add container
2. Fill in the form:
   • Name: Container name
   • Image: Docker image (e.g., nginx:latest)
   • Port mapping: Host port → Container port
   • Volumes: Bind mounts or volumes
   • Environment variables: Key-value pairs
3. Configure advanced options:
   • Restart policy: Always, Unless-stopped, On-failure
   • Runtime & Resources: CPU/Memory limits
   • Labels: Metadata for organization
4. Click Deploy the container

Method 2: From Docker Hub

1. Go to App Templates or search Docker Hub in the image field
2. Pull the image: Enter the full image name and tag
3. Configure as above

6.3 Container Operations

6.4 Viewing Logs

1. Click the Logs icon or go to Container → Logs
2. Options:
   • Auto-refresh: Real-time log streaming
   • Wrap lines: Wrap long lines
   • Timestamps: Show log timestamps
   • Since: Filter logs by time
   • Search: Filter logs by keyword

6.5 Console Access

1. Click the Console icon or go to Container → Console
2. Select the shell:
   • /bin/bash (most Linux containers)
   • /bin/sh (Alpine-based containers)
   • Custom command
3. Click Connect

7. Stack Deployment (Docker Compose)

Stacks are the Portainer equivalent of Docker Compose deployments.

7.1 Creating a Stack

Method 1: Web Editor

1. Go to Stacks → Add stack
2. Enter a Name for your stack
3. Choose Web editor
4. Paste your Docker Compose YAML content
5. (Optional) Add environment variables
6. Click Deploy the stack

Method 2: Upload Compose File

1. Go to Stacks → Add stack
2. Enter a Name
3. Choose Upload
4. Select your docker-compose.yml file
5. Click Deploy the stack

Method 3: Git Repository (GitOps)

1. Go to Stacks → Add stack
2. Enter a Name
3. Choose Repository
4. Enter:
   • Repository URL: Git repo URL
   • Reference: Branch or tag
   • Compose path: Path to docker-compose.yml
   • Authentication: If private repo
5. Enable Automatic updates for GitOps workflow
6. Click Deploy the stack

7.2 Example: Deploying a Media Stack

# Media Server Stack Example
services:
  jellyfin:
    image: jellyfin/jellyfin:latest
    container_name: jellyfin
    restart: unless-stopped
    ports:
      - "8096:8096"
    volumes:
      - jellyfin_config:/config
      - jellyfin_cache:/cache
      - /path/to/media:/media:ro
    environment:
      - TZ=UTC

  radarr:
    image: linuxserver/radarr:latest
    container_name: radarr
    restart: unless-stopped
    ports:
      - "7878:7878"
    volumes:
      - radarr_config:/config
      - /path/to/downloads:/downloads
      - /path/to/movies:/movies
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=UTC

  sonarr:
    image: linuxserver/sonarr:latest
    container_name: sonarr
    restart: unless-stopped
    ports:
      - "8989:8989"
    volumes:
      - sonarr_config:/config
      - /path/to/downloads:/downloads
      - /path/to/tv:/tv
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=UTC

volumes:
  jellyfin_config:
  jellyfin_cache:
  radarr_config:
  sonarr_config:

7.3 Managing Stacks

8. App Templates

8.1 Using Built-in Templates

1. Go to App Templates
2. Browse or search for an application
3. Click on the template
4. Configure options (name, ports, volumes)
5. Click Deploy the container

8.2 Adding Custom Template Sources

Portainer supports external template sources from the community.

1. Go to Settings → App Templates
2. Enable Use external templates
3. Enter the template URL:
   • Official Portainer Templates: https://raw.githubusercontent.com/portainer/templates/master/templates-2.0.json
   • Self-Hosted Templates by Lissy93: https://raw.githubusercontent.com/Lissy93/portainer-templates/main/templates.json
4. Click Save settings
5. Refresh the App Templates page

8.3 Popular Community Template Sources

8.4 Creating Custom Templates

You can create custom templates from existing containers or stacks.

From Container

1. Go to Containers
2. Select a container
3. Click Duplicate/Edit
4. Configure as needed
5. Click Actions → Create template

From Stack

1. Go to Stacks → select a stack
2. Click Template → Create
3. Enter template details:
   • Title: Template name
   • Description: What it does
   • Logo: Optional icon URL
   • Categories: For organization
4. Save the template

9. NAS Device Installation

9.1 Synology NAS (DSM 7+)

Prerequisites

• Synology NAS with DSM 7.0 or later
• Container Manager package installed

Method 1: Using Container Manager UI

1. Open Container Manager from DSM
2. Go to Registry → Search for portainer/portainer-ce
3. Download the lts tag
4. Go to Image → Select portainer-ce → Run
5. Configure container:
   • Container Name: portainer
   • Enable auto-restart: Yes
   • Port Settings:
     • Local: 9443, Container: 9443 (HTTPS)
     • Local: 8000, Container: 8000 (Edge)
   • Volume Settings:
     • Add file: /var/run/docker.sock → /var/run/docker.sock
     • Add folder: /docker/portainer → /data
6. Click Done → Apply

Method 2: Using SSH (Recommended)

1. Enable SSH in Control Panel → Terminal & SNMP
2. Connect via SSH: ssh username@synology-ip
3. Run Portainer:

# Create data directory
sudo mkdir -p /volume1/docker/portainer

# Deploy Portainer
sudo docker run -d 
  --name portainer 
  --restart=always 
  -p 8000:8000 
  -p 9443:9443 
  -v /var/run/docker.sock:/var/run/docker.sock 
  -v /volume1/docker/portainer:/data 
  portainer/portainer-ce:lts

9.2 QNAP NAS (QTS 5+)

Prerequisites

• QNAP NAS with QTS 5.0 or later
• Container Station installed

Method 1: Using Container Station

1. Open Container Station
2. Go to Create → Create Application
3. Give it a name (e.g., portainer)
4. Paste the following YAML:

version: "3"
services:
  portainer:
    image: portainer/portainer-ce:lts
    container_name: portainer
    restart: always
    ports:
      - "8000:8000"
      - "9443:9443"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - /share/Container/portainer:/data

5. Click Create

Method 2: Using SSH

# SSH into QNAP
ssh admin@qnap-ip

# Create data directory
mkdir -p /share/Container/portainer

# Deploy Portainer
docker run -d 
  --name portainer 
  --restart=always 
  -p 8000:8000 
  -p 9443:9443 
  -v /var/run/docker.sock:/var/run/docker.sock 
  -v /share/Container/portainer:/data 
  portainer/portainer-ce:lts

9.3 TrueNAS Scale

TrueNAS Scale has native Docker support but requires specific configuration for Portainer.

Method 1: Using a VM or Jail

The recommended approach is to run Portainer inside a VM or jail for full control.

1. Create a Ubuntu VM in TrueNAS
2. Install Docker in the VM (see Section 3.1)
3. Deploy Portainer normally

Method 2: Native Docker (Advanced)

[!WARNING] TrueNAS Scale’s native Docker integration may conflict with Portainer. This method requires disabling TrueNAS’s application management.

1. SSH into TrueNAS Scale
2. Unset the Application Pool (removes ix-applications dataset management)
3. Deploy Portainer:

docker run -d 
  --name portainer 
  --restart=always 
  -p 8000:8000 
  -p 9443:9443 
  -v /var/run/docker.sock:/var/run/docker.sock 
  -v /mnt/pool/portainer_data:/data 
  portainer/portainer-ce:lts

10. Reverse Proxy Integration

10.1 Nginx Proxy Manager

Nginx Proxy Manager (NPM) provides a user-friendly UI for setting up reverse proxies with automatic SSL.

Step 1: Ensure Both Are on Same Network

Create a shared Docker network:

docker network create proxy_network

Update Portainer to use this network:

# docker-compose.yml for Portainer
services:
  portainer:
    image: portainer/portainer-ce:lts
    container_name: portainer
    restart: always
    ports:
      - "9443:9443"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - portainer_data:/data
    networks:
      - proxy_network

volumes:
  portainer_data:

networks:
  proxy_network:
    external: true

Step 2: Configure NPM Proxy Host

1. Open Nginx Proxy Manager (usually port 81)
2. Go to Proxy Hosts → Add Proxy Host
3. Configure:
   • Domain Names: portainer.yourdomain.com
   • Scheme: https
   • Forward Hostname/IP: portainer
   • Forward Port: 9443
   • Block Common Exploits: Enable
   • Websockets Support: Enable
4. SSL Tab:
   • Request a new SSL certificate
   • Force SSL: Enable
   • HTTP/2 Support: Enable
5. Click Save

10.2 Traefik

Traefik provides dynamic Docker-aware reverse proxying with automatic SSL.

Docker Compose with Traefik Labels

services:
  portainer:
    image: portainer/portainer-ce:lts
    container_name: portainer
    restart: always
    command: -H unix:///var/run/docker.sock
    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_network

volumes:
  portainer_data:

networks:
  traefik_network:
    external: true

[!NOTE] When using Traefik, Portainer should use HTTP internally (port 9000) as Traefik handles SSL termination.

10.3 Caddy

Caddy provides automatic HTTPS with minimal configuration.

Caddyfile Example

portainer.yourdomain.com {
    reverse_proxy portainer:9443 {
        transport http {
            tls_insecure_skip_verify
        }
    }
}

Or for HTTP backend (recommended):

portainer.yourdomain.com {
    reverse_proxy portainer:9000
}

11. Monitoring Integration

11.1 Prometheus and Grafana Stack

Deploy a complete monitoring stack alongside Portainer.

Docker Compose Monitoring Stack

services:
  prometheus:
    image: prom/prometheus:latest
    container_name: prometheus
    restart: unless-stopped
    ports:
      - "9090:9090"
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml:ro
      - prometheus_data:/prometheus
    command:
      - '--config.file=/etc/prometheus/prometheus.yml'
      - '--storage.tsdb.path=/prometheus'
      - '--web.enable-lifecycle'

  grafana:
    image: grafana/grafana:latest
    container_name: grafana
    restart: unless-stopped
    ports:
      - "3000:3000"
    volumes:
      - grafana_data:/var/lib/grafana
    environment:
      - GF_SECURITY_ADMIN_PASSWORD=admin
      - GF_USERS_ALLOW_SIGN_UP=false

  node-exporter:
    image: prom/node-exporter:latest
    container_name: node-exporter
    restart: unless-stopped
    ports:
      - "9100:9100"
    volumes:
      - /proc:/host/proc:ro
      - /sys:/host/sys:ro
      - /:/rootfs:ro
    command:
      - '--path.procfs=/host/proc'
      - '--path.sysfs=/host/sys'
      - '--collector.filesystem.mount-points-exclude=^/(sys|proc|dev|host|etc)($$|/)'

  cadvisor:
    image: gcr.io/cadvisor/cadvisor:latest
    container_name: cadvisor
    restart: unless-stopped
    ports:
      - "8080:8080"
    volumes:
      - /:/rootfs:ro
      - /var/run:/var/run:ro
      - /sys:/sys:ro
      - /var/lib/docker/:/var/lib/docker:ro
      - /dev/disk/:/dev/disk:ro
    privileged: true

volumes:
  prometheus_data:
  grafana_data:

Prometheus Configuration

Create prometheus.yml:

global:
  scrape_interval: 15s
  evaluation_interval: 15s

scrape_configs:
  - job_name: 'prometheus'
    static_configs:
      - targets: ['localhost:9090']

  - job_name: 'node-exporter'
    static_configs:
      - targets: ['node-exporter:9100']

  - job_name: 'cadvisor'
    static_configs:
      - targets: ['cadvisor:8080']

Connect Grafana to Prometheus

1. Access Grafana at http://server-ip:3000
2. Login (default: admin/admin)
3. Go to Configuration → Data Sources → Add data source
4. Select Prometheus
5. URL: http://prometheus:9090
6. Click Save & Test

Import Dashboards

Popular dashboards for Docker monitoring:

To import: Go to Dashboards → Import → Enter Dashboard ID → Load

12. Edge Agent for Remote Management

The Edge Agent allows managing remote Docker environments that may be behind firewalls or NAT.

12.1 How Edge Agent Works

┌─────────────────────────────────────────────────┐
│              Home Lab Server                     │
│          (Portainer Server)                      │
│        Ports: 9443 (UI), 8000 (Tunnel)          │
└─────────────────────┬───────────────────────────┘
                      │ Outbound TLS Tunnel
          ┌───────────┴───────────┐
          │                       │
    ┌─────▼─────┐           ┌─────▼─────┐
    │ Remote    │           │ IoT       │
    │ Server    │           │ Device    │
    │ (Edge)    │           │ (Edge)    │
    └───────────┘           └───────────┘

Key Points:

• Edge Agent initiates outbound connection to Portainer Server
• No inbound ports needed on remote devices
• Works through NAT and firewalls
• Encrypted TLS tunnel

12.2 Deploying Edge Agent

Step 1: Prepare Portainer Server

Ensure port 8000 is accessible on your Portainer Server:

# Verify port 8000 is exposed
docker ps | grep portainer
# Should show: 0.0.0.0:8000->8000/tcp

Step 2: Add Edge Environment in Portainer

1. Go to Environments → Add environment
2. Select Docker → Edge Agent
3. Configure:
   • Name: Remote device name
   • Portainer API server URL: https://your-portainer-server:9443
4. Click Create
5. Copy the generated deployment command

Step 3: Run Edge Agent on Remote Device

Run the command provided by Portainer on your remote device:

docker run -d 
  -v /var/run/docker.sock:/var/run/docker.sock 
  -v /var/lib/docker/volumes:/var/lib/docker/volumes 
  -v /:/host 
  -v portainer_agent_data:/data 
  --restart always 
  -e EDGE=1 
  -e EDGE_ID=<unique_edge_id> 
  -e EDGE_KEY=<edge_key> 
  -e EDGE_INSECURE_POLL=1 
  --name portainer_edge_agent 
  portainer/agent:lts

[!NOTE] The EDGE_INSECURE_POLL=1 flag is required if your Portainer Server uses a self-signed certificate.

12.3 Use Cases for Edge Agent

13. Home Lab Use Cases

13.1 Media Server Stack

A complete media automation stack managed through Portainer.

Components

Deployment Tips

1. Create a dedicated stack in Portainer
2. Use shared volumes for media library
3. Configure proper user/group IDs (PUID/PGID)
4. Set up reverse proxy for external access

13.2 Privacy & Security Stack

Self-hosted privacy tools.

13.3 Productivity Stack

Self-hosted productivity suite.

13.4 Home Automation Stack

14. Backup and Restore

14.1 What to Back Up

14.2 Manual Backup

Portainer Data Volume

# Create backup directory
mkdir -p ~/backups/portainer

# Backup Portainer data volume
docker run --rm 
  -v portainer_data:/data 
  -v ~/backups/portainer:/backup 
  alpine tar czf /backup/portainer_data_$(date +%Y%m%d).tar.gz -C /data .

Export Stack Definitions

1. Go to Stacks in Portainer
2. Click on each stack
3. Copy the compose file content
4. Save to version control (Git)

14.3 Automated Backup with Docker

Create a backup container that runs on schedule:

services:
  backup:
    image: offen/docker-volume-backup:latest
    container_name: backup
    restart: unless-stopped
    volumes:
      - portainer_data:/backup/portainer:ro
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - ~/backups:/archive
    environment:
      - BACKUP_CRON_EXPRESSION=0 2 * * *  # Daily at 2 AM
      - BACKUP_FILENAME=portainer-%Y%m%d.tar.gz
      - BACKUP_RETENTION_DAYS=7

14.4 Restore Procedure

Restore Portainer Data

# Stop Portainer
docker stop portainer

# Restore data
docker run --rm 
  -v portainer_data:/data 
  -v ~/backups/portainer:/backup 
  alpine sh -c "rm -rf /data/* && tar xzf /backup/portainer_data_YYYYMMDD.tar.gz -C /data"

# Start Portainer
docker start portainer

15. Updating Portainer

15.1 Update Using Docker CLI

# Stop and remove current container
docker stop portainer
docker rm portainer

# Pull latest LTS image
docker pull portainer/portainer-ce:lts

# Recreate container (same command as installation)
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

15.2 Update Using Docker Compose

# Navigate to stack directory
cd ~/docker/portainer

# Pull new image
docker compose pull

# Recreate container with new image
docker compose up -d

15.3 Update Using Portainer (Recreate)

1. Go to Containers → portainer
2. Click Recreate
3. Enable Pull latest image
4. Click Recreate

[!WARNING] Always backup your Portainer data before updating. While updates are generally smooth, having a backup ensures you can recover if something goes wrong.

16. Security Best Practices

16.1 Access Control

16.2 Network Security

16.3 Container Security

16.4 Portainer-Specific Settings

1. Disable unused features: Settings → Authentication → Disable options you don’t use
2. Set session timeout: Settings → Authentication → Set appropriate timeout
3. Enable webhooks cautiously: Only if needed, with proper authentication
4. Regular backups: Automate backups of Portainer data

17. Troubleshooting

17.1 Common Issues

Cannot Access Portainer Web UI

Symptoms: Browser shows connection refused or timeout

Solutions:

# Check if container is running
docker ps | grep portainer

# Check container logs
docker logs portainer

# Verify port is listening
netstat -tlnp | grep 9443  # Linux
netstat -an | findstr 9443  # Windows

# Check firewall
sudo ufw status  # Linux

Portainer Cannot Connect to Docker

Symptoms: “Unable to connect to Docker” error

Solutions:

# Verify Docker socket permissions
ls -la /var/run/docker.sock
# Should show: srw-rw---- 1 root docker

# Restart Portainer
docker restart portainer

# Recreate with socket mount
docker rm -f portainer
docker run -d ... -v /var/run/docker.sock:/var/run/docker.sock ...

Stacks Won’t Deploy

Symptoms: Stack deployment fails with errors

Solutions:

1. Validate YAML syntax at yamlvalidator.com
2. Check for port conflicts with existing containers
3. Ensure all referenced images exist
4. Verify volume paths are correct

Edge Agent Won’t Connect

Symptoms: Edge environment shows disconnected

Solutions:

# On remote device, check agent status
docker logs portainer_edge_agent

# Verify connectivity to Portainer server
curl -k https://portainer-server:9443

# Check if port 8000 is accessible
nc -zv portainer-server 8000

17.2 Performance Issues

17.3 Getting Help

• Official Documentation: docs.portainer.io
• GitHub Issues: github.com/portainer/portainer
• Community Forum: community.portainer.io
• Discord: Portainer Discord server
• Reddit: r/portainer, r/selfhosted, r/homelab

18. Quick Reference Commands

18.1 Installation Commands Summary

Linux

# Create volume and run Portainer
docker volume create portainer_data
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

Windows (PowerShell)

docker volume create portainer_data
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

macOS

docker volume create portainer_data
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

18.2 Common Management Commands

# View Portainer logs
docker logs portainer

# Restart Portainer
docker restart portainer

# Stop Portainer
docker stop portainer

# Update Portainer
docker stop portainer && docker rm portainer
docker pull portainer/portainer-ce:lts
# Then run the installation command again

# Backup Portainer data
docker run --rm -v portainer_data:/data -v $(pwd):/backup 
  alpine tar czf /backup/portainer_backup.tar.gz -C /data .

18.3 Useful Portainer URLs

19. Conclusion

Portainer transforms Docker management from a command-line endeavor into an intuitive, visual experience. Whether you’re managing a single Raspberry Pi or a fleet of edge devices, Portainer provides the tools to deploy, monitor, and maintain your containerized applications with ease.

Key Takeaways

1. Start Simple: Begin with Docker Standalone installation
2. Use LTS: The LTS tag provides stability for home labs
3. Embrace Stacks: Docker Compose via Portainer is powerful
4. Secure Access: Use reverse proxies and VPNs for remote access
5. Backup Regularly: Protect your Portainer configuration
6. Explore Templates: Community templates speed up deployments
7. Monitor Everything: Integrate with Prometheus/Grafana

Next Steps

• Explore the Portainer Documentation
• Join the Portainer Community
• Try deploying a media stack or home automation platform
• Set up monitoring with Prometheus and Grafana
• Configure Edge Agents for remote device management

[!NOTE] Last Updated: January 2026 | Portainer Version: 2.33 LTS

This guide is based on validated January 2026 information. For updates, visit docs.portainer.io.