Comment installer Portainer sur un VPS Linux

Installer Portainer sur un VPS Linux

Portainer est une interface web pour Docker. Au lieu de tout piloter en ligne de commande, vous voyez vos conteneurs, images, volumes et stacks Docker Compose dans un tableau de bord, avec des boutons pour démarrer, arrêter, consulter les logs ou déployer un fichier Compose. Le projet est open source : le code se trouve sur le dépôt GitHub officiel.

Nous parlons ici de Portainer Community Edition (CE), la version gratuite. C’est le bon choix pour gérer un VPS personnel ou un petit labo. L’interface officielle est en anglais uniquement : les libellés des captures ci-dessous sont donc ceux que vous verrez vraiment après l’installation.

À la fin de ce guide, vous aurez :

• un conteneur Portainer qui redémarre tout seul avec Docker
• un compte administrateur protégé par mot de passe
• Docker local déjà détecté, prêt à être géré depuis le navigateur
• le port 9443 limité à votre IP, avec 8000 et 9000 laissés fermés

Voici le tableau de bord une fois Docker local connecté : menu à gauche, bandeau, infos de l’environnement, et au centre les compteurs (stacks, conteneurs, images, volumes, réseaux).

Le plan

Si Docker est déjà en place sur le VPS, ça tient en cinq gestes :

1. Créez le volume portainer_data, puis lancez le conteneur officiel.
2. Ouvrez https://xxxx:9443/ dans le navigateur (certificat auto-signé au premier essai).
3. Récupérez le setup token dans les logs, créez l’admin en moins de cinq minutes.
4. Cliquez sur Get Started pour rester sur Docker local.
5. Restreignez le port 9443 : Portainer parle à Docker avec les mêmes droits que root.

Prérequis

Avant de coller les commandes :

• vous êtes connecté en root sur un VPS Linux BoxToPlay, en général Ubuntu 24.04 ou Debian 12 et plus récents
• Docker fonctionne déjà. Si ce n’est pas le cas, suivez d’abord Installer Docker sur Linux, guide pratique pour bien démarrer
• le port 9443/tcp n’est pas déjà pris par un autre service
• vous pouvez autoriser ce port dans le pare-feu matériel de votre espace client BoxToPlay, uniquement depuis votre IP, avant de lancer Portainer

Docker doit venir du dépôt officiel, pas d’un paquet snap Ubuntu : Portainer le déconseille, et notre guide Docker utilise déjà la séquence get.docker.com.

Étape 1 : lancer Portainer

Créez d’abord le volume qui stocke la base interne de Portainer (utilisateurs, réglages, historiques). Sans ce volume, un simple docker rm efface aussi le compte admin.

docker volume create portainer_data

Téléchargez explicitement la dernière image LTS afin de ne pas réutiliser une ancienne version restée en cache :

docker pull portainer/portainer-ce:lts

Lancez ensuite l’image officielle en tag lts, pas latest. C’est la recommandation actuelle de Portainer pour un serveur.

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

Par rapport à la documentation officielle, on simplifie trois points :

• nous n’ouvrons pas le port 8000. Il sert au tunnel des Edge agents. Sur un VPS unique qui gère son propre Docker, il ne sert à rien
• nous n’ouvrons pas le port HTTP 9000 par défaut. L’accès normal passe par HTTPS sur 9443. Le 9000 n’existe plus que pour d’anciens signets
• le montage de /var/run/docker.sock est en lecture-écriture, comme dans la procédure officielle. Une version :ro casserait la création de conteneurs depuis l’interface

Vérifiez que le conteneur est bien Up :

docker ps --filter name=portainer

Exemple de sortie :

CONTAINER ID   IMAGE                        STATUS         PORTS                                                             NAMES
a1b2c3d4e5f6   portainer/portainer-ce:lts   Up 8 seconds   8000/tcp, 9000/tcp, 0.0.0.0:9443->9443/tcp, [::]:9443->9443/tcp   portainer

Les 8000/tcp et 9000/tcp sans 0.0.0.0 sont des ports exposés par l’image, pas publiés sur le VPS. Ils n’écoutent pas sur Internet. Seul 9443 est réellement ouvert, y compris en IPv6 si Docker le mappe.

Si vous tenez absolument à l’ancien HTTP en plus du HTTPS, ajoutez -p 9000:9000 dans le docker run. Ce n’est pas le chemin que nous recommandons.

Étape 2 : créer le premier administrateur

Ouvrez dans le navigateur :

https://xxxx:9443/

Remplacez xxxx par l’IP publique ou le nom DNS de votre VPS. Au premier chargement, le navigateur affiche un avertissement de certificat : Portainer génère un certificat auto-signé tant que vous n’en avez pas fourni un vrai. C’est attendu. Continuez uniquement si vous êtes bien sur votre machine.

Une instance neuve de Portainer CE exige un setup token. Sans ce jeton, n’importe qui qui tombe sur le port 9443 pendant les premières minutes pourrait s’auto-proclamer admin. Le jeton est à usage unique, uniquement pour créer le premier compte ou restaurer une sauvegarde.

Affichez-le dans les logs :

docker logs portainer

Cherchez setup_token=. Copiez uniquement la longue chaîne hexadécimale qui suit, rien d’autre. La FAQ officielle du setup token décrit le même réflexe.

