portier-cli 0.1.4
Gestionnaire de ports pour vos applications Docker
Requires Python: >=3.8
Keywords: docker, ports, cli, devops, containers

# 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](#le-problème)
- [Prérequis](#prérequis)
- [Installation](#installation)
- [Premier lancement](#premier-lancement--intégrer-votre-environnement-existant)
- [Utilisation quotidienne](#utilisation-quotidienne)
- [Référence des commandes](#référence-des-commandes)
- [Configuration](#configuration)
- [Catégories](#catégories)
- [Workflows](#workflow-complet--nouvelle-application)
- [Intégrations](#intégration-avec-docker-compose)
- [Mise à jour](#mise-à-jour)
- [Désinstallation](#désinstallation)
- [Alternatives](#alternatives)

---

## Le problème

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

```yaml
# 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.

```bash
# 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 :

```bash
# Ajouter le dossier au PATH
pipx ensurepath

# Recharger le terminal
source ~/.bashrc
```

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

```bash
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 :

```bash
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 :

```bash
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 :

```bash
# 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

```bash
# 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

```bash
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 :

```bash
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 :

```bash
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

```bash
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 :

```bash
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 :

```bash
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

```bash
portier add mon-nouveau-projet
```

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

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

Avec une catégorie :

```bash
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

```bash
portier check 3005
```

```
✓ Port 3005 est disponible
```

```bash
portier check 3001
```

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

### Voir tous vos ports

```bash
portier list
```

### Supprimer une application

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

```bash
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 :

```bash
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.

```bash
portier init
```

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

---

### `portier add <app>`

Attribue un port à une nouvelle application.

```bash
# 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.

```bash
# 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.

```bash
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.

```bash
portier remove mon-api
```

---

### `portier scan`

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

```bash
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.

```bash
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.

```bash
portier categories
```

---

### `portier config add-category`

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

```bash
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.

```bash
portier config remove-category staging
```

---

### `portier config set-range`

Modifie la plage de ports par défaut.

```bash
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

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

#### En modifiant le fichier de configuration

```bash
nano ~/.portier/config.yaml
```

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

```yaml
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.

```json
{
  "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

```bash
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

```bash
# 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

```bash
# 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 :**

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

**Avec portier :**

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

```yaml
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 :

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

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

---

## Mise à jour

### Si installé avec pipx

```bash
pipx upgrade portier-cli
```

### Si installé avec pip

```bash
pip install --upgrade portier-cli
```

### Si installé dans un environnement virtuel

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

### Vérifier la version après mise à jour

```bash
portier --version
```

---

## Désinstallation

### Si installé avec pipx

```bash
pipx uninstall portier-cli
```

### Si installé avec pip

```bash
pip uninstall portier-cli
```

### Supprimer les fichiers de configuration

```bash
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](https://github.com/Landers9)