Portainer Setup Guide 2026: Visual Docker Management for Homelabs

Reading time: ~10 minutes
Audience: Docker users who prefer GUIs over terminal commands
Last tested: Portainer CE 2.25, June 2026

What Is Portainer?

Overview

Portainer Community Edition (CE) is a lightweight web-based management interface for Docker, Docker Swarm, and Kubernetes. It translates every Docker operation — starting containers, inspecting logs, managing volumes, editing Compose files — into clickable buttons and forms.

For homelab users, Portainer eliminates the need to SSH into your server every time you want to check a container log or update an image. It also provides a built-in stack editor with Git integration, making it ideal for managing 10–50 self-hosted applications.

Key Benefits

Portainer CE vs Portainer Business (BE)

For single-user homelabs, CE provides everything you need.

Prerequisites

Hardware Requirements

Software Requirements

• Docker Engine 24.0+ with Docker Compose plugin
• A Linux host (Ubuntu, Debian, Proxmox LXC, Raspberry Pi OS)
• The host must have internet access to pull images

Step 1: Create the Portainer Data Volume

Objective

Prepare persistent storage so Portainer settings survive updates.

Step-by-Step Instructions

1. SSH into your Docker host.

2. Create a dedicated Docker volume:

docker volume create portainer_data

1. Verify it exists:

docker volume ls

Why a named volume? Portainer stores user accounts, endpoint configurations, and stack definitions in /data. A named volume persists this across image updates. Bind mounts work too, but named volumes are cleaner for single-file databases.

Step 2: Deploy Portainer via Docker Compose

Objective

Launch Portainer CE with a simple, maintainable Compose file.

Step-by-Step Instructions

1. Create a directory for Portainer:

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

1. Create docker-compose.yml:

version: "3.8"

services:
  portainer:
    image: portainer/portainer-ce:2.25-alpine
    container_name: portainer
    restart: unless-stopped
    security_opt:
      - no-new-privileges:true
    volumes:
      - /etc/localtime:/etc/localtime:ro
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - portainer_data:/data
    ports:
      - "9000:9000"
      - "8000:8000"  # Only needed for Edge Agent setups

volumes:
  portainer_data:

1. Start the container:

docker compose up -d

1. Check that it is running:

docker compose ps
docker compose logs -f

You should see portainer in an Up state.

Security Note: Mounting /var/run/docker.sock gives Portainer full control over Docker on the host. This is necessary for its functionality but means you should not expose Portainer to the public internet without HTTPS + strong authentication.

Step 3: Initial Configuration and Connecting the Environment

Objective

Complete the first-run wizard and connect Portainer to your local Docker socket.

Step-by-Step Instructions

1. Open your browser and navigate to:

http://your-server-ip:9000

1. You will see the “Create the first administrator user” screen.
2. Username: Choose something memorable (e.g., admin)
3. Password: Use a strong, unique password (16+ characters)

4. Confirm password: Re-enter it

5. Click “Create user”.

6. On the “Environment Wizard” screen, select “Get Started”.

7. Choose “Docker” as the environment type, then “Start Wizard”.

8. Select “Docker environment” and click “Connect”.

Portainer will detect the local Docker socket and import all existing containers, volumes, networks, and images.

Step 4: Exploring the Portainer Interface

Objective

Learn the main sections and where to find critical functions.

Step-by-Step Instructions

Left sidebar navigation:

Key actions to try:

1. View logs: Click any container → Logs tab. Use the search box to filter.
2. Access console: Click any container → Console tab → Choose /bin/bash or /bin/sh → Connect.
3. Inspect a container: Click any container → Inspect tab to see the raw JSON Docker config.
4. Edit a running container: You cannot directly edit a running container’s config, but you can Duplicate/Edit to clone it with changes.

Step 5: Deploying a Stack from the Web Editor

Objective

Use Portainer’s built-in editor to deploy a multi-container application without touching the terminal.

Step-by-Step Instructions

1. In Portainer, click Stacks → Add stack.
2. Name the stack: whoami-demo
3. In the Web editor, paste:

version: "3.8"

services:
  whoami:
    image: traefik/whoami
    container_name: whoami-web
    ports:
      - "8080:80"
    restart: unless-stopped

1. Click Deploy the stack.
2. Navigate to Containers. You will see whoami-web running.
3. Visit http://your-server-ip:8080 to confirm it responds.

To update a stack: 1. Go to Stacks → whoami-demo → Editor. 2. Make changes (e.g., change the image tag). 3. Click Update the stack → Pull latest images.

Pro Tips

Tip 1: Use Portainer with a Reverse Proxy

Do not expose Portainer on port 9000 directly to the internet. Put it behind NGINX Proxy Manager or Traefik:

# In your reverse proxy stack
services:
  nginx-proxy-manager:
    image: jc21/nginx-proxy-manager:latest
    ports:
      - "80:80"
      - "443:443"
      - "81:81"
    # Add a Proxy Host in the NPM UI:
    # Domain: portainer.yourdomain.com
    # Forward Host: portainer
    # Forward Port: 9000

Tip 2: Back Up Portainer Data

The entire Portainer state lives in the portainer_data volume. Back it up with:

docker run --rm -v portainer_data:/data -v $(pwd):/backup alpine \
  tar czf /backup/portainer-backup.tar.gz -C /data .

Tip 3: Enable Dark Mode

Go to My account → Theme → Dark. Portainer’s light theme is blinding at 2 AM during a homelab debug session.

Tip 4: Use Git Repositories for Stacks

Instead of editing in the browser, connect Portainer to a Git repo: 1. Stacks → Add stack → Repository 2. Enter your Git URL, branch, and Compose file path 3. Enable Authentication if the repo is private 4. Enable Automatic updates to poll for changes every X minutes

This turns Portainer into a lightweight GitOps controller for your homelab.

Troubleshooting Common Issues

“Cannot connect to the Docker daemon”

• Verify the Docker service is running: sudo systemctl status docker
• Ensure /var/run/docker.sock exists on the host
• If running in LXC, ensure the container is privileged or has nesting=1 and keyctl=1

Forgotten Admin Password

If you locked yourself out, reset via CLI:

docker stop portainer
docker run --rm -v portainer_data:/data portainer/portainer-ce:2.25-alpine \
  --admin-reset-password
# Follow prompts, then restart Portainer
docker start portainer

High Memory Usage

Portainer itself uses ~50–100 MB RAM. If memory spikes, it is likely due to a large number of images or containers. Prune unused images in Images → Prune.

Conclusion

Summary

You now have Portainer CE running as a web UI for your Docker host. You can inspect logs, manage containers, deploy stacks from a browser, and even connect Git repositories for automatic deployments.

Next Steps

• Deploy Nextcloud via Portainer Stack Editor
• Compare Portainer vs Cockpit for full-system management
• Set up NGINX Proxy Manager for clean local domains
• Monitor your containers with Grafana and Prometheus

Affiliate Opportunities

• Mini PCs: Compact Docker hosts (Intel N100, Beelink SER5)
• Monitors: A small touchscreen display mounted near your server rack for quick Portainer checks
• UPS: Keep Portainer accessible during power flickers

Internal Linking Strategy

• what-is → /docker-compose-for-beginners for readers new to Docker
• stack-editor → /nextcloud-docker-compose for a real-world Compose example
• conclusion → /portainer-vs-cockpit to compare container vs system management tools

CTA

What apps are you managing with Portainer? Share your stack in the comments!

Subscribe to the WordForge newsletter for weekly self-hosting guides and Docker tips.