Getting started

This guide starts ermahgerd’s self-hostable, multi-tenant PaaS in its local development form. It deploys the bundled applications, creates the Local Development organization, and verifies the request path and platform services they use.

Prerequisites

Use macOS with Lima 2.0 or newer, Ansible, Node.js/npm, make, curl, and ssh. Homebrew users can start with:

brew install lima ansible node

Install D2 to render architecture diagrams and k6 to run all quality and load checks:

brew install d2 k6

Create the appliance

Start the default compact demo appliance:

make up

This command starts one 4 vCPU / 16 GiB / 64 GiB Lima VM, applies the same Ansible roles used by the capacity profile, deploys examples/sum and the composed examples through Wrangler, exercises them, and verifies that the telemetry pipeline receives metrics, logs, and traces. It then enables trusted local HTTPS for Worker ingress. It is safe to re-run against the running appliance.

The Lima appliance uses a pinned Ubuntu 26.04 image; the Ansible roles accept supported Ubuntu releases from 24.04 through the 26.x series. The platform also pins workerd and Wrangler versions in source. Run make multi-up to use six purpose-sized nodes totaling 28 vCPUs and 52 GiB of memory. Its disks are sparse: two compute nodes use 24 GiB each, while storage and observability nodes receive more disk capacity. See Deployment profiles and capacity for the complete placement table.

Explore the examples

Open the two composed applications. The photo workflow has separate management and public surfaces:

• https://order-desk.t-bd7662a5eeb4.workers.ermahgerd.localhost:8443
• https://photo-studio.t-bd7662a5eeb4.workers.ermahgerd.localhost:8443
• https://photo-gallery.t-bd7662a5eeb4.workers.ermahgerd.localhost:8443
• https://durable-counter.t-bd7662a5eeb4.workers.ermahgerd.localhost:8443

The photo studio redirects through Access and accepts the bootstrap owner credentials. The photo gallery is intentionally public.

Order desk connects a static UI and API to a durable queue, background Worker, database, KV status records, and an R2 archive. Photo gallery performs native image resizing in a background Worker, keeps its catalog in a database, and publishes approved renditions from R2. If you add a Fireworks connection under AI → Models, photo processing can also generate structured descriptions, categories, and tags. The example guide explains each workflow. The durable counter demonstrates native named state, SQLite persistence, alarms, RPC, and WebSockets through an ordinary Wrangler deployment.

The original sum Worker remains a useful stateless canary:

make test

Or call it directly through HAProxy:

curl -sS -H 'content-type: application/json' \
  -H 'Host: sum.t-bd7662a5eeb4.workers.ermahgerd.localhost' \
  -d '{"a":20,"b":22}' http://127.0.0.1:8080/sum

The expected response is {"result":42}. The sample Worker also provides GET /health for its own convenience; the platform does not require Workers to implement that endpoint.

Sign in to the console

The public root at http://ermahgerd.localhost:8080 shows the platform name and a sign-in link. The bootstrap account below already has organization-creation access and owns the seeded Local Development organization.

Open http://console.ermahgerd.localhost:8081 and use the local bootstrap identity:

Email:    owner@localhost
Password: local-owner-password

The tenant console opens at your organization directory. Select Local Development to manage its Workers, data services, AI connections, vector indexes, version history, and limits. Platform administration is a separate portal at http://admin.ermahgerd.localhost:8082 with its own session. These credentials are development defaults; do not expose them outside host loopback. The console guide walks through each surface with real screenshots.

Local endpoints

Lima forwards only the listed host-loopback endpoints. Private services bind to the fleet WireGuard addresses, and runtime pool ports are admitted only on the WireGuard interface; they are not forwarded to the host.

Grafana, Loki, Tempo, and Prometheus are provisioned for advanced operator investigation. The tenant and administrator portals are the supported day-to-day interfaces.

VM lifecycle

make site       # apply Ansible to the compact appliance
make status     # inspect its Lima and systemd health
make ssh        # open a shell on single-01
make down       # stop it and retain its disk/state
make destroy    # remove it and all local platform state

Use make multi-site, make multi-status, make multi-ssh, make multi-down, and make multi-destroy for the optional six-node profile. After a destroy, use the corresponding up or multi-up target to return to a known-good appliance. See Operating the appliance for maintenance and health checks.

The same product guides are also deployed as a Nimbus site at https://ermahgerd-docs.t-bd7662a5eeb4.workers.ermahgerd.localhost:8443.