chore(workspace): DEV origin on the private network — scripts/dev-env.sh (FAUNOSTEO_DEV_HOST detected or set), Supabase CLI wrapper, pnpm dev on the LAN address, config.toml URLs via env(); ENVIRONMENTS.md (identity Faunosteo / faunosteo.com, DEV / STAGING / PROD, exposure table, owner procedure)
The owner tests from other devices of the private network: every test surface is addressed by the machine's LAN address, never 127.0.0.1 or localhost, never hard-coded. scripts/dev-env.sh decides the host once (hostname -I, FAUNOSTEO_DEV_HOST override, production hosts refused); scripts/supabase.sh exports it for every CLI call (pnpm db:*, pnpm supabase) because config.toml now reads api.external_url (mail links), auth.site_url and studio.api_url with env(); scripts/dev.sh = pnpm dev on that origin, pnpm dev:offline keeps the local tool alone; dev-lan.sh removed. Verified: GoTrue API_EXTERNAL_URL and Studio SUPABASE_PUBLIC_URL on the LAN address, a signup mail linking to http://<lan>:54321/auth/v1/verify, the four published ports answering from a separate Docker network, and the 10-step procedure in headless Chromium at the LAN origin with every request URL audited (no 127.0.0.1 / localhost).
This commit is contained in:
1 parent
f5865f073f
commit
dd4c35c061
14 files changed
+228
-41
No files matched your search
@@ -0,0 +1,107 @@
|
||||
# Environments: DEV, STAGING, PROD
|
||||
|
||||
Owner decisions of 2026-10-13 (BDR-049). Product identity: **Faunosteo**,
|
||||
official domain **https://faunosteo.com** (the SaaS, the application, the
|
||||
public site and its services; the current logo, palette and validated
|
||||
mockups under `docs/design/` stay). No other brand name is proposed again.
|
||||
|
||||
| Environment | Where | Data | Reachable from |
|
||||
|---|---|---|---|
|
||||
| **DEV** | the self-hosted Ubuntu development machine (native Rust via rustup/Cargo, Node/Vite, Docker rootless for the Supabase stack, the worker and the images) | test data, fictitious accounts, local Supabase, local worker | the owner's other devices on the private network (computer, phone): the DEV origin below |
|
||||
| **STAGING** | `staging.faunosteo.com`, planned, not created | its own database, storage, secrets, accounts | later |
|
||||
| **PROD** | `https://faunosteo.com`, separate VPS | real data | the Internet; the site present today is preserved until an explicit migration decision |
|
||||
|
||||
Isolation: each environment keeps its own PostgreSQL, Storage, secrets,
|
||||
accounts, OAuth client ids, payments, e-mails, professional files and
|
||||
bilans. Production data is never copied into DEV. A merge into `develop`
|
||||
never deploys anything; no CI/CD runs on the forge today (workflow files are
|
||||
prepared material), no runner, registry or secret exists.
|
||||
|
||||
## 1. Rule: every test surface of DEV is reachable on the private network
|
||||
|
||||
The owner does not test on the Ubuntu machine itself. Whatever a browser or
|
||||
a phone needs for a test is addressed by the machine's LAN address (or a
|
||||
private DNS name), never by `127.0.0.1` or `localhost` of the server, and
|
||||
never hard-coded in the sources.
|
||||
|
||||
## 2. The DEV origin, in one place
|
||||
|
||||
`scripts/dev-env.sh` decides the DEV host once:
|
||||
|
||||
| Variable | Default | Meaning |
|
||||
|---|---|---|
|
||||
| `FAUNOSTEO_DEV_HOST` | the first non-loopback IPv4 of the host (`hostname -I`) | address or name of this machine on the private network; `127.0.0.1` for a host-only session; a production host is refused |
|
||||
| derived | `FAUNOSTEO_DEV_API_URL` `http://<host>:54321`, `FAUNOSTEO_DEV_SITE_URL` `http://<host>:5173`, `FAUNOSTEO_DEV_API_ORIGIN`, `FAUNOSTEO_DEV_STUDIO_URL` `:54323`, `FAUNOSTEO_DEV_MAILPIT_URL` `:54324` | read by `supabase/config.toml` (`env()`) and by the Vite dev server |
|
||||
|
||||
Consumers: `scripts/supabase.sh` (every CLI call: `pnpm supabase …`,
|
||||
`pnpm db:start|stop|reset|test|types`), `scripts/dev.sh` (`pnpm dev`),
|
||||
`scripts/avatar-e2e.sh`. The address changes with `FAUNOSTEO_DEV_HOST=…`
|
||||
in front of the command, without touching a source file. Calling the CLI
|
||||
binary directly (`node_modules/.bin/supabase start`) leaves the literal
|
||||
`env(...)` text in the services: always go through `pnpm`.
|
||||
|
||||
```bash
|
||||
pnpm db:start # stack on the DEV origin; mails link to http://<host>:54321/auth/v1/...
|
||||
pnpm worker:image && docker compose --profile worker up -d worker # .env.worker: DEPLOY.md
|
||||
pnpm dev # http://<host>:5173, Supabase by the DEV origin, HMR over the LAN
|
||||
pnpm dev:offline # the local tool without backend (host:5173 too)
|
||||
FAUNOSTEO_DEV_HOST=10.0.0.5 pnpm db:start # another address: restart the stack, then pnpm dev again
|
||||
```
|
||||
|
||||
`supabase/config.toml` reads: `api.external_url` (the address GoTrue writes
|
||||
into confirmation and recovery mails), `auth.site_url`, `studio.api_url`;
|
||||
`auth.additional_redirect_urls` allows every private-network host on `:5173`
|
||||
(`192.168.*.*`, `10.*.*.*`, `172.16.*.*`) plus the host-only forms, so PKCE
|
||||
links return to the origin the browser used.
|
||||
|
||||
## 3. What listens where (DEV, measured 2026-10-13)
|
||||
|
||||
The Supabase CLI publishes its ports on every interface (`0.0.0.0`, no bind
|
||||
option); Vite listens on every interface (`server.host: true`).
|
||||
|
||||
| Service | Port | Interface | Needed by the remote browser | Protection |
|
||||
|---|---|---|---|---|
|
||||
| Application (Vite) | 5173 | all | yes | none (dev build, anon key only) |
|
||||
| Supabase API (Kong: Auth, PostgREST, Storage) | 54321 | all | yes | RLS, policies, the anon key; the service key never reaches a browser |
|
||||
| Studio | 54323 | all | useful for inspection, not for the flows | **none**: full database access to anyone on the LAN |
|
||||
| Mailpit | 54324 | all | yes for sign-up and recovery mails | **none**: every DEV mail readable on the LAN |
|
||||
| PostgreSQL | 54322 | all | no | password `postgres`: **should not be reachable from the LAN** |
|
||||
| Worker | none | — | no | internal only (Supabase compose network, read-only, no capability) |
|
||||
| PostgREST, GoTrue, Storage, pg-meta | none | — | behind Kong | — |
|
||||
|
||||
The firewall state of the host could not be read without privileges. The
|
||||
proposal for the owner (not applied): a host firewall keeping 54322 on
|
||||
loopback only, and 54323 / 54324 restricted to the private subnet
|
||||
(`192.168.1.0/24`); 5173 and 54321 open to that subnet. Nothing is exposed to
|
||||
the Internet by this repository; the box, the router and any public
|
||||
forwarding stay untouched.
|
||||
|
||||
HTTP on a private address: the auth flows (PKCE, cookies-free session in
|
||||
localStorage) work; what does not is any browser feature that needs a
|
||||
secure context on a non-loopback origin (camera, geolocation, some
|
||||
clipboard and service-worker features) and any OAuth provider that refuses
|
||||
`http://` redirect URIs. When one of those lands, the answer is a private
|
||||
HTTPS origin (local CA or a private name with a certificate), never the
|
||||
production domain.
|
||||
|
||||
## 4. Procedure from another device (owner validation)
|
||||
|
||||
Stack and worker started on the Ubuntu machine (`pnpm db:start`, the worker
|
||||
container, `pnpm dev`), then from the computer, and again from the phone on
|
||||
the same network:
|
||||
|
||||
1. `http://<host>:5173/` opens the Faunosteo home.
|
||||
2. `/login` shows the sign-in card.
|
||||
3. `alice@faunosteo.local` / `LocalDev-only-password-1` signs in.
|
||||
4. `/app` shows the dashboard.
|
||||
5. Mon compte opens.
|
||||
6. Modifier la photo with a photo of the device → preview → Enregistrer.
|
||||
7. "Traitement en cours…" then the photo (the worker's log shows
|
||||
`job_completed`).
|
||||
8. Reload: the photo is still there, in the circle, the sidebar / drawer and
|
||||
the top bar.
|
||||
9. Se déconnecter returns to the home; `/app` redirects to `/login`.
|
||||
10. Same steps on the phone; no horizontal scroll.
|
||||
|
||||
A sign-up from the device: Mailpit at `http://<host>:54324`, the link opened
|
||||
in the same browser as the form.
|
||||
@@ -99,9 +99,8 @@ holding a platform role.
|
||||
## 5. Manual validation (local stack)
|
||||
|
||||
```bash
|
||||
pnpm db:start # prints API URL + anon key; Mailpit at http://127.0.0.1:54324
|
||||
VITE_SUPABASE_URL=http://127.0.0.1:54321 VITE_SUPABASE_ANON_KEY=<anon key> \
|
||||
VITE_AUTH_PROVIDERS=google pnpm dev
|
||||
pnpm db:start # stack on the DEV origin (LAN address); Mailpit at http://<host>:54324
|
||||
VITE_AUTH_PROVIDERS=google pnpm dev # http://<host>:5173 from any device of the private network (ENVIRONMENTS.md)
|
||||
```
|
||||
|
||||
1. `/app` while signed out → `/login?next=%2Fapp`. The login card shows a
|
||||
|
||||
@@ -55,6 +55,14 @@ like every other tool. Never install it globally.
|
||||
|
||||
## 3. Start, stop, reset
|
||||
|
||||
Every CLI call goes through `scripts/supabase.sh` (`pnpm db:*`, `pnpm supabase
|
||||
<args>`): it exports the DEV origin that `config.toml` reads with `env()`
|
||||
(`api.external_url`, `auth.site_url`, `studio.api_url`). A direct
|
||||
`node_modules/.bin/supabase start` would leave the literal `env(...)` text in
|
||||
GoTrue's mail links. Published ports (all interfaces): API 54321, PostgreSQL
|
||||
54322, Studio 54323, Mailpit 54324 (`ENVIRONMENTS.md` §3 for what each one
|
||||
exposes).
|
||||
|
||||
```bash
|
||||
pnpm db:start # supabase start: pulls images, applies migrations + seed, prints URLs and keys
|
||||
pnpm db:stop # supabase stop (keeps the volume)
|
||||
@@ -246,14 +254,19 @@ audit rows (bootstrap with null actor, grant by the owner).
|
||||
|
||||
## 9. Wiring the app
|
||||
|
||||
`.env` (Docker) or `apps/app/.env.local` (Vite dev):
|
||||
Development: `pnpm dev` (`scripts/dev.sh`) sets `VITE_SUPABASE_URL` to the DEV
|
||||
origin (`http://<FAUNOSTEO_DEV_HOST>:54321`, the LAN address of the machine:
|
||||
`ENVIRONMENTS.md` §2) and the anon key from `supabase status`; the app is
|
||||
served on `http://<host>:5173` for every device of the private network.
|
||||
`pnpm dev:offline` runs the local tool without backend. Docker deployments use
|
||||
`.env`:
|
||||
|
||||
```bash
|
||||
APP_SUPABASE_URL=http://127.0.0.1:54321 # VITE_SUPABASE_URL in dev
|
||||
APP_SUPABASE_ANON_KEY=<anon key> # VITE_SUPABASE_ANON_KEY in dev
|
||||
APP_SUPABASE_URL=<Supabase origin reachable by the browser>
|
||||
APP_SUPABASE_ANON_KEY=<anon key> # public by design
|
||||
```
|
||||
|
||||
Both empty (the default) keeps the app in its local-only mode:
|
||||
Both empty keeps the app in its local-only mode:
|
||||
`getSupabaseClient()` returns null, the auth screens show an "unavailable"
|
||||
notice and `/app` redirects to `/login`. `APP_AUTH_PROVIDERS` /
|
||||
`VITE_AUTH_PROVIDERS` (`google,apple`) lists the OAuth buttons to show.
|
||||
|
||||
@@ -85,7 +85,9 @@ works as `corepack pnpm <cmd>`.
|
||||
| Command | Does |
|
||||
|---|---|
|
||||
| `pnpm install` | installs the whole workspace from the lockfile |
|
||||
| `pnpm dev` | Vite dev server of `apps/app` on :5173 |
|
||||
| `pnpm dev` | Vite dev server of `apps/app` on `http://<FAUNOSTEO_DEV_HOST>:5173`, wired to the local Supabase stack by the DEV origin (`scripts/dev.sh`, `ENVIRONMENTS.md`) |
|
||||
| `pnpm dev:offline` | the same server without backend (local tool only) |
|
||||
| `pnpm supabase <args>` / `pnpm db:*` | the Supabase CLI with the DEV origin exported (`scripts/supabase.sh`) |
|
||||
| `pnpm preview` | serves `apps/app/dist` on :4173 |
|
||||
| `pnpm typecheck` | `tsc --noEmit` in every package |
|
||||
| `pnpm test:run` | vitest once in every package |
|
||||
|
||||
Reference in new issue
Block a user