05ea29fbd0
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>
69 lines
2.9 KiB
Markdown
69 lines
2.9 KiB
Markdown
# PiCloud
|
|
|
|
A lightweight, self-hosted, event-driven serverless compute platform. Upload a [Rhai](https://rhai.rs/) 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`](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](https://caddyserver.com/) fronts everything; [PostgreSQL](https://www.postgresql.org/) is the single source of truth.
|
|
|
|
See [`CLAUDE.md`](CLAUDE.md) for working notes and [`serverless_cloud_blueprint.md`](serverless_cloud_blueprint.md) for the full design.
|
|
|
|
## Quick Start
|
|
|
|
> _Coming as scaffolding lands. For now:_
|
|
|
|
```sh
|
|
# 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/`](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](https://rust-lang.github.io/mdBook/):
|
|
|
|
```sh
|
|
cargo install mdbook # once
|
|
mdbook serve docs/dev-guide # then open http://localhost:3000
|
|
```
|
|
|
|
Architecture and contributor notes live alongside it in [`docs/`](docs/) (`sdk-shape.md`,
|
|
`stdlib-reference.md`, `versioning.md`, …) and in [`serverless_cloud_blueprint.md`](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`](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.
|