Vous avez cinq minutes pour créer l’utilisateur. Passé ce délai, Portainer refuse le setup pour des raisons de sécurité. Dans ce cas, voyez le bloc repliable en bas de cet article : un redémarrage du conteneur génère un nouveau jeton.

L’écran ressemble à ceci. Le mot de passe doit faire au moins 12 caractères. Le nom d’utilisateur proposé est admin, vous pouvez le changer.

Renseignez le mot de passe deux fois, collez le setup token, puis cliquez sur Create user. Ne collez jamais ce mot de passe dans un dépôt, un ticket ou un salon Discord.

Étape 3 : rester sur Docker local

Juste après, l’Environment Wizard s’ouvre. Portainer a déjà vu le socket Docker du VPS. Pour un serveur unique, cliquez sur Get Started. Add Environments sert à brancher d’autres hôtes (agent, Kubernetes, cloud), ce n’est pas nécessaire ici. Cet écran n’apparaît qu’une fois : la connexion suivante ouvre directement l’accueil Home.

Vous arrivez ensuite sur la page Home. L’environnement s’appelle local, le statut Up, et l’URL affichée est le socket Unix /var/run/docker.sock. Cliquez sur cette carte pour ouvrir le dashboard Docker.

Étape 4 : conteneurs et stacks

Le menu de gauche donne l’essentiel du quotidien :

• Containers : liste, start/stop, logs, console
• Images : ce qui est déjà téléchargé
• Volumes et Networks
• Stacks : déploiement d’un fichier Docker Compose

La liste des conteneurs, juste après l’installation, ne montre souvent que Portainer lui-même :

Les Stacks sont vides au départ. Le plus simple : Add stack, un nom (par exemple web), le Compose collé dans l’éditeur, puis Deploy the stack. Git et l’upload existent aussi si vous préférez.

Exemple minimal pour vérifier que le déploiement web fonctionne. Il rend Nginx accessible uniquement depuis le VPS sur 127.0.0.1:8080. Pour l’exposer à Internet, choisissez explicitement une publication publique et protégez le port dans le pare-feu matériel BoxToPlay.

services:
  web:
    image: nginx:alpine
    ports:
      - "127.0.0.1:8080:80"
    restart: unless-stopped

Une fois déployée, la stack web apparaît dans Stacks, et le conteneur s’appelle en général web-web-1 dans Containers. Start, stop et logs se font depuis l’interface, sans retaper de docker compose en SSH.

Sécurité : traiter Portainer comme un accès root

Le montage de docker.sock n’est pas un détail. Qui peut se connecter à Portainer peut, en pratique, lancer n’importe quel conteneur, monter le disque de l’hôte et devenir root sur le VPS. Le mot de passe admin n’est donc pas « un login de plus » : c’est la clé de la machine.

Configurez le pare-feu matériel BoxToPlay avant le docker run, puis autorisez 9443/tcp uniquement depuis votre IP, jamais depuis 0.0.0.0/0. Vérifiez aussi la règle IPv6 si votre VPS en possède une. Terminez ensuite le setup immédiatement, sans laisser Portainer ouvert « pour plus tard ».

Un port publié avec Docker peut contourner les règles UFW classiques. Une commande comme ufw allow 9443/tcp ouvrirait en plus le port à toutes les sources au lieu de le limiter à votre IP. De même, une règle ajoutée à la chaîne iptables INPUT ne filtre pas correctement le trafic transféré vers un conteneur Docker.

Pour une restriction supplémentaire directement sur le VPS, utilisez la chaîne DOCKER-USER avec votre IP source et l’interface réseau réelles. C’est une configuration avancée qui dépend du réseau du serveur : ne copiez pas une règle générique à l’aveugle. Le pare-feu matériel BoxToPlay reste la méthode la plus simple pour limiter l’accès avant le premier démarrage.

Ne publiez pas 8000 tant que vous n’avez pas d’Edge agents, et ne partagez pas l’URL Portainer, même « juste le temps d’installer ». Portainer a déjà une authentification web : un reverse proxy avec une Basic Auth supplémentaire n’est pas obligatoire. Il reste utile si vous voulez un nom DNS et un certificat Let’s Encrypt propres.

Mettre à jour et sauvegarder

La donnée durable vit dans le volume portainer_data. Pour mettre à jour :

docker pull portainer/portainer-ce:lts
docker stop portainer
docker rm portainer

Relancez exactement le même docker run qu’à l’installation (mêmes ports, mêmes volumes, même tag lts). Le volume n’est pas recréé : comptes et réglages restent.

Pour une sauvegarde manuelle, arrêtez le conteneur puis archivez le volume, ou snapshottez le VPS depuis l’espace client BoxToPlay avant une mise à jour importante. Le volume nommé portainer_data survit à docker rm, y compris avec l’option -v. L’installation n’est réellement effacée que si vous supprimez explicitement ce volume, par exemple avec docker volume rm portainer_data une fois le conteneur retiré.

docker stop portainer
docker start portainer
docker logs portainer

Et après

Portainer ne remplace pas les sauvegardes, le pare-feu ni les mises à jour du système. C’est pratique tous les jours, et dangereux s’il reste ouvert à Internet.

Si vous cherchez un VPS Linux déjà livré en root, avec Docker prêt à installer et un pare-feu matériel dans l’espace client, vous pouvez lancer votre serveur chez BoxToPlay.