# portman — Port Manager for containerised development

**Engineered by Codermasky**

A global port registry and conflict-free port assignment system for all your Docker Compose projects on macOS, Linux, and Windows.

---

## Quick Start

```bash
bash ~/Sandbox/portman/install.sh
source ~/.zshrc
portman new myproject
portman list
```

---

## Files

- **`portman.py`** — Main CLI tool (Python 3.7+)
- **`install.sh`** — One-time installation script
- **`GUIDE.md`** — Complete user guide with examples and troubleshooting

---

## What It Does

**Problem:** Running 15+ projects in `~/Sandbox`, each with docker-compose, and manually tracking which ports are in use? Constant conflicts.

**Solution:** `portman` auto-assigns ports from predefined ranges and prevents collisions:

```bash
portman new myapp        # Auto-assigns: frontend:3000, backend:8000, postgres:5432, redis:6379, langfuse:3200
portman list             # View all assigned ports across all projects
portman check            # Detect conflicts (should never happen)
portman scan             # See what's actually listening on your Mac/Linux/WSL2
portman export myapp     # Copy-paste docker-compose ports snippet
```

---

## Installation

```bash
cd ~/Sandbox/portman
bash install.sh
source ~/.zshrc    # or ~/.bashrc, ~/.bash_profile, etc.
```

Then:
```bash
portman --help
portman new myproject
```

---

## Port Ranges

| Service | Range | Purpose |
|---|---|---|
| frontend | 3000–3099 | React, Vue, Next.js, Vite |
| backend | 8000–8099 | FastAPI, Node.js, Flask, Django |
| postgres | 5432–5532 | PostgreSQL databases |
| redis | 6379–6479 | Redis cache |
| langfuse | 3200–3299 | Langfuse observability |
| clickhouse | 8123–8222 | ClickHouse analytics |
| minio | 9000–9099 | MinIO object storage |
| grafana | 3300–3399 | Grafana dashboards |

---

## Full Documentation

Read the complete guide:

```bash
cat ~/Sandbox/portman/GUIDE.md
```

Or open in your editor:

```bash
code ~/Sandbox/portman/GUIDE.md
```

---

## Registry Location

All port assignments are stored in:

```
~/.portman/registry.json
```

This is a global file shared across all projects, persists across terminal sessions, and is auto-created on first run.

---

## Cross-Platform Support

- **macOS** — ✅ Full support (uses `lsof`)
- **Linux** — ✅ Full support (uses `lsof`)
- **Windows (WSL2)** — ✅ Full support
- **Windows (native)** — ⚠️ Basic support (uses `netstat`)

Recommended: Use **WSL2** on Windows for the best experience.

---

## Common Commands

```bash
portman list               # Show all ports
portman new myapp          # Create new app with standard services
portman assign svc --app myapp    # Add a service
portman release svc --app myapp   # Remove a service
portman check              # Detect conflicts
portman scan               # See what's listening
portman export myapp       # Get docker-compose snippet
portman rm myapp           # Delete entire app
portman dashboard          # Open visual dashboard in browser
```

---

## Getting Help

```bash
portman --help             # Show all commands
portman list --help        # Help for specific command
cat ~/Sandbox/portman/GUIDE.md   # Full guide
```

---

## Why portman?

✅ **No more port conflicts** — Auto-assign + enforcement
✅ **Works across all projects** — Global registry at `~/.portman/`
✅ **Copy-paste ready** — `portman export myapp` → docker-compose snippet
✅ **Cross-platform** — macOS, Linux, WSL2, Windows
✅ **Zero config** — Just `portman new myapp` and go
✅ **Live scanning** — `portman scan` shows what's actually listening

---

**Engineered with ❤️ by Codermasky**
