Pourquoi installer Portainer sur votre VPS
Gérer Docker en ligne de commande devient vite fastidieux quand vous accumulez les conteneurs : retrouver les logs d'un service, inspecter un volume, redémarrer une stack ou vérifier l'utilisation des ressources demande de jongler entre plusieurs commandes. Portainer expose tout cela dans une interface web : vous voyez l'état de chaque conteneur, consultez les logs en direct, ouvrez une console interactive, déployez des stacks via un éditeur de docker-compose et surveillez la consommation CPU/RAM. Contrairement à un PaaS comme CapRover ou Dokku, Portainer ne build pas votre code : c'est un outil d'administration et de visualisation de votre environnement Docker existant. Il est parfait pour les équipes qui veulent un accès clair et délégable à un serveur Docker sans donner d'accès SSH à tout le monde.
Ce que Portainer simplifie au quotidien
- Vue d'ensemble en temps réel de tous vos conteneurs, images, volumes et réseaux.
- Déploiement de stacks via un éditeur
docker-composeintégré, sans toucher au SSH. - Logs en direct et console interactive dans chaque conteneur, directement dans le navigateur.
- Gestion fine des droits : créez des comptes et des équipes avec des accès limités.
- Surveillance de la consommation CPU, RAM et réseau de chaque service.
- Gestion de plusieurs hôtes Docker ou clusters Swarm depuis une seule interface.
Prérequis pour Portainer
Portainer est extrêmement léger car il ne fait qu'administrer Docker, sans builder ni base de données lourde. Un VPS d'1 Go de RAM et 1 vCPU est largement suffisant pour faire tourner Portainer lui-même ; dimensionnez ensuite votre VPS selon les applications que vous comptez héberger dessus. Prévoyez tout de même 20 Go de disque SSD pour les images Docker. Docker Engine doit être installé au préalable (Portainer se connecte au socket /var/run/docker.sock). Un nom de domaine portainer.mondomaine.com et un port 443 ouvert sont recommandés pour exposer l'interface en HTTPS. Important : Portainer donne un contrôle total sur Docker, donc ne laissez jamais son interface directement exposée sur Internet sans reverse proxy et sans authentification forte. Côté ports, la documentation d'installation actuelle publie 9443 (interface HTTPS à certificat auto-signé) ; le port 8000 (tunnel TCP) ne sert que pour les agents Edge et le 9000 (HTTP) est un port optionnel hérité des anciennes versions. Nous n'ouvrons ici que le 9443, et seulement le temps de la configuration.
Déployer Portainer en 5 étapes
Préparer Docker sur le VPS
Installez Docker si ce n'est pas déjà fait :
curl -fsSL https://get.docker.com | sh. Vérifiez avecdocker ps. Créez un volume dédié pour la persistance de Portainer :docker volume create portainer_data.Lancer le conteneur Portainer
Démarrez Portainer CE :
docker run -d -p 9443:9443 --name portainer --restart=always -v /var/run/docker.sock:/var/run/docker.sock -v portainer_data:/data portainer/portainer-ce:lts. La documentation officielle d'installation utilise le taglts(suivi à support long) ; c'est celui que nous retenons pour un serveur de production, plutôt quelatest. L'interface devient accessible sur le port 9443 en HTTPS auto-signé.Créer le compte administrateur
Relevez d'abord le jeton d'installation dans les journaux :
docker logs portainer, lignesetup_token=. Depuis les versions 2.43 et 2.39.4, une instance neuve l'exige pour créer le premier administrateur. Ouvrez ensuitehttps://IP_DU_VPS:9443: le compte doit être créé dans les 5 minutes suivant le premier démarrage, sinon Portainer s'arrête par sécurité (message « timed out for security purposes »). Dans ce cas,docker stop portainerpuisdocker start portainerredonne 5 minutes. Choisissez un mot de passe fort (12 caractères au minimum).Exposer proprement via un reverse proxy
Placez Caddy ou Nginx Proxy Manager devant Portainer pour servir l'interface sur
portainer.mondomaine.comavec un vrai certificat Let's Encrypt. Fermez ensuite l'accès direct au port 9443. Attention : un port publié par Docker contourne les règlesufw(Docker le détourne avant les chaînes que ufw filtre), doncufw deny 9443ne suffit pas. Recréez plutôt le conteneur avec-p 127.0.0.1:9443:9443, de sorte que seul le proxy local puisse l'atteindre.Déployer votre première stack
Dans le menu « Stacks », cliquez sur « Add stack », collez un fichier
docker-compose.ymldans l'éditeur (par exemple une app + PostgreSQL), nommez la stack et cliquez sur « Deploy the stack ». Portainer crée les conteneurs, le réseau et les volumes, et vous suivez leur état en temps réel.
Activez les « Access Controls » de Portainer pour déléguer la gestion d'une stack précise à un développeur sans lui donner accès à l'ensemble du serveur. Pour aller plus loin, déployez un agent Portainer sur un second VPS et rattachez-le à votre instance principale : vous administrez alors plusieurs serveurs Docker depuis un point unique. Sauvegardez régulièrement le volume portainer_data, qui contient vos utilisateurs, endpoints et définitions de stacks, ainsi que les dossiers de stacks issues de Git (compose/).
Déployer depuis Git avec les mises à jour GitOps
Coller un fichier compose suffit pour démarrer, mais une stack liée à un dépôt Git se met à jour toute seule et garde son historique ailleurs que dans l'interface. Dans « Stacks > Add stack », choisissez « Git Repository », puis renseignez la source, la référence (branche) et le chemin du fichier compose. Portainer clone alors le dépôt dans son volume de données, sous compose/<id de la stack>. C'est ce mécanisme, et lui seul, qui est en cause dans le dépannage ci-dessous.
Les réglages à connaître
- Source, référence et « Compose path » : le dépôt, la branche et le chemin du fichier compose depuis la racine ; « Additional paths » fusionne d'autres fichiers YAML, comme plusieurs options
-f. - « GitOps updates » par interrogation : Portainer vérifie le dépôt à intervalle régulier (« Fetch interval »).
- « GitOps updates » par webhook : Portainer génère une URL à appeler depuis votre dépôt ou une action GitHub pour déclencher la mise à jour à la demande.
- « Re-pull image » : tire à nouveau les images à chaque mise à jour, comme
--pull=always. - « Force redeployment » : redéploie à chaque échéance ou webhook, même sans changement dans le dépôt, en écrasant les modifications locales.
- Bouton « Pull and redeploy » de la page de la stack : récupère le dernier commit et redéploie immédiatement.
Dépannage : « Unable to move git repository directory: Target path already exists »
Symptôme exact : sur une stack déployée depuis Git, « Pull and redeploy » (ou la mise à jour GitOps automatique) échoue avec Unable to move git repository directory: Target path already exists, et les conteneurs ne sont pas mis à jour. C'est le problème n° 10428 du dépôt portainer/portainer, ouvert en octobre 2023 sur Portainer CE 2.19.1 (dépôt GitHub privé, nœud Edge), décrit comme intermittent : un redémarrage ou l'attente le faisaient parfois passer. Il est encore rapporté en 2026.
État à la source, relevé le 29 octobre 2026 : l'issue est toujours ouverte. Elle porte les étiquettes bug et priorité « 2 - High », a été assignée à un développeur de Portainer en juillet 2026 et l'étiquette de version cible est passée de 3.0.0 à 3.1.0 en octobre 2026. Aucune pull request n'y est liée, et la seule correction proposée est un commit d'un fork d'un utilisateur, resté non fusionné. Le correctif officiel n'existe donc pas à cette date : le contournement ci-dessous reste d'actualité, et vous ne devez pas attendre une version précise pour le résoudre.
Causes rapportées par les utilisateurs (hypothèses, non confirmées par l'éditeur)
- Un dossier résiduel
<id>-olddanscompose/: pendant une mise à jour, Portainer semble renommer le dossier de la stack en<id>-oldavant de déplacer le nouveau clone ; s'il en reste un d'une tentative précédente, le déplacement échoue. - Un déploiement interrompu : un conteneur Portainer figé puis redémarré en plein déploiement, ou une page rafraîchie pendant « Pull and redeploy », a laissé l'état incohérent chez plusieurs utilisateurs (le mainteneur n'a pas pu le reproduire ainsi).
- Des images volumineuses : le premier rapporteur soupçonnait un dépassement de délai sur une stack contenant une image de près de 2 Go.
- Variante de février 2026 : l'erreur devient
stat /data/compose/61: no such file or directory, c'est-à-dire que le dossier de la stack a disparu. Le contournement ci-dessous n'aide pas dans ce cas.
Contournement prudent en 6 étapes
Repérer la stack et son identifiant
Notez le nom de la stack en échec et son identifiant numérique, qui est le nom du dossier
compose/<id>. Ne touchez jamais au dossier<id>lui-même : seul le dossier<id>-oldest visé.Arrêter Portainer et sauvegarder le volume
Arrêtez Portainer pour figer sa base :
docker stop portainer. Puis archivez tout le volume :docker run --rm -v portainer_data:/data -v "$PWD":/backup alpine tar czf /backup/portainer_data-avant-correctif.tgz -C /data .. Vérifiez que l'archive existe et n'est pas vide avant d'aller plus loin.Lister le dossier compose
Affichez son contenu :
docker run --rm -v portainer_data:/data alpine ls -la /data/compose. Cherchez un dossier dont le nom est l'identifiant de la stack suivi de-old(par exemple61-old).Mettre le dossier résiduel de côté, sans le supprimer
Déplacez-le hors du volume :
docker run --rm -v portainer_data:/data -v "$PWD":/backup alpine mv /data/compose/61-old /backup/. Remplacez 61 par votre identifiant. Les utilisateurs rapportent qu'effacer ce dossier suffit ; le mettre de côté donne le même effet en gardant un retour arrière.Redémarrer et relancer la mise à jour
docker start portainer, puis « Pull and redeploy » sur la stack. Contrôlez que les conteneurs ont bien été recréés avec la nouvelle version, pas seulement que le message d'erreur a disparu.Si l'échec persiste
Si aucun dossier
-oldn'existe ou si le dossier<id>est absent, ce contournement ne s'applique pas. La solution rapportée est alors de supprimer et recréer la stack depuis Git. Avant cela, vérifiez que vos données applicatives sont dans des volumes nommés et sauvegardez-les. Ne restaurez l'archive de l'étape 2 que si quelque chose s'est mal passé.
Prévention. Aucune de ces mesures n'est un correctif garanti, puisque la cause n'est pas confirmée par l'éditeur : elles réduisent seulement les occasions de laisser un dossier -old derrière vous. Ne rafraîchissez pas la page et ne redémarrez pas Portainer pendant un « Pull and redeploy ». Tirez à l'avance les images volumineuses avec docker pull pour raccourcir le déploiement. Après chaque échec de mise à jour, regardez tout de suite si un dossier -old traîne dans compose/. Sauvegardez portainer_data avant les mises à jour de Portainer. Pour un service critique, ne dépendez pas du seul bouton de l'interface : gardez un déploiement de secours en docker compose pull && docker compose up -d sur le serveur. Surveillez l'issue #10428 pour savoir quand un correctif arrive.
Installer Portainer depuis le Marketplace ServOrbit
Tout ce qui précède se fait à la main, et c'est utile de savoir le faire. Si vous préférez ne pas le faire, Portainer CE figure dans le [Marketplace ServOrbit](/applications/deploiement/portainer) et s'installe sur votre VPS en un clic. Le gabarit déploie portainer/portainer-ce:latest en mode Docker Compose, monte le socket /var/run/docker.sock et crée le volume portainer_data pour la persistance — sans session SSH pour la configuration de base. L'interface n'est pas publiée sur Internet : le gabarit la lie à l'adresse locale du serveur (127.0.0.1, port HTTP 9000), donc vous y accédez par un tunnel SSH ou en ajoutant un domaine personnalisé depuis votre espace client. À la première ouverture, Portainer vous guide via un assistant pour créer votre compte administrateur : s'il réclame un jeton d'installation, il se trouve dans les journaux du conteneur (docker compose logs, ligne setup_token=). Comme tout gabarit du Marketplace, il est fourni sous forme de guide d'installation, sans prise en charge de l'application elle-même. Si vous préférez rester sur la branche à support long, remplacez le tag latest par lts dans le fichier compose.
