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>
43 lines
2.0 KiB
Markdown
43 lines
2.0 KiB
Markdown
# 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`](../rest-api/access.md#admin-users-instance) 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:
|
|
|
|
```sh
|
|
# 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
|
|
> (`pic` or `curl`).
|