FR

Applications

Installer Portainer CE et sécuriser son accès

Installez Portainer Community Edition avec Docker Compose sur Debian ou Ubuntu : accès par tunnel SSH ou HTTPS restreint, risque du socket Docker, mises à jour et sauvegarde.

11 min de lecture, mis à jour le 18 novembre 2026

Sur cette page

Vos valeurs

Renseignez-les une fois, les commandes du guide se mettent à jour.

Portainer Community Edition (CE) est une interface web qui permet de gérer les conteneurs, images, volumes, réseaux et stacks d'un serveur Docker. Ce guide vous explique comment l'installer avec Docker Compose sans exposer son interface sur Internet.

À la fin du guide, Portainer n'écoute que sur l'adresse locale du serveur. Vous y accédez par un tunnel SSH ou, si vous le souhaitez, en HTTPS depuis votre seule adresse IP. Vous savez aussi mesurer le risque lié au socket Docker, mettre à jour Portainer et sauvegarder ses données.

Commander un serveur

Ce guide s'applique aux serveurs que vous administrez vous-même :

Prérequis

  • Un serveur sous Debian 12 ou 13, ou Ubuntu 22.04 ou 24.04
  • Un accès SSH avec un utilisateur disposant de sudo
  • Docker Engine et Docker Compose installés depuis le dépôt officiel, comme expliqué dans le guide Installer Docker Engine et Docker Compose. N'utilisez pas le paquet snap de Docker
  • Un client SSH sur votre poste

Les commandes docker supposent que votre utilisateur appartient au groupe docker. Sinon, ajoutez sudo devant.

Ce guide utilise la version 2.45.3, la version LTS la plus récente au moment de la rédaction. Contrôlez la dernière version sur la page des versions de Portainer et la liste des versions de Docker prises en charge.

Ports utilisés

Port Rôle Publication dans ce guide À ouvrir dans le pare-feu
22/tcp SSH et tunnel vers Portainer Service SSH du serveur Oui, s'il ne l'est pas déjà
9443/tcp Interface HTTPS de Portainer 127.0.0.1 uniquement Non
9000/tcp Interface HTTP, pour un reverse proxy local 127.0.0.1, seulement avec l'option Caddy Non
8000/tcp Tunnel des Edge Agents Non publié Non
80 et 443/tcp Caddy Seulement avec l'option Caddy Seulement avec l'option Caddy

Comprendre le risque du socket Docker

Portainer pilote Docker à travers le socket /var/run/docker.sock, monté dans son conteneur. Ce socket donne accès à toute l'API de Docker, dont le démon s'exécute en root.

Un compte qui contrôle Docker peut par exemple lancer un conteneur privilégié ou monter la racine / du serveur dans un conteneur, puis lire et modifier n'importe quel fichier. La documentation de Docker rappelle que seuls des utilisateurs de confiance doivent pouvoir contrôler le démon.

Quelques conséquences pratiques :

  • Le montage :ro du socket ne vous protège pas : il concerne le fichier, pas les actions envoyées à l'API Docker
  • Réservez le rôle d'administrateur aux personnes qui pourraient déjà être root sur le serveur
  • Appliquez rapidement les mises à jour de Portainer
  • Préférez le tunnel SSH, qui évite d'exposer l'interface

Étape 1 : créer le projet Compose

Créez un dossier pour Portainer :

Terminal
sudo mkdir -p /opt/portainer
sudo chown "$USER": /opt/portainer
cd /opt/portainer
nano compose.yaml

Collez cette configuration :

YAML
services:
  portainer:
    image: portainer/portainer-ce:2.45.3
    container_name: portainer
    restart: unless-stopped
    ports:
      - "127.0.0.1:9443:9443"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - portainer_data:/data

volumes:
  portainer_data:
    name: portainer_data

Le port 8000 n'est pas publié, car il ne sert qu'aux Edge Agents. Validez le fichier et téléchargez l'image :

Terminal
docker compose config --quiet
docker compose pull

Étape 2 : ouvrir le tunnel SSH

Portainer laisse 5 minutes pour créer le premier administrateur après son démarrage. Préparez donc le tunnel avant de lancer le conteneur.

Dans un terminal sur votre poste, exécutez :

Terminal
ssh -N -L 9443:127.0.0.1:9443 VOTRE_USER@VOTRE_IP_SERVEUR

La commande n'affiche rien et reste active : c'est normal. Laissez ce terminal ouvert pendant que vous utilisez Portainer et fermez le tunnel ensuite avec Ctrl+C. Si le port 9443 est déjà pris sur votre poste, utilisez par exemple -L 19443:127.0.0.1:9443 et l'adresse https://localhost:19443.

Étape 3 : démarrer Portainer

Sur le serveur, lancez le conteneur puis récupérez le jeton d'installation :

