Files
faunosteo/docs/development/ENVIRONMENTS.md
T
bchanot 3e48b0d848 chore(workspace): DEV least-privilege exposure — nginx DEV gateway (API on the LAN, Mailpit behind basic auth), network check from a distinct origin, loopback default for the rootless daemon documented
The Supabase CLI publishes 54321-54324 on every interface with no bind
option. Design: the rootless daemon binds published ports on loopback by
default (~/.config/docker/daemon.json {"ip":"127.0.0.1"}, owner action,
not applied), and the DEV gateway (Compose service dev-gateway, profile
dev, container faunosteo_dev_gateway) re-publishes only the API (Kong) and
Mailpit behind HTTP basic auth on FAUNOSTEO_DEV_HOST; Studio and PostgreSQL
stay loopback (SSH tunnel for Studio). pnpm dev:gateway generates the Mailpit
credentials (gitignored; htpasswd 644 because the rootless container user
cannot read a 600 file, hash only). pnpm dev:net-check probes from a
throwaway container on its own Docker network: app, API health, REST 401,
Mailpit 401/200, PostgreSQL and Studio closed. Gateway proven on alternate
ports (health 200, password login 200, Mailpit 401 / 200).
2026-10-13 22:38:40 +02:00

8.0 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. Exposure on the private network: least privilege

Target (owner decision 2026-10-13): the browser surfaces are reachable from the LAN, the administration tools and the database are not.

Service Port LAN How it is enforced
Application (Vite) 5173 open Vite listens on every interface (server.host: true); dev build, anon key only
Supabase API (Kong: Auth, PostgREST, Storage) 54321 open the DEV gateway re-publishes it on <DEV host>:54321; RLS, policies and the anon key protect the data; the service key never reaches a browser
Mailpit (DEV mails) 54324 open with credentials the DEV gateway re-publishes it behind HTTP basic auth (user dev, generated password in docker/dev-gateway/mailpit-password, never committed)
Studio 54323 closed loopback only; from another device: SSH tunnel (below)
PostgreSQL 54322 closed loopback only; tests and the CLI use 127.0.0.1:54322 on the host
Worker none — internal, Supabase compose network, read-only, no capability
PostgREST, GoTrue, Storage, pg-meta none — behind Kong

3.1 Mechanism (no privileges, no firewall)

The Supabase CLI publishes its ports with no host address and offers no bind option, so Docker uses the daemon's default address. Two pieces:

  1. The rootless daemon binds published ports on loopback by default: ~/.config/docker/daemon.json = {"ip": "127.0.0.1"} (user-level file of Docker rootless, no sudo). Every port published without an explicit address, the CLI's included, then listens on 127.0.0.1 only.
  2. The DEV gateway (docker/dev-gateway/nginx.conf, Compose service dev-gateway, profile dev, container faunosteo_dev_gateway): an nginx on the Supabase network, published on <FAUNOSTEO_DEV_HOST>:54321 (proxy to Kong) and <FAUNOSTEO_DEV_HOST>:54324 (proxy to Mailpit behind basic auth). pnpm dev:gateway starts it (and generates the Mailpit password on first use), pnpm dev:gateway:stop stops it.

Why not UFW: with Docker rootless, published ports are ordinary listening sockets of the rootlesskit process in the host network namespace, so host INPUT rules would apply (unlike rootful Docker, whose DNAT bypasses UFW); but a firewall rule needs sudo, and binding to loopback removes the listener instead of filtering it. A host firewall stays a possible second layer, the owner's decision.

3.2 Check

pnpm dev:net-check probes from a throwaway container on its own Docker network (a distinct origin that reaches the host by its LAN address only): app 200, API health 200, REST without key 401, Mailpit 401 without and 200 with the credentials, PostgreSQL and Studio closed; it prints the published ports of the stack. Exit 1 on any deviation.

3.3 Studio from another device

ssh -L 54323:127.0.0.1:54323 <user>@<DEV host>    # then http://localhost:54323 on that device

Studio's own API calls go to http://<DEV host>:54321 (the gateway), which the device reaches directly.

3.4 HTTP on a private address

The auth flows (PKCE, session in localStorage, no cookie) work over HTTP. What would not: browser features that need a secure context on a non-loopback origin (camera capture, geolocation, some clipboard and service-worker features) and OAuth providers that refuse 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)

On the Ubuntu machine: pnpm db:start, pnpm dev:gateway, the worker (docker compose --profile worker up -d worker), pnpm dev, then pnpm dev:net-check (all OK). From the computer, then 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 (user dev, password: cat docker/dev-gateway/mailpit-password on the Ubuntu machine), the link opened in the same browser as the form. Refused from the device: http://<host>:54323 (Studio) and anything on :54322 (PostgreSQL).