Install

Three install paths

The single-machine demo runs in about 5 minutes. A full multi-host setup is roughly 30 minutes once SSH keys are in place. The from-source dev setup takes longest.

Path 1 — Single-machine demo

~5 minutes

Best for evaluating Portoser. Brings up Caddy, a small FastAPI dashboard, and one nginx-backed dummy service. No Postgres, Vault, or Keycloak.

Requires

  • Docker + Docker Compose
  • Bash 4.0+
  • 8 GB RAM

Steps

git clone https://github.com/nonagenticai/portoser.git
cd portoser
cp .env.example .env
docker compose up
# Open http://localhost:8080

Path 2 — Multi-host cluster

~30 minutes

For when you want to drive a real 2–20 host cluster. The CLI runs from one machine and SSHes to the rest.

Requires

  • A registry.yml describing your hosts and services
  • SSH key auth to every host
  • yq, jq, ssh, scp, curl on the host running the CLI
  • Bash 5+ (Apple ships 3.2 — brew install bash)

Steps

# On the CLI host
git clone https://github.com/nonagenticai/portoser.git
cd portoser
cp registry.example.yml registry.yml
# Edit registry.yml: replace IPs, ssh_user, paths
cp .env.example .env
export CADDY_REGISTRY_PATH=$(pwd)/registry.yml

# Validate, then deploy infrastructure first
./portoser registry validate
./portoser deploy mini1 dnsmasq caddy
./portoser deploy mini1 vault

# Then your services
./portoser cluster deploy --all
./portoser cluster health --watch

Path 3 — From source (development)

~1 hour

For contributors and people who want the full stack: web UI backend + frontend + MCP server. Runs the production web/docker-compose.yml against your local code.

Requires

  • Path 2 prerequisites
  • Postgres 16
  • Node 20+ for the frontend dev server (optional)

Steps

git clone https://github.com/nonagenticai/portoser.git
cd portoser

# Backend + frontend (full stack)
cd web && docker compose up -d
# Frontend on http://localhost:8989
# Backend  on http://localhost:8988

# Run tests
./tests/run_tests.sh

# Live frontend dev (optional)
cd web/frontend && npm install && npm run dev

Verify it works

./portoser registry validate

Prints "Registry is valid" or surfaces the specific field error.

./portoser health check-all

JSON-shaped per-service health summary.

./portoser caddy validate

Caddyfile syntax check (uses caddy validate under the hood).

curl http://localhost:8988/api/services

(Path 3 only) JSON list of services from the running backend.

Common dependency gotchas

  • Apple Bash 3.2. The CLI requires Bash 4+. Run brew install bash on every macOS host.
  • yq flavor. Portoser uses Mike Farah's Go-based yq (v4), not the Python yq. brew install yq gives the right one on macOS; snap install yq on Linux.
  • Docker Desktop on Apple Silicon. Allocate at least 4 GB to the VM if you plan to run the full Path 3 stack with Postgres.
  • Port 8080 free. The demo Caddy binds :8080. Override with PORTOSER_DEMO_PORT=8090 docker compose up.
Read the Quickstart Pick a hardware shape