Files
faunosteo/docs/development/ENVIRONMENTS.md
T
bchanot dd4c35c061 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).
2026-10-13 22:06:25 +02:00

6.2 KiB

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.

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.