Files

MechaCat02 05ea29fbd0 docs: add comprehensive developer guide (mdBook)

Add a browsable mdBook developer guide under docs/dev-guide/ covering the
full PiCloud v1.1.9 surface for developers building on the platform:

- Guide: introduction, 10-minute quickstart, core concepts, writing scripts
- Tutorials: 5 end-to-end example apps (URL shortener, webhook receiver,
  TODO API with auth, scheduled report, file-upload service) + feature matrix
- SDK reference: kv/docs/files, pubsub/queue, http, email, users, secrets,
  invoke/retry/dead_letters, stdlib, ctx & events
- HTTP API reference: every /api/v1 endpoint, auth, and capability
- CLI reference: the `pic` client + the server admin recovery command
- Config: every PICLOUD_* env var, capabilities & roles
- Deployment: Docker Compose, bare binary, Caddy/TLS, production checklist
- Operations: security, best practices, troubleshooting

Every example was built and run against a live instance; SDK signatures,
endpoint paths, and env vars were verified against source. Build the site
with `mdbook serve docs/dev-guide`. A pointer is added to README.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

2026-06-20 13:54:23 +02:00

2.9 KiB

Raw Permalink Blame History

PiCloud

A lightweight, self-hosted, event-driven serverless compute platform. Upload a Rhai script, get an HTTP endpoint. Designed to run on a single modest server with no idle CPU cost, and to scale out to a small cluster when you need it.

Status: Phase 1 — MVP scaffolding in progress.

The authoritative design lives in serverless_cloud_blueprint.md.

Why

Existing serverless platforms are either cloud-locked, heavyweight, or both. PiCloud aims for the opposite end of the spectrum: one binary, one database, one reverse proxy — running on hardware you already own.

Architecture (one paragraph)

PiCloud splits into three logical services — manager (control plane: scripts, schedules, dashboard), orchestrator (per-node event ingress and dispatch), and executor (per-node Rhai sandbox) — each backed by a *-core Rust library. In MVP they run in a single process; in cluster mode they run as three binaries with one manager and one orchestrator + executor per node. Caddy fronts everything; PostgreSQL is the single source of truth.

See CLAUDE.md for working notes and serverless_cloud_blueprint.md for the full design.

Quick Start

Coming as scaffolding lands. For now:

# Rust toolchain (pinned via rust-toolchain.toml)
cargo check --workspace

# Run the all-in-one MVP binary (once main.rs is wired up)
cargo run -p picloud

Documentation

The Developer Guide in docs/dev-guide/ is the place to start using PiCloud — quickstart, core concepts, full SDK / HTTP-API / CLI reference, five end-to-end example apps, and deployment + security guides. Build and read it locally with mdBook:

cargo install mdbook          # once
mdbook serve docs/dev-guide   # then open http://localhost:3000

Architecture and contributor notes live alongside it in docs/ (sdk-shape.md, stdlib-reference.md, versioning.md, …) and in serverless_cloud_blueprint.md.

Repository Layout

crates/
  shared/                 cross-cutting types
  executor-core/          Rhai engine + sandbox
  orchestrator-core/      event ingress, dispatch
  manager-core/           control plane
  picloud/                MVP all-in-one binary
  picloud-{manager,orchestrator,executor}/   cluster-mode binaries (skeleton)
dashboard/                SvelteKit
caddy/                    Caddyfile
docker/                   Dockerfiles
docs/
  git-workflow.md         Trunk-based workflow

Contributing

See docs/git-workflow.md for the branching and commit conventions. TL;DR: trunk-based, short-lived branches, Conventional Commits, no force-pushing main.

License

TBD.

2.9 KiB Raw Permalink Blame History