portier-cli 0.1.2

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.

---

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
pipx ensurepath
source ~/.bashrc

# Installer portier
pipx install portier-cli

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

Méthode 3 : Dans un environnement virtuel

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

python3 -m venv ~/portier-env
~/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

portier --help

La commande portier n'est pas trouvée ?

Ajoute le dossier des binaires à ton PATH :

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

---

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

---

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é

---

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

---

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