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>
2.0 KiB
Server admin commands
Separate from the pic developer CLI, the picloud server binary carries a tiny set of
operator/recovery subcommands you run directly on the host (no auth — they touch the database through
DATABASE_URL). These are for out-of-band situations where you can't log in.
Bootstrap the first admin (env vars)
On a fresh install (empty admin_users table), the server seeds the first admin — always as
owner — from environment variables:
| Variable | Notes |
|---|---|
PICLOUD_ADMIN_USERNAME |
required |
PICLOUD_ADMIN_PASSWORD_HASH |
preferred — a pre-computed Argon2id PHC string, so the raw password never lands in env/compose |
PICLOUD_ADMIN_PASSWORD |
fallback — raw password, hashed on first boot |
If both the hash and the raw password are set, the hash wins (and a warning is logged). These are
read only when no admin exists yet — on a database that already has an admin, they're ignored (with a
warning). After that, manage admins via pic admins or
the recovery command below.
picloud admin reset-password
Reset (and reactivate) an admin's password without logging in — the escape hatch when you've locked yourself out:
# interactive: prompts for a new password on stdin
picloud admin reset-password admin
# non-interactive: supply a pre-computed Argon2id PHC hash
picloud admin reset-password admin --password-hash '$argon2id$v=19$m=…'
It re-activates a deactivated admin and drops all of that admin's sessions (forcing re-login). It
needs the same DATABASE_URL (and master key) the server normally runs with. Run it on the host, e.g.
inside the container: docker compose exec picloud picloud admin reset-password admin.
This is the only subcommand on the server binary besides running the server itself. Everything else — creating more admins, changing roles, minting keys — goes through the authenticated API (
picorcurl).