portier-cli 0.1.3

Gestionnaire de ports pour vos applications Docker

Portier 🔌

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.

---

Table des matières

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

---

Le problème

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.

---

Prérequis

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

---

Installation

Méthode 1 : Avec pipx (recommandé)

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

Problème : portier: command not found après l'installation ?

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

---

Méthode 2 : Avec pip (systèmes plus anciens)

Sur Ubuntu 22.04 et versions antérieures :

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

Problème : externally-managed-environment ?

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).

Problème : portier: command not found ?

Ajoutez le dossier des binaires pip à votre PATH :

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

---

Méthode 3 : Dans un environnement virtuel

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

---

Vérifier l'installation

# 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

---

Premier lancement : intégrer votre environnement existant

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

Étape 1 : Initialiser portier

portier init

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

Étape 2 : Scanner vos conteneurs existants

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        │
└─────────────────────────┴───────────┴─────────────────┘

Étape 3 : Importer dans le registre

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.

Étape 4 : Vérifier le registre

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.

Étape 5 (optionnel) : Organiser avec des catégories

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         │
└──────────┴─────────────┴──────────────────────────┘

---

Utilisation quotidienne

Ajouter une nouvelle application

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"

Vérifier si un port est disponible

portier check 3005

✓ Port 3005 est disponible

portier check 3001

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

Voir tous vos ports

portier list

Supprimer une application

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)

Resynchroniser après des changements manuels

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.

---

Référence des commandes

portier init

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.

---

portier add <app>

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 :

Option	Description
--category, -c	Catégorie de l'app (utilise la plage définie)
--port, -p	Port spécifique à attribuer

---

portier list

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.

---

portier check <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é

---

portier remove <app>

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

portier remove mon-api

---

portier scan

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.

---

portier sync

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

---

portier categories

Affiche toutes les catégories configurées.

portier categories

---

portier config add-category

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

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

Options :

Option	Description
--range	Plage de ports (obligatoire, format : start-end)
--description, -d	Description de la catégorie (optionnel)

---

portier config remove-category

Supprime une catégorie.

portier config remove-category staging

---

portier config set-range

Modifie la plage de ports par défaut.

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

✓ Plage de ports mise à jour : 4000-4999

Options :

Option	Description
--start	Port de début de la plage (obligatoire)
--end	Port de fin de la plage (obligatoire)

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

---

Configuration

Configuration de la plage par défaut

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

Via la commande CLI

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

En modifiant le fichier de configuration

nano ~/.portier/config.yaml

range:
  start: 4000
  end: 4999

Fichiers de configuration

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

~/.portier/config.yaml

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

~/.portier/registry.json

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"
    }
  }
}

---

Catégories

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

Exemple de configuration

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"

Avantages

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

---

Workflow complet : nouvelle application

# 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

---

Workflow complet : supprimer une application

# 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é

---

Intégration avec Docker Compose

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

---

Intégration avec Nginx

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;
}

---

Désinstallation

Si installé avec pipx

pipx uninstall portier-cli

Si installé avec pip

pip uninstall portier-cli

Supprimer les fichiers de configuration

rm -rf ~/.portier

---

Alternatives

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.

---

Licence

MIT

---

Contribuer

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

---

Auteur

Développé par Franck AÏGBA