Gestionnaire de ports pour vos applications Docker.

Portier est un CLI qui résout un problème simple mais fréquent : garder une trace des ports utilisés par vos applications Docker sur un VPS.

• Le problème
• Prérequis
• Installation
• Premier lancement
• Utilisation quotidienne
• Référence des commandes
• Configuration
• Catégories
• Workflows
• Intégrations
• Mise à jour
• Désinstallation
• Alternatives

Vous avez plusieurs applications Docker sur votre serveur. Chacune expose un port :

# App 1
ports:
  - "3001:3000"

# App 2
ports:
  - "3002:3000"

# App 3
ports:
  - "???:3000"  # Lequel est libre déjà ?

À chaque nouvelle application, vous devez :

1. Vous souvenir des ports déjà utilisés
2. Vérifier manuellement tous vos docker-compose.yml
3. Vérifier vos configurations Nginx
4. Espérer ne pas avoir de conflit

Portier élimine ce problème en maintenant un registre central de tous vos ports.

• Python 3.8 ou supérieur
• Docker (pour les fonctionnalités de scan et sync)

pipx installe les CLI Python dans des environnements isolés. C'est la méthode recommandée sur Ubuntu 23.04+, Debian 12+ et les systèmes récents.

# Installer pipx
sudo apt update
sudo apt install pipx -y

# Installer portier
pipx install portier-cli

Si vous voyez ce message après l'installation :

⚠️  Note: '/home/user/.local/bin' is not on your PATH environment variable.

Exécutez ces commandes :

# Ajouter le dossier au PATH
pipx ensurepath

# Recharger le terminal
source ~/.bashrc

Si ça ne fonctionne toujours pas, ajoutez manuellement le PATH :

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Sur Ubuntu 22.04 et versions antérieures :

sudo apt update
sudo apt install python3-pip -y
pip install portier-cli

Sur les systèmes récents (Ubuntu 23.04+, Debian 12+), vous pouvez voir cette erreur :

error: externally-managed-environment

Dans ce cas, utilisez la Méthode 1 (pipx) ou la Méthode 3 (environnement virtuel).

Ajoutez le dossier des binaires pip à votre PATH :

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Si vous préférez utiliser un environnement virtuel :

# Créer l'environnement
python3 -m venv ~/portier-env

# Installer portier
~/portier-env/bin/pip install portier-cli

# Ajouter un alias pour la commande
echo 'alias portier="~/portier-env/bin/portier"' >> ~/.bashrc
source ~/.bashrc

# Afficher la version
portier --version

# Afficher l'aide
portier --help

Vous devriez voir :

Usage: portier [OPTIONS] COMMAND [ARGS]...

  Portier - Gestionnaire de ports pour vos applications Docker

Options:
  --version  Show the version and exit.
  --help     Show this message and exit.

Commands:
  add         Attribue un port à une nouvelle app
  categories  Liste les catégories configurées
  check       Vérifie si un port est disponible
  config      Gère la configuration de portier
  init        Initialise portier
  list        Liste toutes les apps et leurs ports
  remove      Supprime une app et libère son port
  scan        Scanne les conteneurs Docker existants
  sync        Synchronise le registre avec Docker

Vous avez probablement déjà des conteneurs Docker qui tournent. Voici comment intégrer portier à votre setup existant.

portier init

✓ Portier initialisé
  Plage par défaut : 3000-3999
  Config : ~/.portier/config.yaml
  Registre : ~/.portier/registry.json

Regardez d'abord ce que portier détecte :

portier scan

┌─────────────────────────┬───────────┬─────────────────┐
│ Conteneur               │ Port hôte │ Port conteneur  │
├─────────────────────────┼───────────┼─────────────────┤
│ mon-api                 │ 3001      │ 3000/tcp        │
│ mon-frontend            │ 3002      │ 3000/tcp        │
│ postgres                │ 5432      │ 5432/tcp        │
└─────────────────────────┴───────────┴─────────────────┘

Synchronisez pour importer vos conteneurs existants :

portier sync

Synchronisation...

