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

6.8 KiB

Raw Blame History

Environment variables

The picloud server is configured entirely through environment variables. This is the complete list, grouped by area. Only DATABASE_URL and a master key are strictly required to boot.

Required to boot

Variable	Default	Purpose
`DATABASE_URL`	—	Required. Postgres connection string.
`PICLOUD_SECRET_KEY`	—	Master encryption key, base64 of 32 bytes. Required unless dev mode is acknowledged (below). Encrypts secrets and realtime keys at rest.

On a fresh database you also need the bootstrap admin vars. After that, only the two above are required.

Dev mode

Variable	Default	Purpose
`PICLOUD_DEV_MODE`	`false`	Enables local-dev conveniences (in-memory email sink). Never in production.
`PICLOUD_DEV_INSECURE_KEY`	—	Set to the literal `i-understand-this-is-insecure` to boot without `PICLOUD_SECRET_KEY`, using a deterministic, world-known dev key. `PICLOUD_DEV_MODE=true` alone aborts — you must also set this. Never in production.

Network & process

Variable	Default	Purpose
`PICLOUD_BIND`	`0.0.0.0:8080`	HTTP listen address. (In Compose, picloud binds 8080 inside the network; Caddy publishes 8000.)
`PICLOUD_PUBLIC_BASE_URL`	`http://localhost:8000`	Public origin reported by `/version` and used to render URLs.
`PICLOUD_DB_MAX_CONNECTIONS`	`32`	Postgres pool size (matched to the execution cap).
`PICLOUD_MAX_CONCURRENT_EXECUTIONS`	`32`	Global cap on simultaneous script runs. Overflow → `503` + `Retry-After: 1`, no queue.
`PICLOUD_SESSION_TTL_HOURS`	`24`	Admin session sliding-window lifetime.
`RUST_LOG`	`info`	`tracing` filter, e.g. `info,picloud=debug`.
`PICLOUD_CONFIG_DIR`	platform default	Where the `pic` CLI stores credentials.

Bootstrap admin

Read only on a fresh install (empty admin_users); ignored afterward. See Server admin commands.

Variable	Purpose
`PICLOUD_ADMIN_USERNAME`	first admin's username (seeded as `owner`)
`PICLOUD_ADMIN_PASSWORD_HASH`	preferred: Argon2id PHC string
`PICLOUD_ADMIN_PASSWORD`	fallback: raw password

Data-plane size caps

Exceeding any cap throws in the script. All in bytes.

Variable	Default	Caps
`PICLOUD_KV_MAX_VALUE_BYTES`	`262144` (256 KiB)	`kv::...set` value
`PICLOUD_DOCS_MAX_VALUE_BYTES`	`262144`	`docs` document
`PICLOUD_PUBSUB_MAX_MESSAGE_BYTES`	`262144`	`pubsub::publish_durable` message
`PICLOUD_QUEUE_MAX_PAYLOAD_BYTES`	`262144`	`queue::enqueue` message
`PICLOUD_SECRET_MAX_VALUE_BYTES`	`262144`	`secrets::set` value
`PICLOUD_FILES_MAX_FILE_SIZE_BYTES`	`104857600` (100 MiB)	`files::...create/update` blob
`PICLOUD_EMAIL_MAX_MESSAGE_BYTES`	—	inbound/outbound email size
`PICLOUD_EMAIL_MAX_RECIPIENTS`	—	recipients per send
`PICLOUD_HTTP_MAX_REQUEST_BODY_BYTES`	—	outbound `http` request body
`PICLOUD_HTTP_MAX_RESPONSE_BODY_BYTES`	—	outbound `http` response body read

Sandbox ceilings

Upper bounds on per-script sandbox overrides. An override above the ceiling is rejected at deploy time. Defaults are the conservative built-ins.

Variable	Default ceiling
`PICLOUD_SANDBOX_MAX_OPERATIONS`	10,000,000
`PICLOUD_SANDBOX_MAX_STRING_SIZE`	1 MiB
`PICLOUD_SANDBOX_MAX_ARRAY_SIZE`	100,000
`PICLOUD_SANDBOX_MAX_MAP_SIZE`	100,000
`PICLOUD_SANDBOX_MAX_CALL_LEVELS`	128
`PICLOUD_SANDBOX_MAX_EXPR_DEPTH`	128

