Introduction
Portainer simplifie l'administration des containers :
- Dashboards visuels (containers, images, volumes, networks)
- Multi-environments (gerez Docker local + cluster K8s distant depuis la meme UI)
- Editor Docker Compose / Kubernetes YAML integre
- Logs, exec, file browser direct dans le navigateur
- RBAC : roles et permissions par equipe
- Templates d'apps prets
- Webhooks pour les deploiements
- Gratuit (Community Edition) ou Business (commercial)
Pour des admins systeme qui veulent une UI plutot que la CLI, ou pour des equipes ou tout le monde n'est pas tech.
Prerequis
- VPS Linux avec Docker installe
- Acces root
- Port 9443 (HTTPS Portainer) ouvert
Etape 1 : Deploiement Portainer CE (Community Edition)
Creez le volume :
sudo docker volume create portainer_data
Lancez Portainer :
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
Etape 2 : Premier acces
Visitez https://IP_VPS:9443. Acceptez le cert auto-signe.
Creez le compte admin (mdp 12+ caracteres).
Etape 3 : Configurer l'environnement local
Apres login, Portainer detecte automatiquement le Docker local via /var/run/docker.sock.
Cliquez Get Started > Docker. L'environnement local apparait.
Etape 4 : Reverse proxy avec HTTPS valide
Pour eviter le cert auto-signe, mettez Portainer derriere Nginx + Let's Encrypt :
server {
listen 443 ssl http2;
server_name portainer.votre-domaine.fr;
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; # Portainer utilise son cert self-signed en interne
}
}
sudo certbot --nginx -d portainer.votre-domaine.fr
Etape 5 : Deployer un container via UI
Containers > Add container.
Remplissez :
- Name :
nginx-test - Image :
nginx:alpine - Port mapping : 8080 -> 80
- Network :
bridge - Restart policy :
Unless stopped
Cliquez Deploy the container.
Verifiez :
curl http://IP_VPS:8080
Etape 6 : Stacks Docker Compose
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:
Cliquez Deploy the stack. Portainer cree le stack via docker-compose.
Etape 7 : Templates d'apps
App Templates : liste d'apps preconfigurees (WordPress, NextCloud, GitLab, etc.).
Cliquez sur un template, remplissez les variables (mdp, domaine), deploy.
Vous pouvez creer vos propres templates JSON et les heberger.
Etape 8 : Ajouter un environnement distant
Pour gerer un Docker / K8s distant depuis le meme Portainer :
Environments > Add environment :
- Docker Standalone : agent Portainer sur le distant
- Docker Swarm : agent sur le swarm
- Kubernetes : via kubeconfig
- Edge Agent : pour clusters edge (Pi, IoT)
Sur le distant, lancez l'agent :
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
Et ajoutez dans Portainer l'URL tcp://IP_DISTANT:9001.
Etape 9 : Utilisateurs et roles
Users > Add user.
Roles disponibles :
- Administrator : tout pouvoir
- User : selon les permissions d'environment et ressources
Creez un user dev et donnez-lui acces a l'environment staging uniquement.
Etape 10 : Resource Control (RBAC)
Sur chaque container/stack/volume, vous pouvez definir le proprietaire et qui y a acces. Practique en multi-tenant.
Resource controls :
- Public : tout le monde y accede
- Restricted : seuls les users / teams listes
- Administrators only
Etape 11 : Webhooks pour CI/CD
Sur un container, Webhook > Enable. Portainer genere une URL.
Vous pouvez appeler cette URL depuis votre CI :
curl -X POST https://portainer.votre-domaine.fr/api/webhooks/XXXX-XXXX
Portainer redeploie le container (re-pull l'image et restart).
Etape 12 : Backup et restore
Settings > Backup. Telechargez un fichier .tar.gz qui contient toute la config Portainer (users, environments, stacks).
Pour restore : reinstallez Portainer puis Settings > Restore.
⚠️ Le backup ne contient pas les volumes Docker eux-memes. Sauvegardez-les separement.
Depannage
Login impossible
Verifiez :
sudo docker logs portainer
Si vous avez oublie le mdp admin, reinitialisez :
sudo docker stop portainer
sudo docker run --rm -v portainer_data:/data portainer/helper-reset-password
sudo docker start portainer
Affiche un nouveau mdp.
"Cannot connect to Docker daemon"
Le socket Docker n'est pas mount correctement :
sudo docker inspect portainer | grep Mounts
Verifiez /var/run/docker.sock:/var/run/docker.sock.
Reverse proxy : "502 Bad Gateway"
Portainer ecoute en HTTPS sur 9443. Verifiez que votre proxy_pass utilise https:// et que proxy_ssl_verify off.
Performance lente
Si vous avez beaucoup de containers, Portainer peut etre lent. Augmentez les resources Docker :
sudo docker update --memory=2g --cpus=2 portainer
Commandes utiles
# Status
sudo docker ps -f name=portainer
sudo docker logs portainer
# Update Portainer
sudo docker pull portainer/portainer-ce:latest
sudo docker stop portainer
sudo docker rm portainer
# Relancez avec la meme commande qu'a l'install
# Volumes (sauvegarde manuelle)
sudo docker run --rm -v portainer_data:/data -v $(pwd):/backup busybox tar czf /backup/portainer-$(date +%F).tar.gz /data
# Reset password admin (Portainer doit etre stop avant)
sudo docker run --rm -v portainer_data:/data portainer/helper-reset-password
# Logs avec timestamps
sudo docker logs -t -f portainer
Conclusion
Portainer simplifie la vie quand :
- Vous gerez plusieurs environnements
- Vous travaillez en equipe
- Vous voulez deleguer sans donner l'acces SSH
- Vous voulez visualiser rapidement l'etat de vos containers
Limites :
- Pas un outil GitOps (utilisez ArgoCD/Flux pour ca)
- Le mode Community a quelques limites RBAC (Business pour les besoins enterprise)
Pour aller plus loin :
- Combinez avec Watchtower pour les auto-updates de containers
- Activez Portainer Edge pour gerer du IoT
- Pour une approche full GitOps, regardez ArgoCD + Portainer en complement
Ressources
- Documentation officielle : https://docs.portainer.io
- Site officiel : https://www.portainer.io
- Github : https://github.com/portainer/portainer
- App Templates : https://github.com/portainer/templates