⚠ Conteneur 'mon-api' sur port 3001 (non enregistré)
  Ajouter au registre ? [O/n] O
  ✓ "mon-api" ajouté (port 3001)

⚠ Conteneur 'mon-frontend' sur port 3002 (non enregistré)
  Ajouter au registre ? [O/n] O
  ✓ "mon-frontend" ajouté (port 3002)

⚠ Conteneur 'postgres' sur port 5432 (non enregistré)
  Ajouter au registre ? [O/n] O
  ✓ "postgres" ajouté (port 5432)

Synchronisation terminée.

portier list

┌──────────────┬──────┬───────────┬────────┐
│ App          │ Port │ Catégorie │ Actif  │
├──────────────┼──────┼───────────┼────────┤
│ mon-api      │ 3001 │ -         │ ✓      │
│ mon-frontend │ 3002 │ -         │ ✓      │
│ postgres     │ 5432 │ -         │ ✓      │
└──────────────┴──────┴───────────┴────────┘

3 apps · Ports : 3001, 3002, 5432

Portier connaît maintenant tout votre environnement. À partir de maintenant, utilisez-le pour gérer vos ports.

Pour mieux structurer vos ports, créez des catégories :

portier config add-category frontend --range=3000-3099 --description="Applications frontend"
portier config add-category backend --range=3100-3199 --description="APIs backend"
portier config add-category database --range=5400-5499 --description="Bases de données"

Vérifiez vos catégories :

portier categories

┌──────────┬─────────────┬──────────────────────────┐
│ Nom      │ Plage       │ Description              │
├──────────┼─────────────┼──────────────────────────┤
│ frontend │ 3000-3099   │ Applications frontend    │
│ backend  │ 3100-3199   │ APIs backend             │
│ database │ 5400-5499   │ Bases de données         │
└──────────┴─────────────┴──────────────────────────┘

portier add mon-nouveau-projet

✓ Port 3003 attribué à "mon-nouveau-projet"

  Utilise dans ton docker-compose.yml :
  ports:
    - "3003:3000"

Avec une catégorie :

portier add mon-api-v2 --category=backend

✓ Port 3100 attribué à "mon-api-v2"
  Catégorie : backend

  Utilise dans ton docker-compose.yml :
  ports:
    - "3100:3000"

portier check 3005

✓ Port 3005 est disponible

portier check 3001

✗ Port 3001 est utilisé par "mon-api"

portier list

Quand vous supprimez un conteneur, libérez aussi son port :

docker compose down
portier remove mon-ancien-projet

✓ Port 3003 libéré (app "mon-ancien-projet" supprimée)

Si vous avez créé ou supprimé des conteneurs sans passer par portier :

portier sync

Portier détectera les différences et vous proposera de mettre à jour le registre.

Initialise portier. Crée le dossier ~/.portier/ avec les fichiers de configuration.

portier init

À exécuter une seule fois lors de la première utilisation.

Attribue un port à une nouvelle application.

# Attribution automatique
portier add mon-api

# Avec une catégorie
portier add mon-site --category=frontend

# Avec un port spécifique
portier add mon-service --port=4000

Options :

Affiche toutes les applications enregistrées et leurs ports.

# Toutes les apps
portier list

# Filtrer par catégorie
portier list --category=frontend

La colonne "Actif" indique si un conteneur Docker utilise actuellement ce port.

Vérifie si un port est disponible.

portier check 3500

Retourne :

• ✓ si le port est disponible
• ✗ si le port est utilisé par une app enregistrée
• ⚠ si le port est utilisé par Docker mais non enregistré

Supprime une application du registre et libère son port.

portier remove mon-api

Affiche tous les conteneurs Docker en cours d'exécution avec leurs ports exposés.

portier scan

Utile pour voir l'état actuel avant d'importer dans portier.

Synchronise le registre avec l'état réel de Docker.

portier sync

Cette commande :

1. Détecte les apps dans le registre dont le conteneur n'existe plus
2. Détecte les conteneurs Docker non enregistrés
3. Propose de nettoyer/ajouter les entrées

Affiche toutes les catégories configurées.

portier categories

Crée une nouvelle catégorie avec sa plage de ports.

