Hardware Setups Overview

Portoser is built for clusters in the 2–20 machine range. This page sketches the six shapes that come up most often. Each links to a dedicated walkthrough.

Solo Laptop or Mac mini

  • 1 machine, macOS or Linux, 8–32 GB RAM
  • Best for: side projects, learning the tool, the demo
  • Run via docker compose up from the repo root
  • All three deployment types (docker, local, native) work on a single host

→ Solo Laptop walkthrough

Raspberry Pi Home Lab

  • 3–6 Pis, arm64 Linux, often Pi 4 / Pi 5
  • Optional: one x86 box for image builds (buildx host)
  • Best for: home automation, self-hosted tools, learning multi-host
  • Pin services to specific Pis by role (e.g. pi-1 runs DNS + Caddy; pi-2 runs the database; pi-3..6 run app services)

→ Raspberry Pi Cluster walkthrough

Mac mini Lab

  • 2–4 Mac minis, mixed M-series, sometimes one Intel
  • Best for: small studios, ML inference + APIs, anyone who already invested in Apple Silicon
  • native deployment type via launchctl works first-class on macOS
  • Bash 5.x is required (Homebrew); Apple's Bash 3.2 is too old

→ Mac mini Lab walkthrough

Mixed-Architecture Cluster

  • Mac minis + Raspberry Pis + maybe one x86 box
  • Cross-arch (arm64 + amd64), cross-OS (macOS + Linux)
  • The same registry.yml describes all of them
  • lib/cluster/buildx.sh builds the right image variant for each target machine

→ Mixed Architecture walkthrough

GPU + CPU Split

  • One GPU host (often a desktop with NVIDIA or Apple Silicon GPU) for inference / training
  • A handful of CPU hosts for APIs, queues, databases
  • The GPU host is just another machine in registry.yml; services declare current_host: gpu-host

→ GPU + CPU Split walkthrough

Home + VPS Hybrid

  • Local cluster for development and private services
  • A remote VPS for the public-facing surface (often behind Cloudflare Tunnel or WireGuard / Tailscale mesh)
  • mTLS between local and VPS using Portoser's built-in CA
  • One registry, two networks

→ VPS + Home Hybrid walkthrough

Sizing guidance

Cluster size RAM per host Notes
1 host 8 GB minimum Plenty for the demo and 5–10 small services
3–6 hosts 4 GB on Pis, 8 GB+ on x86/Mac Caddy + DNS on one, database on another, apps on the rest
7–15 hosts 8 GB+ on hosts running stateful services Consider one host as the dedicated "control plane" running Vault, Caddy, and the Portoser web UI
15–20 hosts Same as above This is the upper end Portoser is built for; beyond ~20 hosts, a real scheduler is probably the right call

What's the same across every setup

  • One registry.yml is the source of truth
  • SSH key auth, no agents installed on workers
  • Self-healing loop on every deploy
  • Web UI, CLI, and (preview) MCP server all work identically
  • mTLS between services if you opt in