Paul Payne
770574f575
CaddySpec had only `enable` left (path_prefix/host removed; extra_snippets was
unused), so `proxy: { caddy: {} }` was three levels of nesting for a checkbox —
and it invited drift (supabase silently reverted to proxy.caddy.host). Replace it
with a plain `ServiceSpec.proxy: bool`.
- Model: remove ProxySpec/CaddySpec; `proxy: bool = False`. Readers simplified to
`bool(svc.proxy)` (generator, castle-api summaries, CLI info).
- CLI create / dashboard editor + create form: write `proxy: true` / a checkbox.
- Configs migrated to `proxy: true` (and supabase's stale proxy.caddy.host block
removed).
- Docs (registry, dns-and-tls, design, stack guides) + tests/fixtures updated;
also fixed lingering path-model staleness in the stack guides.
145 lines
6.3 KiB
Markdown
145 lines
6.3 KiB
Markdown
# 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 supabase app is a `frontend` program (its `public/` is served in place), so the
|
|
gateway serves it at its own subdomain `<name>.<gateway.domain>`. With
|
|
`gateway.tls: acme` that subdomain is HTTPS — a **secure context**, which apps
|
|
using **auth or WebCrypto** require — with no private CA to install. (The substrate
|
|
service itself is likewise at `supabase.<gateway.domain>`.) See
|
|
@docs/dns-and-tls.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).
|