Metadata-Version: 2.4
Name: portier-cli
Version: 0.1.2
Summary: Gestionnaire de ports pour vos applications Docker
Home-page: https://github.com/Landers9/portier
Author: Franck AÏGBA
Author-email: franckaigba4@gmail.com
Project-URL: Bug Tracker, https://github.com/Landers9/portier/issues
Project-URL: Documentation, https://github.com/Landers9/portier#readme
Project-URL: Source, https://github.com/Landers9/portier
Keywords: docker,ports,cli,devops,containers
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: click>=8.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: docker>=6.0.0
Requires-Dist: rich>=13.0.0
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: project-url
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

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

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

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

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

```bash
portier --help
```

### La commande `portier` n'est pas trouvée ?

Ajoute le dossier des binaires à ton PATH :

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

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

---

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

---

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

---

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

---

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