@supacloud/lite 0.33.2 → 0.35.0

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## [0.35.0](https://github.com/vibeunion/supacloud/compare/supacloud-lite-v0.34.0...supacloud-lite-v0.35.0) (2026-10-26)
+
+
+### Features
+
+* **lite:** add PostgREST count strategies and rollback preference ([#2253](https://github.com/vibeunion/supacloud/issues/2253)) ([b87ef01](https://github.com/vibeunion/supacloud/commit/b87ef01f320cb1ed5b94cd16ea0412cf798fe5c9))
+* **lite:** add S3-compatible storage endpoint ([#2252](https://github.com/vibeunion/supacloud/issues/2252)) ([37a37b3](https://github.com/vibeunion/supacloud/commit/37a37b3e193cd328a5ef5e852d927b594ad1856f))
+
+## [0.34.0](https://github.com/vibeunion/supacloud/compare/supacloud-lite-v0.33.2...supacloud-lite-v0.34.0) (2026-10-26)
+
+
+### Features
+
+* **lite:** add authorized realtime HTTP broadcast ([#2250](https://github.com/vibeunion/supacloud/issues/2250)) ([405747c](https://github.com/vibeunion/supacloud/commit/405747cce8f055c371e8f76c38a862aaf480f94c))
+* **lite:** add production readiness doctor checks ([#2249](https://github.com/vibeunion/supacloud/issues/2249)) ([d9f09f2](https://github.com/vibeunion/supacloud/commit/d9f09f2ff797898af9a68d2c261b9d66e0eea001))
+* **lite:** add restricted same-origin external auth proxy ([#2247](https://github.com/vibeunion/supacloud/issues/2247)) ([10e420e](https://github.com/vibeunion/supacloud/commit/10e420e700f206a8f190e6d51622c980d867fc68))
+* **lite:** add storage status and metrics endpoints ([#2251](https://github.com/vibeunion/supacloud/issues/2251)) ([183b323](https://github.com/vibeunion/supacloud/commit/183b32397006a2b80d9961e7ae26d5779654b064))
+
+
+### Documentation
+
+* **lite:** add single-node production deployment assets ([#2248](https://github.com/vibeunion/supacloud/issues/2248)) ([1e36554](https://github.com/vibeunion/supacloud/commit/1e36554cbbdbfecbb1e2a4974af560e8fa62124a))
+
 ## [0.33.2](https://github.com/vibeunion/supacloud/compare/supacloud-lite-v0.33.1...supacloud-lite-v0.33.2) (2026-10-25)
 
 

package/README.md

@@ -166,8 +166,23 @@ Lite 支持平铺 SQL 与 `时间戳目录/migration.sql`，执行前检查重
 
 `/graphql/v1` 使用真正的 `pg_graphql` 扩展和调用者的数据库角色/RLS，不模拟扩展。默认 PGlite 和标准 native 下载包均不包含该扩展；native 可通过 `--postgres-dir` 选择已经安装匹配扩展的 PostgreSQL。配置 `[lite.graphql] enabled = true` 会在运行时启动前验证扩展，`doctor --json` 区分已支持、缺失与尚未验证。
 
+`doctor --production` 在能力报告之外检查单机生产阻断项和运维义务：strict 运行时、非内存存储、外部身份同源代理、公开地址、数据库/存储目录隔离、状态目录位置和快照新鲜度。阻断项使命令以非零退出码结束；警告项表示必须由部署方承担的运维责任（例如 S3 对象不在快照内、PGlite 容量验证、TLS 必须由反代终止）。
+
 外部 SupAuth 可通过 `createSupAuthLiteIdentity` 复用 `@supacloud/elysia` 的验证和业务侧本地用户映射；本地 Auth 仍是默认模式。外部模式不会把本地令牌降级当成 SupAuth，也不会根据请求头授予权限。
 
+如果浏览器应用与身份服务不同源，且身份服务没有为业务域名开放 CORS，可在 Lite 前面启用受限的同源 OAuth 反代：
+
+```sh
+supacloud-lite start \
+  --external-auth-proxy-issuer https://auth.example.com/auth/v1 \
+  --external-auth-proxy-redirect-origin https://app.example.com
+```
+
+反代只接受 `/auth/v1/oauth/token`（POST）、`/auth/v1/oauth/userinfo`（GET）和
+`/auth/v1/logout`（GET/POST），不会转发 cookie、`x-forwarded-*` 或任意上游地址。
+授权请求仍由浏览器顶层跳转到身份服务；应用端把 token/userinfo 指向 Lite 同源地址。
+嵌入宿主也可以直接调用 `createExternalAuthProxy()`。
+
 完整配置、边界和回归方法见仓库文档 `docs/lite-runtime-compatibility.md`。性能基线可在源码目录运行 `bun run benchmark`，native 模式加 `--native`。
 
 ### CLI
@@ -187,7 +202,7 @@ supacloud-lite snapshot create [-o backup.tar.gz]
 supacloud-lite snapshot restore <backup.tar.gz> [--force]
 supacloud-lite upgrade [-o pre-upgrade.tar.gz]
 supacloud-lite inspect
-supacloud-lite doctor [--json]
+supacloud-lite doctor [--json] [--production]
 supacloud-lite version
 ```
 
@@ -238,6 +253,9 @@ supacloud-lite auth create-user --project-dir ./my-project \
 - `SUPACLOUD_LITE_STORAGE_DIR`
 - `SUPACLOUD_LITE_STORAGE_BACKEND`：`fs`（默认）、`memory` 或 `s3`
 - `SUPACLOUD_LITE_S3_PREFIX`：S3 对象 key 前缀，可被 `--s3-prefix` 覆盖
+- `SUPACLOUD_LITE_S3_ENDPOINT_ACCESS_KEY_ID` / `SUPACLOUD_LITE_S3_ENDPOINT_SECRET_ACCESS_KEY`：启用入站 `/storage/v1/s3` 的 SigV4 凭据，必须成对设置
+- `SUPACLOUD_LITE_S3_ENDPOINT_REGION`：入站 S3 期望的 SigV4 region，默认 `us-east-1`
+- `SUPACLOUD_LITE_S3_ENDPOINT_BUCKETS`：逗号分隔的入站 S3 bucket allowlist；为空表示项目内全部 bucket
 - `SUPACLOUD_LITE_POSTGRES_MIRROR`：native 引擎下载 PostgreSQL 发布包时使用的 HTTPS 镜像前缀，例如 `https://ghproxy.net/`
 - `SUPACLOUD_LITE_ENGINE`：`pglite`（默认）或 `native`
 - `SUPACLOUD_LITE_REPLICATION_PROFILE`：仅支持显式值 `powersync`，且仅用于 native 引擎
@@ -351,6 +369,26 @@ S3 模式的快照只包含数据库中的 Storage 元数据和密钥，不复
 
 内存数据库没有可持久化的数据，因此 `snapshot` 和 `upgrade` 会拒绝 `--memory`。
 
+### S3 兼容入口
+
+设置 `SUPACLOUD_LITE_S3_ENDPOINT_ACCESS_KEY_ID` 和 `SUPACLOUD_LITE_S3_ENDPOINT_SECRET_ACCESS_KEY` 后，Lite 会在 `/storage/v1/s3` 挂载 SigV4 + XML 的 S3 协议入口。AWS SDK 使用 path-style endpoint：
+
+```ts
+const s3 = new S3Client({
+  endpoint: 'https://example.com/storage/v1/s3',
+  region: 'us-east-1',
+  forcePathStyle: true,
+  credentials: { accessKeyId, secretAccessKey },
+})
+```
+
+支持 `ListBuckets`、Bucket 创建/HEAD/删除、`PutObject`、`GetObject`/Range、`HeadObject`、`DeleteObject`、`DeleteObjects`、`ListObjectsV2`、`CopyObject`、Presigned GET，以及最多 10000 个 part 的 multipart 上传。Multipart part 会先写入 StorageDriver 的临时 key，完成时按顺序合并；因此它适合单机 Lite，不是大规模并行对象组装服务。
+
+S3 对象和 multipart 完成后的总大小上限为 64 MiB，同时遵守 bucket 的大小、MIME 类型限制及项目默认大小限制。Multipart 完成请求必须明确列出升序且不重复的 part；XML 请求体上限为 2 MiB。
+项目最多保留 128 个活跃 multipart 上传、10000 个临时 part 和 256 MiB 临时数据。上传 24 小时后过期，启动和后续 multipart 请求会清理过期数据；删除 bucket 时也会清理其临时分片。
+
+第一版明确限制：只支持 path-style，不支持 virtual-hosted-style、S3 ACL/Bucket Policy、Versioning、Object Lock、Replication、S3 Select 和 `STREAMING-*` SigV4 payload。S3 凭据是服务级凭据，默认绕过 RLS；需要隔离时用 `SUPACLOUD_LITE_S3_ENDPOINT_BUCKETS` 限定 bucket。S3 写入仍使用与普通 Storage API 相同的 bucket/object 元数据和 StorageDriver。
+
 ### 兼容范围
 
 | 能力 | V1 状态 | 说明 |
@@ -374,6 +412,21 @@ S3 模式的快照只包含数据库中的 Storage 元数据和密钥，不复
 
 RLS 表的 Realtime DELETE 无法在行删除后安全重放 SELECT policy，因此 V1 只向 `service_role` 订阅者发送这类 DELETE 事件。普通用户仍可收到通过逐行 RLS 校验的 INSERT/UPDATE 事件。
 
+PostgREST 的边缘语义补充：表和 view 的 `Prefer: count=planned` 和 `count=estimated` 都在当前角色与 JWT claims 的只读事务中读取最外层 `count(*)` 输入节点的 `Plan Rows`（该计数聚合节点本身恒为 1），保留过滤条件、RLS、inner embed、view 和查询本身的 GROUP BY 聚合。Lite 不直接读取全表 `pg_class.reltuples`；`estimated` 是保守的 planner 兼容实现，不实现 PostgREST 按阈值切换精确计数的行为，估算值仍可能不准确。两者都只用于 GET/HEAD，结果仍写入 `Content-Range`。`Prefer: tx=rollback` 可包裹成功的 POST/PATCH/DELETE，返回与实际提交相同的状态和 representation，但事务最终回滚且不触发 CDC/webhook。其他 `Prefer` 值（`return`、`resolution`、`missing`）行为不变。
+
+Realtime 也支持服务端 HTTP 广播：
+
+```http
+POST /realtime/v1/api/broadcast
+apikey: <project-anon-key>
+authorization: Bearer <access-token>
+content-type: application/json
+
+{"messages":[{"topic":"room:42","event":"notice","payload":{"text":"hello"},"private":false}]}
+```
+
+请求沿用 Realtime 的 `messages` 数组格式，单次最多 100 条，每条 `event` 最多 256 字节、`topic` 最多 256 字节、`payload` 最多 1 MiB。`private: true` 会按 `realtime.messages` 的 INSERT policy 校验调用者；整个批次先完成校验再发送，任一主题无写权限时返回 `403`，不会部分广播。成功返回 `202 {"message":"Broadcast sent"}`。该端点只做实时投递，不持久化消息；需要离线补偿时仍应使用数据库表或 outbox。
+
 ### Capability doctor 与 PowerSync profile
 
 `doctor` 输出 Lite 自己的稳定能力契约，不复制完整 Management API：
@@ -508,6 +561,10 @@ Lite 的缓存调用是进程内数据库操作，不具备标准版跨进程 HT
 
 V1 不在一个进程内复用多个 PGlite 项目。需要多个项目时，为每个项目配置独立的工作目录、端口和 `.supacloud-lite` 状态目录，并用进程管理器分别启动。这样可保持数据库、JWT、Storage 和 Realtime 的故障域隔离。
 
+### 生产部署
+
+`deploy/` 提供单机生产部署模板：systemd 用户/目录/状态目录约定、Caddy TLS 反代、外部 SupAuth 同源代理、快照维护窗口、S3 对象单独备份和回滚步骤。Lite 不自带 TLS、HA 或控制面；必须保持单进程单状态目录，并由 Caddy/Nginx 终止 TLS。生产前至少应完成容量测试、恢复演练和未认证请求失败关闭验证。
+
 ### 资源边界
 
 PGlite 是 WebAssembly PostgreSQL，不是 SQLite。它换来了 PostgreSQL SQL、角色、RLS 和 Supabase 迁移兼容性，但内存占用通常高于 PocketBase/SQLite。生产部署前应按真实 schema、并发和 Realtime 负载做容量测试。
@@ -531,6 +588,8 @@ await running.close()
 
 图片变换目前提供 Bun.Image 的兼容子集：`width`、`height`、`resize=fill|contain`，以及 `format=origin|jpeg|png|webp` 和 JPEG/WebP `quality`。`resize=cover` 需要裁剪能力，当前 Bun 运行时没有对应 API，因此会明确返回不支持错误，不会错误地把图片拉伸成 `cover`。
 
+Storage 还提供两个运维端点：`GET /storage/v1/status` 无需项目 API key，返回服务名称、版本和健康状态；`GET /storage/v1/metrics` 需要 `service_role`，以 Prometheus 文本格式输出 bucket 数、对象元数据行数和声明对象总字节数。指标只统计 Lite 自己的 `storage` schema，不代表远端 S3 bucket 的真实用量或后台清理延迟。
+
 也可以使用 `createLiteBackend()` 直接创建内存或自定义目录的嵌入式后端，并把它的 `fetch` 传给自定义宿主。
 
 ### 来源与许可
@@ -662,7 +721,7 @@ supacloud-lite snapshot create [-o backup.tar.gz]
 supacloud-lite snapshot restore <backup.tar.gz> [--force]
 supacloud-lite upgrade [-o pre-upgrade.tar.gz]
 supacloud-lite inspect
-supacloud-lite doctor [--json]
+supacloud-lite doctor [--json] [--production]
 supacloud-lite version
 ```
 
@@ -707,6 +766,9 @@ Environment variables:
 - `SUPACLOUD_LITE_STORAGE_DIR`
 - `SUPACLOUD_LITE_STORAGE_BACKEND`: `fs` (default), `memory`, or `s3`
 - `SUPACLOUD_LITE_S3_PREFIX`: S3 object key prefix, can be overridden by `--s3-prefix`
+- `SUPACLOUD_LITE_S3_ENDPOINT_ACCESS_KEY_ID` / `SUPACLOUD_LITE_S3_ENDPOINT_SECRET_ACCESS_KEY`: SigV4 credentials enabling the inbound `/storage/v1/s3` endpoint; set both together
+- `SUPACLOUD_LITE_S3_ENDPOINT_REGION`: SigV4 region expected by the inbound S3 endpoint, default `us-east-1`
+- `SUPACLOUD_LITE_S3_ENDPOINT_BUCKETS`: comma-separated bucket allowlist for the inbound endpoint; empty means every project bucket
 - `SUPACLOUD_LITE_POSTGRES_MIRROR`: HTTPS prefix used to proxy native-engine PostgreSQL release downloads, for example `https://ghproxy.net/`
 - `SUPACLOUD_LITE_ENGINE`: `pglite` (default) or `native`
 - `SUPACLOUD_LITE_REPLICATION_PROFILE`: explicit `powersync` opt-in for the native engine only
@@ -853,10 +915,54 @@ GraphQL fails startup when missing; `doctor --json` reports actual or unverified
 capability. External SupAuth can reuse the shared Elysia verifier through
 `createSupAuthLiteIdentity` and an explicit application-owned local user mapping.
 
+When the browser application and the identity service have different origins and
+the identity service does not allow the application origin via CORS, Lite can
+serve a restricted same-origin OAuth proxy:
+
+```sh
+supacloud-lite start \
+  --external-auth-proxy-issuer https://auth.example.com/auth/v1 \
+  --external-auth-proxy-redirect-origin https://app.example.com
+```
+
+The proxy accepts only `/auth/v1/oauth/token` (POST),
+`/auth/v1/oauth/userinfo` (GET) and `/auth/v1/logout` (GET/POST). It never
+forwards cookies, `x-forwarded-*`, or arbitrary upstream URLs. Authorization
+remains a top-level navigation to the identity service; the application points
+token/userinfo at the Lite same-origin address. Embedded hosts can call
+`createExternalAuthProxy()` directly.
+
+`doctor --production` adds single-node production policy checks: strict runtime,
+non-memory storage, external identity proxying, public URLs, database/storage
+path separation, state-directory location and snapshot freshness. Blockers exit
+non-zero; warnings are operational obligations such as backing up S3 objects
+outside the Lite snapshot, capacity-testing PGlite, and terminating TLS at the
+proxy.
+
 See repository document `docs/lite-runtime-compatibility.md` for configuration
 and acceptance boundaries. Run `bun run benchmark` (or add `--native`) in the
 source package for a synthetic baseline, not a production performance claim.
 
+### S3-compatible endpoint
+
+When `SUPACLOUD_LITE_S3_ENDPOINT_ACCESS_KEY_ID` and `SUPACLOUD_LITE_S3_ENDPOINT_SECRET_ACCESS_KEY` are set, Lite mounts a SigV4 + XML S3 endpoint at `/storage/v1/s3`. Configure AWS SDKs with a path-style endpoint:
+
+```ts
+const s3 = new S3Client({
+  endpoint: 'https://example.com/storage/v1/s3',
+  region: 'us-east-1',
+  forcePathStyle: true,
+  credentials: { accessKeyId, secretAccessKey },
+})
+```
+
+It supports `ListBuckets`, bucket create/HEAD/delete, `PutObject`, `GetObject`/Range, `HeadObject`, `DeleteObject`, `DeleteObjects`, `ListObjectsV2`, `CopyObject`, presigned GET, and multipart uploads with up to 10000 parts. Multipart parts are staged in the StorageDriver and concatenated on completion; this is suitable for single-node Lite, not a distributed object-assembly service.
+
+S3 objects, including completed multipart uploads, are limited to 64 MiB and also honor bucket size/MIME restrictions and the project default size limit. Completion requests must explicitly list unique parts in ascending order. XML request bodies are limited to 2 MiB.
+Each project allows at most 128 active uploads, 10000 staged parts and 256 MiB of staged bytes. Uploads expire after 24 hours and are reclaimed at startup and on subsequent multipart requests. Bucket deletion also removes its staged multipart data.
+
+The first version deliberately excludes virtual-hosted-style addressing, S3 ACL/Bucket Policy, Versioning, Object Lock, Replication, S3 Select, and `STREAMING-*` SigV4 payloads. S3 credentials are service-level and bypass RLS by default; use `SUPACLOUD_LITE_S3_ENDPOINT_BUCKETS` to restrict buckets. S3 writes use the same bucket/object metadata and StorageDriver as the normal Storage API.
+
 ### Compatibility Scope
 
 | Capability | V1 Status | Notes |
@@ -880,6 +986,21 @@ source package for a synthetic baseline, not a production performance claim.
 
 Realtime DELETE on RLS tables cannot safely replay SELECT policies after a row is deleted, so V1 only sends such DELETE events to `service_role` subscribers. Regular users can still receive INSERT/UPDATE events that pass row-by-row RLS validation.
 
+PostgREST edge semantics: for tables and views, `Prefer: count=planned` and `count=estimated` both read the `Plan Rows` of the outermost `count(*)` input inside the current role and JWT-claims read-only transaction (that counting aggregate itself always produces one row). This preserves filters, RLS, inner embeds, views, and the query's own GROUP BY aggregates. Lite does not read relation-wide `pg_class.reltuples` directly; `estimated` is a conservative planner-based compatibility implementation, not PostgREST's threshold-based switch to exact counting, and estimates may still be inaccurate. Both are only evaluated for GET/HEAD and still populate `Content-Range`. `Prefer: tx=rollback` wraps a successful POST/PATCH/DELETE, returns the same status and representation as a commit, then rolls the transaction back without firing CDC/webhooks. Other `Prefer` values (`return`, `resolution`, `missing`) keep their existing behavior.
+
+Realtime also exposes server-side HTTP broadcast:
+
+```http
+POST /realtime/v1/api/broadcast
+apikey: <project-anon-key>
+authorization: Bearer <access-token>
+content-type: application/json
+
+{"messages":[{"topic":"room:42","event":"notice","payload":{"text":"hello"},"private":false}]}
+```
+
+It uses Realtime's `messages` envelope: at most 100 messages per request, each `event` and `topic` at most 256 bytes, and each `payload` at most 1 MiB. `private: true` authorizes the caller through the `realtime.messages` INSERT policy. The whole batch is authorized before any delivery, so one denied topic returns `403` without partially broadcasting. Success returns `202 {"message":"Broadcast sent"}`. This endpoint delivers live events only; use a database table or outbox when messages must survive disconnects.
+
 ### Capability doctor and PowerSync profile
 
 `supacloud-lite doctor --json` reports a stable Lite capability contract without copying the full Management API. PGlite explicitly reports Logical Replication and PowerSync source support as `unsupported`; it never emulates WAL, publications, or slots. Multi-device offline deployments should use central SupaCloud + PowerSync, while a single field workstation can use Lite as a local project server or upload through an application-owned outbox.
@@ -998,6 +1119,16 @@ Lite's cache calls are in-process database operations and do not have the timeou
 
 V1 does not multiplex multiple PGlite projects within a single process. When multiple projects are needed, configure an independent working directory, port, and `.supacloud-lite` state directory for each project, and start them separately with a process manager. This keeps the database, JWT, Storage, and Realtime failure domains isolated.
 
+### Production Deployment
+
+The `deploy/` directory documents a single-node production contract: systemd
+service account/state directories, Caddy TLS termination, external SupAuth
+same-origin proxying, snapshot maintenance windows, separate S3 object backup,
+and rollback. Lite does not bundle TLS, HA, or a control plane. Keep one process
+per state directory and terminate TLS at Caddy/Nginx. Before production, run
+capacity tests, a restore drill, and an unauthenticated-request fail-closed
+check.
+
 ### Resource Boundaries
 
 PGlite is WebAssembly PostgreSQL, not SQLite. It trades off for PostgreSQL SQL, roles, RLS, and Supabase migration compatibility, but its memory footprint is typically higher than PocketBase/SQLite. Before production deployment, you should perform capacity testing against the real schema, concurrency, and Realtime load.
@@ -1021,6 +1152,8 @@ await running.close()
 
 Image transforms currently provide a compatible subset of Bun.Image: `width`, `height`, `resize=fill|contain`, as well as `format=origin|jpeg|png|webp` and JPEG/WebP `quality`. `resize=cover` requires cropping capability, which the current Bun runtime does not have a corresponding API for, so it explicitly returns an unsupported error instead of incorrectly stretching the image to `cover`.
 
+Storage also exposes two operational endpoints: `GET /storage/v1/status` needs no project API key and returns the service name, version, and health; `GET /storage/v1/metrics` requires `service_role` and returns Prometheus text with bucket count, object metadata rows, and declared object bytes. These metrics cover Lite's `storage` schema only; they do not claim the real usage of a remote S3 bucket or background cleanup latency.
+
 You can also use `createLiteBackend()` to directly create an embedded backend with an in-memory or custom directory, and pass its `fetch` to a custom host.
 
 ### Provenance and License

package/deploy/README.md

@@ -0,0 +1,110 @@
+# SupaCloud Lite production deployment
+
+This directory contains a minimal single-project deployment contract. It is not
+a multi-tenant control plane. Run one Lite process per state directory and put
+TLS plus a reverse proxy in front of it.
+
+## Layout
+
+```text
+/opt/supacloud-lite/project       reviewed migrations, seed and functions (read-only at runtime)
+/var/lib/supacloud-lite           database, storage and snapshots (persistent)
+/etc/supacloud-lite/env           secrets and runtime configuration (root:root 0600)
+/usr/local/bin/supacloud-lite     installed CLI / standalone binary
+```
+
+The systemd unit sets `SUPACLOUD_LITE_STATE_DIR=/var/lib/supacloud-lite`, so the
+project checkout does not contain mutable data.
+
+## Install
+
+1. Install the pinned Lite release and verify its version.
+2. Create a service account and directories:
+
+```sh
+sudo useradd --system --home /var/lib/supacloud-lite --shell /usr/sbin/nologin supacloud-lite
+sudo install -d -o supacloud-lite -g supacloud-lite -m 0750 /var/lib/supacloud-lite
+sudo install -d -o root -g root -m 0755 /opt/supacloud-lite/project /etc/supacloud-lite
+```
+
+3. Put the reviewed project files under `/opt/supacloud-lite/project`.
+4. Create `/etc/supacloud-lite/env` from the project's deployment secret store.
+   Keep it `root:root` and `0600`. Supported values include `S3_*` credentials,
+   `SUPACLOUD_LITE_S3_PREFIX`, `SUPACLOUD_LITE_STORAGE_BACKEND=s3`, and the
+   trusted external identity module setting.
+5. Run migrations and create the first local account **before** starting the
+   service:
+
+```sh
+sudo -u supacloud-lite env SUPACLOUD_LITE_STATE_DIR=/var/lib/supacloud-lite \
+  supacloud-lite migrate --project-dir /opt/supacloud-lite/project
+sudo -u supacloud-lite env SUPACLOUD_LITE_STATE_DIR=/var/lib/supacloud-lite \
+  supacloud-lite auth create-user --project-dir /opt/supacloud-lite/project \
+  --email operator@example.com --password-stdin --email-confirm < /secure/password.txt
+```
+
+6. Install the unit and reload systemd:
+
+```sh
+sudo install -m 0644 deploy/systemd/supacloud-lite.service /etc/systemd/system/
+sudo systemctl daemon-reload
+sudo systemctl enable --now supacloud-lite
+curl -fsS http://127.0.0.1:54321/health
+```
+
+7. Install the Caddy site from `deploy/caddy/Caddyfile`, replace the hostname,
+   and verify HTTPS plus an authenticated API request.
+
+## External SupAuth
+
+If the browser application and identity service are on different origins and
+the identity service does not allow the application origin via CORS, use the
+restricted same-origin proxy documented in the package README:
+
+```sh
+supacloud-lite start \
+  --external-auth-proxy-issuer https://auth.example.com/auth/v1 \
+  --external-auth-proxy-redirect-origin https://app.example.com
+```
+
+The proxy handles only OAuth token, userinfo and logout. Authorization remains a
+top-level navigation. Membership and application permissions stay in the
+application-owned data and RLS model; Lite does not grant them from token claims.
+
+## Backup, upgrade and restore
+
+Lite snapshots require the process to be stopped. Use a maintenance window:
+
+```sh
+sudo systemctl stop supacloud-lite
+sudo -u supacloud-lite env SUPACLOUD_LITE_STATE_DIR=/var/lib/supacloud-lite \
+  supacloud-lite snapshot create \
+  --project-dir /opt/supacloud-lite/project \
+  -o /var/lib/supacloud-lite/backups/pre-upgrade.tar.gz
+sudo systemctl start supacloud-lite
+```
+
+For an upgrade, stop the service, install the pinned candidate, run
+`supacloud-lite upgrade`, start the service, and verify `/health` and a real
+authenticated read. If the upgrade fails, restore the pre-upgrade snapshot with
+`snapshot restore --force` and restart the previous binary.
+
+When using S3, snapshots contain database metadata and secrets but **not remote
+objects**. Back up the bucket/prefix separately and restore it before starting
+the service. `db reset` is intentionally rejected in S3 mode.
+
+## Production checks
+
+Before exposing the service:
+
+- keep the process bound to loopback and terminate TLS at the proxy;
+- use `--runtime-mode strict` for functions;
+- set an explicit snapshot retention period and test a restore drill;
+- use S3/MinIO or a durable mounted volume for storage, not an ephemeral disk;
+- use native PostgreSQL when the project needs extensions such as `pg_graphql`;
+- keep one process per state directory; Lite is not a multi-writer cluster;
+- verify unauthenticated API calls fail closed and authenticated reads succeed.
+
+`supacloud-lite doctor --json` reports the selected engine, extension inventory,
+identity mode and replication readiness. It is a capability report, not a
+production security certification.

package/deploy/caddy/Caddyfile

@@ -0,0 +1,15 @@
+# Replace app.example.com with the real public hostname.
+# Lite must remain bound to 127.0.0.1:54321 behind this proxy.
+https://app.example.com {
+	encode zstd gzip
+
+	# Caddy terminates TLS and forwards WebSocket/Realtime upgrades by default.
+	reverse_proxy 127.0.0.1:54321
+
+	header {
+		Strict-Transport-Security "max-age=31536000; includeSubDomains"
+		X-Content-Type-Options "nosniff"
+		Referrer-Policy "strict-origin-when-cross-origin"
+		-Server
+	}
+}

package/deploy/systemd/supacloud-lite.service

@@ -0,0 +1,32 @@
+[Unit]
+Description=SupaCloud Lite (single-project backend)
+Documentation=https://github.com/vibeunion/supacloud/tree/main/packages/supacloud-lite
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+User=supacloud-lite
+Group=supacloud-lite
+WorkingDirectory=/opt/supacloud-lite/project
+EnvironmentFile=/etc/supacloud-lite/env
+Environment=SUPACLOUD_LITE_STATE_DIR=/var/lib/supacloud-lite
+Environment=SUPACLOUD_LITE_HOST=127.0.0.1
+Environment=SUPACLOUD_LITE_PORT=54321
+Environment=SUPACLOUD_LITE_RUNTIME_MODE=strict
+ExecStart=/usr/local/bin/supacloud-lite start --project-dir /opt/supacloud-lite/project
+Restart=on-failure
+RestartSec=3
+# Lite has no bundled TLS termination. Keep it on loopback and terminate TLS in
+# Caddy/Nginx; bind a non-loopback address only when another trusted proxy or
+# network boundary protects it.
+UMask=0077
+NoNewPrivileges=true
+PrivateTmp=true
+ProtectHome=true
+ProtectSystem=strict
+StateDirectory=supacloud-lite
+ReadWritePaths=/var/lib/supacloud-lite
+
+[Install]
+WantedBy=multi-user.target