Portler

Portler is a local development process runner like a small docker compose, but with automatic port assignment.

It reads portler.yml, assigns free localhost ports, resolves service references like backend.url, and starts each service with the right environment variables.

📖 Full documentation: yjjosh.github.io/Portler

Install

npm install -g portler
portler --help

Requires Node.js >=22.6. Docker only if you use Docker services; kubectl and a local cluster (kind, minikube, or Docker Desktop Kubernetes) only for Kubernetes mode.

Quick example

# portler.yml
services:
  postgres:
    image: postgres:16-alpine
    port: 5432
    env:
      POSTGRES_USER: app
      POSTGRES_PASSWORD: app
      POSTGRES_DB: app

  backend:
    command: npm run dev
    cwd: backend
    port: 4000
    port_env: PORT
    depends_on:
      - postgres
    env:
      DATABASE_URL: postgres://app:app@localhost:${postgres.port}/app

  frontend:
    command: npm run dev
    cwd: frontend
    port: 3000
    port_env: PORT
    env:
      VITE_API_URL: backend.url

$ portler up
SERVICE    PORT    URL
postgres   51234   http://localhost:51234
backend    51235   http://localhost:51235
frontend   51236   http://localhost:51236

Every service gets a free port (so any number of projects and git worktrees run side by side), backend.url resolves to the backend's real address, and services start in dependency order once their healthchecks pass.

Highlights

• Automatic port assignment — sticky, collision-free ports from a global registry
• Service references — backend.url, ${postgres.port} in env values
• Docker services and a full Docker mode
• Kubernetes mode — the same stack in a local cluster, port-forwarded back
• Managed volumes — fork database data per branch/worktree
• Reverse proxy — one project URL, no CORS pain
• Full CLI and portler.yml reference

Local development

npm install
npm link
portler --help

Or run without linking:

npm run dev -- --help
node ./bin/portler.ts --help

Docs live in docs/ (VitePress): npm run docs:dev serves them locally, npm run docs:build builds the site.

Project structure

The code is organized by concern. Each folder owns one part of the pipeline and most expose an index.ts barrel:

bin/
  portler.ts          CLI entry point (calls src/cli)
src/
  constants.ts        Version and shared defaults
  cli/                Argument parsing, help, output, and command dispatch
    args.ts           Flag parsing
    help.ts           --help text
    table.ts          SERVICE/PORT/URL table rendering
    sample.ts         Canonical starter portler.yml (init + help)
    services.ts       Service selection / dependency ordering
    commands/         One file per command: up, down, restart, ps, logs, ports, env, clean, volumes, init
  config/             Loading and normalizing portler.yml
    loader.ts         Top-level loadConfig + .env loading
    scalars.ts        Small value validators/normalizers
    naming.ts         Default Docker image/container/network/volume names
    docker.ts         Docker service normalization
    k8s.ts            Kubernetes mode normalization
    healthcheck.ts    Healthcheck normalization
    dependencies.ts   depends_on normalization
    volumes.ts        Managed volume declarations, volume sets, volume root
  env/                Environment resolution and generation
    resolve.ts        Service-reference resolution (backend.url, ${x.port})
    generate.ts       PORTLER_* generated values
    service.ts        Per-service and printable env building
  ports/              Free-port allocation
    probe.ts          TCP port availability check
    lock.ts           Global registry lock
    registry.ts       ~/.portler/ports.json read/write/prune
    allocate.ts       Assignment + release logic
    locations.ts      Global paths
  process/            Spawning and stopping services
    spawn.ts          Process spawning
    stop.ts           Signalling and Docker cleanup
    pids.ts           .portler/pids.json tracking
    docker.ts         Docker run/build command building
    logs.ts           Prefixed log streaming and .portler/logs/ paths
  proxy/              Reverse proxy for the top-level proxy block
    server.ts         HTTP forwarding, route matching, WebSocket upgrades
    daemon.ts         Standalone proxy process entry point
    spawn.ts          Proxy process spawning and pids.json record
  volumes/            Volume manager (list/fork/remove via the docker CLI)
  k8s/                Kubernetes mode (up k8s / down k8s / k8s render)
    manifests.ts      Deployment/Service/PVC/Namespace objects
    render.ts         .portler/k8s/ manifest file generation
    cluster.ts        Cluster detection + local image loading
    kubectl.ts        apply, rollout wait, port-forward, delete
    build.ts          Docker image builds for k8s mode
    exec.ts           Child-process helpers
  readiness/          Healthcheck polling (tcp/http/command)
  state/              .portler/state.json and runtime.env
  parse/              Hand-rolled YAML (practical subset) parser, dotenv parser, and YAML writer
  types/              Shared TypeScript types (common, config, runtime)
  util/               sleep, json-file, hash, suggestion helpers

License

MIT