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.
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
:rodu 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
rootsur 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 :
sudo mkdir -p /opt/portainer
sudo chown "$USER": /opt/portainer
cd /opt/portainer
nano compose.yamlCollez cette configuration :
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_dataLe port 8000 n'est pas publié, car il ne sert qu'aux Edge Agents. Validez le fichier et téléchargez l'image :
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 :
ssh -N -L 9443:127.0.0.1:9443 VOTRE_USER@VOTRE_IP_SERVEURLa 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 :
cd /opt/portainer
docker compose up -d
docker compose ps
docker logs portainer 2>&1 | grep setup_token | tail -n 1La 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
- Ouvrez
https://localhost:9443dans votre navigateur. - Acceptez l'avertissement de sécurité : Portainer utilise par défaut un certificat auto-signé. Le trafic passe dans le tunnel SSH.
- Choisissez un nom d'utilisateur et un mot de passe unique d'au moins 12 caractères.
- Collez la valeur du jeton dans le champ Setup token, puis validez.
- Sur l'écran Edge Compute, choisissez Skip si vous ne gérez pas d'Edge Agents.
- 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 :
docker ps --filter name=portainer --format '{{.Names}} {{.Ports}}'
curl -kI https://127.0.0.1:9443La 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 :
nmap -Pn -p 8000,9000,9443 VOTRE_IP_SERVEURAucun 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 :
ports:
- "127.0.0.1:9443:9443"
- "127.0.0.1:9000:9000"Appliquez la modification :
cd /opt/portainer
docker compose up -dAjoutez ensuite ce site dans /etc/caddy/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 :
sudo ufw allow 80,443/tcp comment 'Caddy'
sudo -u caddy caddy validate --config /etc/caddy/Caddyfile --adapter caddyfile
sudo systemctl reload caddyOuvrez 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 :
cd /opt/portainer
nano compose.yaml
docker compose pull
docker compose up -d
docker compose imagesVos 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
- Ouvrez Settings, puis descendez jusqu'à Back up Portainer.
- Activez Password protect et saisissez un mot de passe.
- 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 :
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.gzL'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é :
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 -dUtilisez 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 :
cd /opt/portainer
docker compose restart portainer
docker logs portainer 2>&1 | grep setup_token | tail -n 1Si 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 :
command: --trusted-origins https://portainer.votre-domaine.comUn 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 :
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