caterium-app/ops/supabase-selfhosted/README.md

# Self-hosted Supabase for Caterium (Timeweb Cloud Server)

Target: `https://api.caterium.ru` — replaces `https://cksuehzcimitsxmeloes.supabase.co`.

This directory is deployable as-is on a fresh Ubuntu 22.04/24.04 **Timeweb Cloud Server (VPS with root)**.
It CANNOT run on the existing `timeweb-caterium` shared-hosting SSH account (`ci503744@vh470.timeweb.ru`) —
that account has no root, sudo is disabled (`no_new_privileges`), and there is no Docker daemon. Shared
hosting is fine for serving the static frontend (`public/`) but architecturally cannot host Postgres/Kong/
GoTrue/PostgREST/Realtime/Storage containers.

## What's here

| File | Purpose |
|---|---|
| `bootstrap-server.sh` | Run once (as root) on a fresh Cloud Server. Installs Docker, Docker Compose plugin, Caddy, ufw rules, clones this config, brings the stack up. |
| `docker-compose.yml` | The Supabase stack: db, kong, auth, rest, realtime, storage, meta, functions, studio, imgproxy. |
| `.env.example` | Every secret/setting the stack needs. Copy to `.env`, fill in, `chmod 600`. Never commit the real `.env`. |
| `volumes/api/kong.yml` | Kong declarative routing for `/rest/v1`, `/auth/v1`, `/storage/v1`, `/realtime/v1`, `/functions/v1`. |
| `volumes/db/init/` | One-time SQL run by the Postgres container on first boot (roles, `pg_cron`/extensions, JWT hook wiring). |
| `Caddyfile` | Reverse proxy for `api.caterium.ru`: automatic HTTPS (Let's Encrypt), WebSocket upgrade for Realtime, large upload limits for Storage, header forwarding. |
| `scripts/01-dump-old.sh` | Runs against the OLD Supabase project. Produces `roles.sql`, `schema.sql`, `data.sql` via `supabase db dump`. |
| `scripts/02-restore-new.sh` | Restores those dumps into the new self-hosted Postgres via `psql`. |
| `scripts/03-verify-counts.sql` | Row-count comparison old vs new (auth.users, orders, order_items, clients, catalog_items, storage.objects). |
| `scripts/04-deploy-edge-function.sh` | Copies `supabase/functions/caterium-create-employee` and `caterium-platform-auth-admin` into the running `functions` container's mounted volume and reloads it. |
| `scripts/05-storage-sync.sh` | Copies Storage objects (binary files) from the old project's Storage S3-compatible/API to the new bucket, preserving paths. |

## Order of operations

1. Provision the Cloud Server (see "Manual step required" below). Point DNS `api.caterium.ru` A-record at its IP.
2. `scp` this whole `ops/supabase-selfhosted/` directory to the server, or `git clone` the repo there.
3. `sudo bash bootstrap-server.sh` — installs Docker/Caddy, brings up the stack with placeholder secrets.
4. Fill in real secrets in `.env` (JWT secret, DB password, SMTP, dashboard user/pass) — generate fresh ones with
   `openssl rand -base64 32` unless told to reuse the old JWT secret. `docker compose up -d` again to apply.
5. Run `scripts/01-dump-old.sh` (needs `OLD_DB_URL` — the old project's Postgres connection string with password,
   from Supabase Dashboard → Project Settings → Database → Connection string → URI, "session pooler" disabled,
   direct connection).
6. Run `scripts/02-restore-new.sh` against the new stack's `db` container.
7. Run `scripts/03-verify-counts.sql` old vs new and compare against the expected counts (14 / 11 / 53 / 52 / 460 / 18).
8. Run `scripts/05-storage-sync.sh` to copy the 18 Storage objects and their metadata/policies.
9. Run `scripts/04-deploy-edge-function.sh` to bring `caterium-create-employee` online, verify with a test call.
10. Only after 5-9 pass: flip `DEFAULT_SUPABASE_URL` in `public/app-runtime.js`, ship the `localStorage` migration
    shim (see `ops/supabase-selfhosted/frontend-cutover.md`), commit to `main`, let CI promote to `production`.

## Manual step required right now (nothing beyond this is blocked)

I do not have a Timeweb Cloud API token or root SSH credentials to any Timeweb **Cloud Server** (VPS) — only to
the existing shared-hosting account used for the static frontend, which cannot run Docker. To unblock steps 1-10:

**Either**
- **(A)** In the Timeweb Cloud panel (https://timeweb.cloud/), create a Cloud Server: Ubuntu 22.04, minimum
  2 vCPU / 4 GB RAM / 50 GB NVMe (recommended: 4 vCPU / 8 GB for headroom), public IPv4, and add my SSH public
  key as an authorized key OR give me the root password so I can add my own key. Then tell me the server's IP.
- **(B)** Generate a Timeweb Cloud API token (panel → API → "Токены доступа" → create token with Cloud Servers
  write scope) and give it to me; I will provision the server via the Timeweb API myself
  (`POST https://api.timeweb.cloud/api/v1/servers`).

Whichever you pick, also add a DNS A-record: `api.caterium.ru` → the new server's IP (in whatever DNS provider
currently hosts `caterium.ru`'s zone — outside Cloudflare per your instruction not to put Cloudflare in the
backend path).

**Separately**, to actually migrate the data (step 5), I need the OLD Supabase project's direct Postgres
connection string with the real database password (Supabase Dashboard → Project Settings → Database →
Connection string → URI, non-pooled). I cannot retrieve this myself — it's not in any file on this machine and
I won't ask you to paste a password into a browser form on my behalf. Paste the connection string here in chat,
or set it as `OLD_DB_URL` in the shell before I run `scripts/01-dump-old.sh` for you. If you'd rather I don't
see the raw password in chat, run `scripts/01-dump-old.sh` yourself with `OLD_DB_URL` exported and send me the
three resulting `.sql` files (or their location on this machine) and I'll take it from there.

I will use a **freshly generated JWT secret** for the new stack (per your instruction that this is acceptable) —
existing sessions will be invalidated and all 14 users will need to log in once more with their existing
email+password (which migrate unchanged, since `auth.users.encrypted_password` is copied byte-for-byte from
the dump).