Two related platform-level depth bounds (not per-script overridable):

Variable	Default	Purpose
`PICLOUD_MAX_TRIGGER_DEPTH`	`8`	max trigger fan-out / `invoke` re-entry depth
`PICLOUD_MODULE_IMPORT_DEPTH_MAX`	`8`	max `import` chain depth

Outbound HTTP (`http` SDK)

Variable	Default	Purpose
`PICLOUD_HTTP_ALLOW_PRIVATE`	`false`	Dev/test only. `true` disables the SSRF deny-list (allows requests to private/loopback IPs). Never production.

Email / SMTP

Configure a relay to make email::send work; without it, sends throw NotConfigured (or hit the dev sink in dev mode).

Variable	Purpose
`PICLOUD_SMTP_HOST` / `PICLOUD_SMTP_PORT`	relay address
`PICLOUD_SMTP_USER` / `PICLOUD_SMTP_PASSWORD`	relay auth
`PICLOUD_SMTP_TLS`	TLS mode
`PICLOUD_SMTP_TIMEOUT_SECS`	send timeout

Triggers, dispatcher & background workers

Variable	Default	Purpose
`PICLOUD_DISPATCHER_ASYNC_EXEC_TIMEOUT_SEC`	`120`	per-message executor budget for async/triggered runs
`PICLOUD_DISPATCHER_TICK_INTERVAL_MS`	—	dispatcher poll interval
`PICLOUD_CRON_TICK_INTERVAL_MS`	—	cron scheduler resolution
`PICLOUD_QUEUE_RECLAIM_INTERVAL_MS`	—	how often expired claims are reclaimed
`PICLOUD_QUEUE_DEFAULT_VISIBILITY_TIMEOUT_SECS`	—	default queue claim lease
`PICLOUD_TRIGGER_RETRY_MAX_ATTEMPTS`	`3`	default trigger retry attempts
`PICLOUD_TRIGGER_RETRY_BACKOFF`	`exponential`	default backoff shape
`PICLOUD_TRIGGER_RETRY_BASE_MS`	`1000`	default backoff base
`PICLOUD_TRIGGER_RETRY_JITTER_PCT`	—	retry jitter
`PICLOUD_DEAD_LETTER_RETENTION_DAYS`	`30`	how long dead-letters are kept
`PICLOUD_ABANDONED_EXECUTIONS_RETENTION_DAYS`	—	sweep window for stale in-flight executions

Realtime, subscriber tokens & caches

Variable	Default	Purpose
`PICLOUD_REALTIME_HEARTBEAT_SEC`	`30`	SSE heartbeat interval
`PICLOUD_REALTIME_BROADCAST_CAPACITY`	—	per-topic broadcast buffer
`PICLOUD_SUBSCRIBER_TOKEN_TTL_DEFAULT_SEC` / `_MIN_SEC` / `_MAX_SEC`	—	bounds for `pubsub::subscriber_token` TTLs
`PICLOUD_SCRIPT_CACHE_SIZE` / `PICLOUD_MODULE_CACHE_SIZE`	—	in-memory cache sizes

Files storage

Variable	Default	Purpose
`PICLOUD_FILES_ROOT`	`./data`	filesystem root for `files` blobs
`PICLOUD_FILES_ORPHAN_SWEEP_INTERVAL_SEC` / `PICLOUD_FILES_ORPHAN_TMP_TTL_SEC`	—	cleanup of stale temp blobs

App-user token lifetimes (`users` SDK)

Variable	Purpose
`PICLOUD_APP_USER_SESSION_TTL_HOURS` / `_ABSOLUTE_HOURS`	sliding & absolute session lifetime
`PICLOUD_APP_USER_VERIFICATION_TTL_HOURS`	email-verification token TTL
`PICLOUD_APP_USER_PASSWORD_RESET_TTL_HOURS`	password-reset token TTL
`PICLOUD_APP_USER_INVITATION_TTL_DAYS`	invitation TTL

`pic` CLI

Variable	Purpose
`PICLOUD_URL`	default server URL for `pic`
`PICLOUD_TOKEN`	bearer token for `pic` (CI)

Values shown as "—" have an internal default that's safe to leave unset; consult the running instance or release notes if you need the exact number for capacity planning.

6.8 KiB Raw Blame History