Add supabase stack + general compose runner
Adds "a stack whose default is a substrate": a shared self-hosted Supabase backend plus a `--stack supabase` that scaffolds per-app projects (migrations + edge functions + static UI) which deploy against it. Apps own their code and stay repo-durable; only their rows/blobs live on the shared substrate. - compose runner: new RunCompose supervises a multi-container stack as one systemd unit (ExecStart=`compose up`, generated ExecStop=`compose down`); secrets via EnvironmentFile. Reusable beyond Supabase. Deployment.stop_cmd carries the teardown command through the registry. - supabase stack: CLI --stack choice, STACK_DEFAULTS→frontend with build.outputs=[public], _scaffold_supabase() (migrations/RLS/functions/ static UI/app manifest), and SupabaseHandler with a forward-only idempotent migration runner (plan_migrations + psql build) and deno dev-verbs. - docs: docs/stacks/supabase.md, registered in CLAUDE.md; compose runner documented in registry.md. - tests: compose run/stop cmd, systemd ExecStop, compose host-route TLS, migration planner, supabase verb resolution, create --stack supabase.
This commit is contained in:
@@ -224,6 +224,7 @@ Discriminated union on `runner`:
|
||||
| `python` | *(none — `uv run` self-syncs)* | `uv run --project <source> --no-dev <program>` | `program`, `args` |
|
||||
| `command` | *(none)* | `which(argv[0])` → resolved path | `argv` |
|
||||
| `container` | *(none)* | `docker`/`podman` `run` | `image`, `command`, `ports`, `volumes` |
|
||||
| `compose` | *(none)* | `docker compose -p <project> -f <file> up` (+ `ExecStop=down`) | `file`, `project_name` |
|
||||
| `node` | `package_manager install` | `package_manager run script` | `script`, `package_manager` |
|
||||
| `remote` | *(none)* | *(none — no local process)* | `base_url`, `health_url` |
|
||||
|
||||
@@ -242,6 +243,23 @@ run:
|
||||
program: my-service # name in [project.scripts]
|
||||
```
|
||||
|
||||
A `compose` service supervises a **whole multi-container stack as one systemd
|
||||
unit** — `ExecStart` runs `docker compose … up` attached (`Type=simple`) and a
|
||||
generated `ExecStop` runs `… down` so networks/anonymous volumes are reclaimed on
|
||||
stop. Unlike the single-container `container` runner, compose owns the stack's own
|
||||
networking, startup ordering, and per-service health — Castle delegates rather
|
||||
than reinventing orchestration. Secrets/env reach compose through the unit's
|
||||
`Environment=`/`EnvironmentFile=` (from `defaults.env`), which compose interpolates
|
||||
from the process environment. This is what runs the shared **Supabase substrate**
|
||||
(see @docs/stacks/supabase.md).
|
||||
|
||||
```yaml
|
||||
run:
|
||||
runner: compose
|
||||
file: docker-compose.yml # resolved under the program source
|
||||
# project_name: castle-my-stack # optional; defaults to castle-<name>
|
||||
```
|
||||
|
||||
### `expose` — What it exposes
|
||||
|
||||
```yaml
|
||||
@@ -599,7 +617,7 @@ The Pydantic models live in `core/src/castle_core/manifest.py`. Key classes:
|
||||
- `ProgramSpec` — software catalog entry (source, behavior, stack, build, system_dependencies)
|
||||
- `ServiceSpec` — long-running daemon (run, expose, proxy, manage, defaults)
|
||||
- `JobSpec` — scheduled task (run, schedule, manage, defaults)
|
||||
- `RunSpec` — discriminated union (RunPython, RunCommand, RunContainer, RunNode, RunRemote)
|
||||
- `RunSpec` — discriminated union (RunPython, RunCommand, RunContainer, RunCompose, RunNode, RunRemote)
|
||||
- `ExposeSpec`, `ProxySpec`, `ManageSpec`, `BuildSpec`
|
||||
- `CaddySpec`, `SystemdSpec`, `HttpExposeSpec`, `HttpInternal`
|
||||
|
||||
|
||||
143
docs/stacks/supabase.md
Normal file
143
docs/stacks/supabase.md
Normal file
@@ -0,0 +1,143 @@
|
||||
# Supabase Apps in Castle
|
||||
|
||||
> **This is a stack — creation-time guidance for writing _new_ database-backed
|
||||
> web apps.** A stack is a template + conventions, not a runtime requirement.
|
||||
> `castle program create --stack supabase` scaffolds from it and seeds the
|
||||
> program's default dev-verb commands. See @docs/registry.md for `commands:`,
|
||||
> `stack:` (optional), and `behavior:`.
|
||||
|
||||
How to build tiny, database-backed web apps as castle programs that target a
|
||||
**shared Supabase substrate**. This is Castle's "a stack whose default is a
|
||||
substrate": the app owns its code (and stays repo-durable), and rents the boring
|
||||
backend — Postgres + auth + storage + RLS — that an app can't reliably reinvent.
|
||||
|
||||
## The model: one shared substrate, many apps
|
||||
|
||||
Unlike the other stacks (which scaffold a self-contained process), a supabase app
|
||||
is **code + migrations that deploy against a shared backend**:
|
||||
|
||||
- **The substrate** is one castle service (`supabase`, the `supabase-substrate`
|
||||
repo) running self-hosted Supabase via the `compose` runner. It is shared by
|
||||
every supabase app. Stand it up once (see that repo's README).
|
||||
- **Each app** is a directory of `migrations/` + `functions/` + `public/` that
|
||||
deploys onto the substrate. Its rows/blobs live on the substrate; everything
|
||||
else rebuilds from git.
|
||||
|
||||
Apps are isolated on the shared instance by **table prefix + RLS** in the shared
|
||||
`public` schema (and Storage buckets), under **one identity pool** — correct for a
|
||||
single-operator datalake. Substrate-per-app is deliberately not supported: ~14
|
||||
containers per app doesn't scale to "lots of small ideas," and a DB-backed app is
|
||||
a pet either way.
|
||||
|
||||
## Stack
|
||||
|
||||
| Layer | Choice |
|
||||
|-------|--------|
|
||||
| **Backend** | Self-hosted Supabase (Postgres + PostgREST + GoTrue + Storage + Realtime + Edge Functions) |
|
||||
| **Client** | `@supabase/supabase-js` (from a CDN; no build step required) |
|
||||
| **Migrations** | Ordered SQL files, applied by a versioned idempotent runner |
|
||||
| **Functions** | Deno edge functions |
|
||||
| **UI** | Static HTML/JS in `public/`, served in place by the gateway |
|
||||
| **Auth** | GoTrue + Postgres Row-Level Security |
|
||||
|
||||
## Project layout
|
||||
|
||||
```
|
||||
my-app/
|
||||
├── supabase.app.yaml # substrate wiring + auth policy (public/private/shared)
|
||||
├── migrations/
|
||||
│ └── 0001_init.sql # versioned, idempotent, forward-only
|
||||
├── functions/
|
||||
│ └── hello/index.ts # deno edge function
|
||||
├── public/
|
||||
│ ├── index.html # static UI — talks to the substrate via supabase-js
|
||||
│ └── config.js # SUPABASE_URL + anon key (public-safe)
|
||||
└── CLAUDE.md
|
||||
```
|
||||
|
||||
Registered as a `behavior: frontend` program with `build.outputs: [public]`, so the
|
||||
gateway serves `public/` in place at `/my-app/` — no service, no process.
|
||||
|
||||
## supabase.app.yaml
|
||||
|
||||
```yaml
|
||||
name: my-app
|
||||
substrate: supabase # the shared castle service this app deploys against
|
||||
auth: public # public | private | shared: [handles]
|
||||
table_prefix: my_app_
|
||||
```
|
||||
|
||||
## Migrations
|
||||
|
||||
`migrations/*.sql` are **numbered, forward-only, and idempotent**. `castle program
|
||||
build my-app` runs the versioned migration runner: it ensures a
|
||||
`public.schema_migrations` table, reads applied versions, and applies only the
|
||||
**unapplied** files (in filename order), each in a single transaction with its
|
||||
version-insert — so a failed migration records nothing and the next build retries
|
||||
it. Never edit an applied migration; add a new numbered file.
|
||||
|
||||
```sql
|
||||
-- migrations/0001_init.sql
|
||||
create table if not exists public.my_app_entries (
|
||||
id bigint generated always as identity primary key,
|
||||
message text not null,
|
||||
created_at timestamptz not null default now()
|
||||
);
|
||||
alter table public.my_app_entries enable row level security;
|
||||
create policy "my_app_read" on public.my_app_entries for select using (true);
|
||||
create policy "my_app_write" on public.my_app_entries for insert with check (true);
|
||||
```
|
||||
|
||||
The runner connects via `SUPABASE_DB_URL`, or builds one from the generated
|
||||
`SUPABASE_POSTGRES_PASSWORD` secret against `localhost:5432`. `psql` must be on
|
||||
PATH; a missing URL or client fails loud with guidance.
|
||||
|
||||
## Auth, RLS & the three privacy layers
|
||||
|
||||
`auth:` in `supabase.app.yaml` declares the policy. **RLS protects rows, but it is
|
||||
not sufficient on its own** — a leaked URL to a `private` app would still serve the
|
||||
static shell and any known Storage URL. So a non-public app must enforce privacy at
|
||||
**three** layers:
|
||||
|
||||
1. **Rows** — RLS locks rows to `auth.uid()` (owner) or a shared allowlist.
|
||||
2. **Static shell** — an auth check gates serving `public/` (unauthenticated
|
||||
requests get login/denied, never the app).
|
||||
3. **Storage** — served via short-lived **signed URLs**, never long-lived public
|
||||
object URLs.
|
||||
|
||||
A `public` app intentionally skips shell/Storage gating (anon read/write, still
|
||||
row-gated).
|
||||
|
||||
## Edge functions
|
||||
|
||||
`functions/<name>/index.ts` are deno functions deployed to the substrate's
|
||||
edge-runtime. Privileged work (anything needing the `service_role` key) happens
|
||||
here, server-side — **never** browser-direct. The app frontend calls the function;
|
||||
the function holds credentials and can meter usage.
|
||||
|
||||
## Gateway & secure context
|
||||
|
||||
A `public` app is fine on the gateway's HTTP static route at `/my-app/`. An app
|
||||
that uses **auth or WebCrypto** needs a **secure context**, so give it its own
|
||||
HTTPS host route instead — `proxy.caddy.host: my-app.lan` with `gateway.tls:
|
||||
internal` — exactly like the substrate itself (`supabase.lan`). See the "HTTPS for
|
||||
host routes" section of @docs/registry.md.
|
||||
|
||||
## Commands
|
||||
|
||||
```bash
|
||||
castle program create my-app --stack supabase --description "..." # scaffold + register
|
||||
castle program build my-app # apply unapplied migrations to the substrate
|
||||
castle program test my-app # deno test over functions/ (if deno present)
|
||||
castle deploy && castle gateway reload # serve the static UI at /my-app/
|
||||
```
|
||||
|
||||
## Scaffolding
|
||||
|
||||
`castle program create --stack supabase` generates the full layout above and
|
||||
registers the program as a static frontend. Set the anon key in `public/config.js`
|
||||
(`cat ~/.castle/secrets/SUPABASE_ANON_KEY`), edit your migrations, and build.
|
||||
|
||||
See @docs/registry.md for the `compose` runner, the substrate service definition,
|
||||
and the full registry reference. The substrate itself lives in the
|
||||
`supabase-substrate` repo (vendored, pinned self-hosted Supabase).
|
||||
Reference in New Issue
Block a user