portier config add-category frontend --range=3000-3099 --description="Applications frontend"

Options :

Supprime une catégorie.

portier config remove-category staging

Modifie la plage de ports par défaut.

portier config set-range --start=4000 --end=4999

✓ Plage de ports mise à jour : 4000-4999

Options :

Cette plage est utilisée quand vous ajoutez une app sans catégorie.

Par défaut, portier attribue les ports dans la plage 3000-3999. Vous pouvez modifier cette plage.

portier config set-range --start=4000 --end=4999

nano ~/.portier/config.yaml

range:
  start: 4000
  end: 4999

Portier stocke ses données dans ~/.portier/ :

Configuration générale et catégories.

range:
  start: 3000
  end: 3999
categories:
  frontend:
    range:
      - 3000
      - 3099
    description: Applications frontend
  backend:
    range:
      - 3100
      - 3199
    description: APIs backend
default_category: null

Registre des applications et leurs ports.

{
  "apps": {
    "mon-api": {
      "port": 3100,
      "category": "backend",
      "created_at": "2025-01-30T10:30:00.000000"
    },
    "mon-site": {
      "port": 3000,
      "category": "frontend",
      "created_at": "2025-01-30T10:35:00.000000"
    }
  }
}

Les catégories permettent d'organiser vos ports par type d'application. Chaque catégorie a sa propre plage de ports.

portier config add-category frontend --range=3000-3099 --description="Applications frontend"
portier config add-category backend --range=3100-3199 --description="APIs et services backend"
portier config add-category staging --range=3200-3299 --description="Environnements de staging"
portier config add-category production --range=3300-3399 --description="Environnements de production"

• Organisation claire de vos services
• Plages de ports prévisibles
• Facilite la configuration des firewalls
• Documentation implicite de votre infrastructure

# 1. Demander un port
portier add mon-nouveau-projet --category=backend
# ✓ Port 3100 attribué à "mon-nouveau-projet" (catégorie: backend)

# 2. Créer le docker-compose.yml avec ce port
# ports:
#   - "3100:3000"

# 3. Configurer Nginx
# proxy_pass http://127.0.0.1:3100;

# 4. Démarrer l'application
docker compose up -d

# 1. Arrêter et supprimer le conteneur
docker compose down

# 2. Libérer le port dans portier
portier remove mon-projet
# ✓ Port 3100 libéré

Portier ne modifie pas vos fichiers. Il vous indique simplement quel port utiliser.

Avant :

services:
  mon-app:
    image: mon-app:latest
    ports:
      - "???:3000" # Quel port choisir ?

Avec portier :

portier add mon-app
# ✓ Port 3001 attribué à "mon-app"

services:
  mon-app:
    image: mon-app:latest
    ports:
      - "3001:3000" # Port donné par portier

Exemple de configuration Nginx utilisant le port attribué par portier :

portier add mon-api --category=backend
# ✓ Port 3100 attribué

server {
    server_name api.monsite.com;

    location / {
        proxy_pass http://127.0.0.1:3100;
        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;
    }

    listen 443 ssl;
    ssl_certificate /etc/letsencrypt/live/api.monsite.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/api.monsite.com/privkey.pem;
}

pipx upgrade portier-cli

pip install --upgrade portier-cli

~/portier-env/bin/pip install --upgrade portier-cli

portier --version

pipx uninstall portier-cli

pip uninstall portier-cli

rm -rf ~/.portier

Portier est conçu pour ceux qui utilisent Docker avec une gestion manuelle des ports et Nginx. Si vous cherchez une solution plus automatisée, considérez :

• Traefik : Reverse proxy qui découvre automatiquement les conteneurs Docker et élimine le besoin de gérer les ports
• Kubernetes : Orchestration complète avec service discovery
• Docker Swarm : Orchestration Docker native

Portier reste utile si vous préférez garder le contrôle manuel ou si vous ne souhaitez pas migrer vers ces solutions.

MIT

Les contributions sont les bienvenues ! N'hésitez pas à ouvrir une issue ou une pull request sur GitHub.

Développé par Franck AÏGBA