Introduction
Portainer simplifies container administration:
- Visual dashboards (containers, images, volumes, networks)
- Multi-environment (manage local Docker + remote K8s cluster from one UI)
- Integrated Docker Compose / Kubernetes YAML editor
- Logs, exec, file browser directly in browser
- RBAC: roles and team permissions
- Ready app templates
- Webhooks for deployments
- Free (Community Edition) or Business (commercial)
For sysadmins who want a UI rather than CLI, or for teams where not everyone is technical.
Prerequisites
- Linux VPS with Docker installed
- Root access
- Port 9443 (Portainer HTTPS) open
Step 1: Portainer CE deployment
sudo docker volume create portainer_data
sudo 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:latest
Step 2: First access
Visit https://VPS_IP:9443. Accept self-signed cert. Create admin account (12+ char password).
Step 3: Configure local environment
After login, Portainer auto-detects local Docker via /var/run/docker.sock.
Click Get Started > Docker. local environment appears.
Step 4: Reverse proxy with valid HTTPS
server {
listen 443 ssl http2;
server_name portainer.your-domain.com;
location / {
proxy_pass https://127.0.0.1:9443;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_ssl_verify off;
}
}
sudo certbot --nginx -d portainer.your-domain.com
Step 5: Deploy container via UI
Containers > Add container.
- Name:
nginx-test - Image:
nginx:alpine - Port mapping: 8080 -> 80
- Network:
bridge - Restart policy:
Unless stopped
Click Deploy the container.
Step 6: Docker Compose stacks
Stacks > Add stack. Web editor:
services:
app:
image: nginx:alpine
ports:
- "8081:80"
volumes:
- app_data:/usr/share/nginx/html
restart: unless-stopped
redis:
image: redis:7-alpine
restart: unless-stopped
volumes:
app_data:
Click Deploy the stack.
Step 7: App templates
App Templates: list of preconfigured apps (WordPress, NextCloud, GitLab).
Click template, fill vars (passwords, domain), deploy.
You can create custom JSON templates and host them.
Step 8: Add remote environment
To manage remote Docker / K8s from same Portainer:
Environments > Add environment:
- Docker Standalone: Portainer agent on remote
- Docker Swarm: agent on swarm
- Kubernetes: via kubeconfig
- Edge Agent: for edge clusters (Pi, IoT)
On remote:
sudo 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:latest
Add in Portainer URL tcp://REMOTE_IP:9001.
Step 9: Users and roles
Users > Add user.
Available roles:
- Administrator: full power
- User: per env / resource permissions
Create dev user, give access to staging env only.
Step 10: Resource Control (RBAC)
On each container/stack/volume, define owner and access. Useful in multi-tenant.
Resource controls:
- Public: everyone
- Restricted: listed users / teams only
- Administrators only
Step 11: Webhooks for CI/CD
On a container, Webhook > Enable. Portainer generates URL.
From CI:
curl -X POST https://portainer.your-domain.com/api/webhooks/XXXX-XXXX
Portainer redeploys the container (re-pulls image and restarts).
Step 12: Backup and restore
Settings > Backup. Download .tar.gz with all Portainer config (users, environments, stacks).
To restore: reinstall Portainer then Settings > Restore.
⚠️ Backup doesn't contain Docker volumes. Back them up separately.
Troubleshooting
Can't log in
sudo docker logs portainer
Forgot admin password? Reset:
sudo docker stop portainer
sudo docker run --rm -v portainer_data:/data portainer/helper-reset-password
sudo docker start portainer
"Cannot connect to Docker daemon"
Socket not properly mounted:
sudo docker inspect portainer | grep Mounts
Verify /var/run/docker.sock:/var/run/docker.sock.
Reverse proxy "502 Bad Gateway"
Portainer listens HTTPS on 9443. Use https:// and proxy_ssl_verify off.
Slow performance
Increase Docker resources:
sudo docker update --memory=2g --cpus=2 portainer
Useful commands
sudo docker ps -f name=portainer
sudo docker logs portainer
# Update
sudo docker pull portainer/portainer-ce:latest
sudo docker stop portainer
sudo docker rm portainer
# Relaunch with same install command
# Manual volume backup
sudo docker run --rm -v portainer_data:/data -v $(pwd):/backup busybox tar czf /backup/portainer-$(date +%F).tar.gz /data
# Reset admin password (stop Portainer first)
sudo docker run --rm -v portainer_data:/data portainer/helper-reset-password
sudo docker logs -t -f portainer
Conclusion
Portainer simplifies your life when:
- You manage multiple environments
- You work in a team
- You want to delegate without SSH access
- You want to visualize container state quickly
Limits:
- Not a GitOps tool (use ArgoCD/Flux)
- Community Edition has some RBAC limits (Business for enterprise)
Going further:
- Combine with Watchtower for container auto-updates
- Enable Portainer Edge to manage IoT
- For full GitOps, look at ArgoCD + Portainer as complement
Resources
- Official docs: https://docs.portainer.io
- Site: https://www.portainer.io
- GitHub: https://github.com/portainer/portainer
- App Templates: https://github.com/portainer/templates