Terminal
cd /opt/portainer
docker compose up -d
docker compose ps
docker logs portainer 2>&1 | grep setup_token | tail -n 1

La dernière commande affiche une ligne setup_token=.... Ce jeton à usage unique, exigé depuis les versions 2.39.4 et 2.43, empêche un tiers de s'approprier une instance neuve. Il est régénéré à chaque démarrage tant qu'aucun administrateur n'existe.

Étape 4 : créer le compte administrateur

  1. Ouvrez https://localhost:9443 dans votre navigateur.
  2. Acceptez l'avertissement de sécurité : Portainer utilise par défaut un certificat auto-signé. Le trafic passe dans le tunnel SSH.
  3. Choisissez un nom d'utilisateur et un mot de passe unique d'au moins 12 caractères.
  4. Collez la valeur du jeton dans le champ Setup token, puis validez.
  5. Sur l'écran Edge Compute, choisissez Skip si vous ne gérez pas d'Edge Agents.
  6. Dans l'assistant, cliquez sur Get Started : l'environnement local est détecté automatiquement.

Conservez ce mot de passe dans un gestionnaire de mots de passe.

Vérifier le résultat

Dans Portainer, ouvrez l'environnement local : le conteneur portainer doit apparaître dans la liste Containers.

Sur le serveur, contrôlez ensuite l'adresse d'écoute :

Terminal
docker ps --filter name=portainer --format '{{.Names}} {{.Ports}}'
curl -kI https://127.0.0.1:9443

La sortie doit contenir 127.0.0.1:9443->9443/tcp, et curl doit renvoyer une réponse HTTP. Depuis une autre machine, sans tunnel, vérifiez enfin que rien n'est accessible :

Terminal
nmap -Pn -p 8000,9000,9443 VOTRE_IP_SERVEUR

Aucun de ces ports ne doit apparaître comme open.

Limiter les droits dans Portainer

Quelques réglages réduisent les risques si plusieurs personnes utilisent l'interface :

Réglage Emplacement Recommandation
Comptes individuels User-related > Users Un compte par personne, sans le rôle administrateur sauf nécessité
Durée de session Settings > Authentication Réduisez la valeur par défaut de 8 heures si besoin
Restrictions Docker Environnement local > Host > Setup > Docker Security Settings Activez notamment Hide bind mounts for non-administrators et Hide privileged mode for non-administrators

Ces restrictions concernent uniquement les comptes non administrateurs. Elles ne limitent pas ce qu'un administrateur peut faire.

Option : publier Portainer en HTTPS avec Caddy

Le tunnel SSH suffit dans la plupart des cas. Si vous avez besoin d'une adresse web, placez Portainer derrière un reverse proxy et limitez l'accès à votre adresse IP.

Vous devez avoir suivi le guide Caddy en reverse proxy et créé un enregistrement A pour portainer.votre-domaine.com vers VOTRE_IP_SERVEUR.

Ajoutez le port HTTP local dans /opt/portainer/compose.yaml :

YAML
    ports:
      - "127.0.0.1:9443:9443"
      - "127.0.0.1:9000:9000"

Appliquez la modification :

Terminal
cd /opt/portainer
docker compose up -d

Ajoutez ensuite ce site dans /etc/caddy/Caddyfile :

caddyfile
portainer.votre-domaine.com {
	@allowed client_ip VOTRE_IP

	handle @allowed {
		reverse_proxy 127.0.0.1:9000
	}

	handle {
		abort
	}
}

Caddy étant installé sur le serveur et non dans Docker, UFW s'applique à ses ports. Ouvrez-les, puis rechargez la configuration :

Terminal
sudo ufw allow 80,443/tcp comment 'Caddy'
sudo -u caddy caddy validate --config /etc/caddy/Caddyfile --adapter caddyfile
sudo systemctl reload caddy

Ouvrez https://portainer.votre-domaine.com depuis votre adresse autorisée : la page de connexion doit s'afficher. Depuis une autre connexion, par exemple un téléphone en données mobiles, la connexion doit être coupée.

Si votre adresse IP change souvent, réservez plutôt l'accès à un réseau privé avec WireGuard ou Tailscale.

Mettre à jour Portainer

Sauvegardez d'abord Portainer, puis lisez les notes de version. Remplacez le tag de l'image dans compose.yaml par la nouvelle version, puis exécutez :

Terminal
cd /opt/portainer
nano compose.yaml
docker compose pull
docker compose up -d
docker compose images

Vos autres conteneurs ne sont pas arrêtés. Reconnectez-vous ensuite pour contrôler que l'environnement local répond. Les données restent dans le volume portainer_data.

Le tag mobile lts existe aussi, mais une version précise vous permet de choisir le moment de la mise à jour et de savoir exactement ce qui tourne.

