# Portainer Container Management

> Complete Docker and Kubernetes management solution with beautiful web UI, user management, and multi-environment support.

- Category: DevOps & CI/CD
- Difficulty: beginner
- Components: portainer, portainer-agent
- Tags: portainer, docker, kubernetes, management, gui, devops
- Source: https://docker.recipes/devops/portainer-complete

## Overview

Portainer is a universal container management platform that transforms complex Docker, Kubernetes, and Docker Swarm operations into an intuitive web-based interface. Originally created to democratize container management, Portainer eliminates the need for command-line expertise while providing enterprise-grade features like role-based access control, multi-environment management, and GitOps workflows. The platform has evolved from a simple Docker GUI into a comprehensive container orchestration solution trusted by both homelab enthusiasts and enterprise teams.

This deployment combines Portainer CE with its companion agent to create a powerful management hub for your container infrastructure. The main Portainer service provides the web interface and core management capabilities, while the Portainer agent enables secure communication with remote Docker environments and edge devices. Together, they form a centralized control plane that can manage multiple Docker hosts, Swarm clusters, and Kubernetes environments from a single dashboard.

This stack is ideal for teams transitioning from manual Docker management to a more structured approach, system administrators managing multiple hosts, and organizations seeking to provide controlled container access to developers without exposing underlying infrastructure. The combination offers visual stack deployment, template-based application installation, and comprehensive logging and monitoring capabilities that bridge the gap between simple container tools and complex enterprise platforms like Rancher.

## Features

- Multi-platform container orchestration supporting Docker, Docker Swarm, and Kubernetes clusters
- Visual stack deployment with drag-and-drop Docker Compose editing and validation
- Template marketplace with pre-configured applications and custom template support
- Role-based access control with team management and environment-specific permissions
- Edge agent deployment for managing remote locations and IoT devices
- GitOps integration with automatic stack updates from Git repositories
- Container registry management with support for private registries and image scanning
- Real-time resource monitoring with container logs, stats, and performance metrics

## Use cases

- Homelab management for self-hosted services and personal development environments
- Small to medium team Docker environments requiring user access control and collaboration
- Multi-site container deployments with centralized management across edge locations
- Development teams needing visual container management without CLI complexity
- Educational environments for teaching containerization and orchestration concepts
- Rapid prototyping and testing with template-based application deployment
- Legacy infrastructure modernization with gradual container adoption

## Prerequisites

- Docker Engine 20.10+ with Docker Compose plugin installed
- Minimum 256MB RAM available for Portainer CE (512MB recommended for production)
- Ports 9443 (HTTPS UI) and 8000 (tunnel server) available and accessible
- Docker socket access permissions for container management operations
- SSL/TLS certificates for production deployments (self-signed acceptable for development)
- Network connectivity between Portainer server and any remote Docker hosts or agents

## docker-compose.yml

```yaml
services:
  portainer:
    image: portainer/portainer-ce:latest
    ports:
      - "9443:9443"
      - "8000:8000"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - portainer_data:/data
    restart: always
    networks:
      - portainer_net

  portainer-agent:
    image: portainer/agent:latest
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - /var/lib/docker/volumes:/var/lib/docker/volumes
    networks:
      - portainer_net

volumes:
  portainer_data:

networks:
  portainer_net:
```

## .env

```bash
# Portainer
# Portainer at https://localhost:9443
# Create admin account on first login
```

## Usage notes

- Portainer at https://localhost:9443
- Create admin on first access
- Manage Docker/Swarm/K8s
- Agent for remote environments
- Edge agent for edge devices

## Troubleshooting

- Cannot access Portainer UI after startup: Verify port 9443 is not blocked by firewall and container logs show 'Portainer started on :9443'
- Docker socket permission denied errors: Add your user to docker group with 'usermod -aG docker $USER' and restart session
- Agent connection fails with 'tunnel server unreachable': Ensure port 8000 is accessible from agent host and check network connectivity
- Stack deployment fails with 'compose file invalid': Use Portainer's built-in validator or verify YAML syntax and indentation
- High memory usage or slow performance: Increase container memory limits and consider using Portainer Business Edition for better resource optimization
- Lost admin access after initial setup: Reset admin password by stopping container, removing portainer_data volume, and recreating stack