Sauvegarder et restaurer

Une sauvegarde de Portainer contient sa base de données et les fichiers des stacks déployées depuis Portainer. Elle ne contient ni vos conteneurs, ni vos images, ni les données de leurs volumes : sauvegardez-les séparément, comme expliqué dans le guide Docker.

Depuis l'interface

  1. Ouvrez Settings, puis descendez jusqu'à Back up Portainer.
  2. Activez Password protect et saisissez un mot de passe.
  3. Cliquez sur Download backup.

Dans l'édition CE, cette sauvegarde se lance à la main. Les sauvegardes planifiées et l'envoi vers S3 sont réservés à l'édition Business.

Depuis le serveur

Cette méthode peut être planifiée. Elle arrête Portainer quelques instants, sans toucher à vos autres conteneurs :

Terminal
cd /opt/portainer
mkdir -p backups
docker compose stop portainer
docker run --rm -v portainer_data:/data:ro -v "$PWD/backups":/backup alpine:3 tar czf "/backup/portainer-$(date +%F).tar.gz" -C /data .
docker compose start portainer
sudo chmod 600 backups/*.tar.gz

L'archive contient des identifiants et des clés d'API. Copiez-la, ainsi que compose.yaml, hors du serveur dans un emplacement chiffré.

Restaurer l'archive du serveur

Remplacez AAAA-MM-JJ par la date de l'archive. Le contenu actuel du volume est supprimé :

Terminal
cd /opt/portainer
docker compose down
docker run --rm -v portainer_data:/data -v "$PWD/backups":/backup:ro alpine:3 sh -c 'find /data -mindepth 1 -delete && tar xzf /backup/portainer-AAAA-MM-JJ.tar.gz -C /data'
docker compose up -d

Utilisez la même version de Portainer que lors de la sauvegarde, ou une version plus récente.

Restaurer un fichier téléchargé

Cette restauration n'est possible que sur une instance neuve, avec un volume vide. Sur l'écran d'initialisation, ouvrez Restore Portainer from backup, choisissez le fichier, saisissez son mot de passe et le jeton setup_token, puis cliquez sur Restore Portainer.

En cas de problème

the Portainer instance timed out for security purposes

Le premier administrateur n'a pas été créé dans les 5 minutes. Redémarrez le conteneur, puis récupérez le nouveau jeton :

Terminal
cd /opt/portainer
docker compose restart portainer
docker logs portainer 2>&1 | grep setup_token | tail -n 1

Si ce message apparaît sur une instance déjà configurée, vérifiez que le volume portainer_data est bien monté : sans ses données, Portainer se comporte comme une nouvelle installation.

Le jeton d'installation est refusé

Le jeton change à chaque démarrage. Utilisez la dernière valeur affichée par la commande précédente et copiez-la sans espace.

open failed: connect failed: Connection refused

Ce message s'affiche dans le terminal du tunnel. Le tunnel fonctionne, mais rien n'écoute sur le port visé du serveur. Vérifiez l'état du conteneur avec docker compose ps et ses journaux avec docker compose logs --tail=50 portainer.

bind [127.0.0.1]:9443: Address already in use

Le port est déjà occupé sur votre poste, souvent par un ancien tunnel. Fermez-le ou choisissez un autre port local, comme à l'étape 2.

Client sent an HTTP request to an HTTPS server

Vous utilisez http:// sur le port 9443. Ouvrez https://localhost:9443.

Le port 9443 répond depuis Internet

Le port a probablement été publié sans adresse locale. Contrôlez la sortie de docker ps : si elle contient 0.0.0.0:9443, corrigez compose.yaml et relancez docker compose up -d.

403 Forbidden et CSRF check failed derrière un reverse proxy

Le proxy modifie sans doute le nom d'hôte reçu par Portainer. Avec le bloc Caddy de ce guide, le nom d'origine est conservé. Si vous avez un autre proxy devant, déclarez l'adresse publique avec une URL complète :

YAML
    command: --trusted-origins https://portainer.votre-domaine.com

Un nom sans https:// provoque l'erreur invalid url for trusted origin au démarrage.

Erreur 502 avec Caddy

Caddy ne joint pas le port 9000. Vérifiez qu'il est publié avec docker ps, puis testez curl -I http://127.0.0.1:9000. Si Force HTTPS only est actif, désactivez-le depuis le tunnel SSH.

Mot de passe administrateur perdu

Un autre administrateur peut le réinitialiser. Sinon, utilisez l'outil officiel, qui affiche un nouveau mot de passe :

Terminal
cd /opt/portainer
docker compose stop portainer
docker pull portainer/helper-reset-password
docker run --rm -v portainer_data:/data portainer/helper-reset-password
docker compose start portainer

Références