pnpm e2e:avatar is now an alias of pnpm db:sandbox avatar-e2e and the DEV script scripts/avatar-e2e.sh is removed; the suite fails on any target but the sandbox gateway and database; an occupied port 57800 stops the run before anything starts. The sandbox replaces the seed accounts' DEV password by a per-session secret.
203 lines
12 KiB
Markdown
203 lines
12 KiB
Markdown
# 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` `:54325` (gateway) | 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/db-sandbox.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. 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 | published by the CLI; RLS, policies and the anon key protect the data; the service key never reaches a browser |
|
|
| Mailpit for other devices | 54325 | open **with credentials** | the DEV gateway (nginx, `faunosteo_dev_gateway`, `pnpm dev:gateway`) on `<DEV host>:54325`, HTTP basic auth: user `dev`, generated password in `docker/dev-gateway/mailpit-password` (never committed) |
|
|
| Mailpit raw | 54324 | **closed** | host firewall rule on the LAN interface (§3.2) |
|
|
| Studio | 54323 | **closed** | host firewall rule; from another device: SSH tunnel (§3.4) |
|
|
| PostgreSQL | 54322 | **closed** | host firewall rule; the CLI and the tests use it on the host |
|
|
| Worker | none | — | internal, Supabase compose network, read-only, no capability |
|
|
| Production build for the R4 recettes (`scripts/browser/serve.mjs`) | 4173 | **closed** by default; open only during a device recette | static build behind the DEPLOY CSP, empty `env.js`, bound to the one DEV address (never a wildcard, refused by the script); the owner opens it for the session, `sudo ufw allow in on enp89s0 from 192.168.1.0/24 to any port 4173 proto tcp comment 'faunosteo recette R4'`, and deletes that rule afterwards (`sudo ufw status numbered`, then `sudo ufw delete <n>`) |
|
|
| PostgREST, GoTrue, Storage, pg-meta | none | — | behind Kong |
|
|
|
|
### 3.1 Why a host firewall is required
|
|
|
|
The Supabase CLI 2.120 binds every published port on `0.0.0.0` and `[::]`
|
|
explicitly ("All services bind to 0.0.0.0" at start) and has no bind option:
|
|
the rootless daemon's default address (`daemon.json` `"ip"`) does not apply
|
|
to it (tried 2026-10-13). No user-level setting can close PostgreSQL, Studio
|
|
or the raw Mailpit port. With Docker rootless the published ports are plain
|
|
listening sockets of the rootlesskit process in the host network namespace,
|
|
so host INPUT rules apply to them (unlike rootful Docker, whose DNAT bypasses
|
|
UFW). The rules below are scoped to the LAN interface: loopback, the Docker
|
|
networks and every other port of the machine are untouched.
|
|
|
|
### 3.2 Firewall rules (owner action, sudo)
|
|
|
|
```bash
|
|
sudo ufw status verbose # note whether it is active and its default policy
|
|
|
|
# A. UFW inactive (keeps today's behaviour for every other port, adds three refusals)
|
|
sudo ufw default allow incoming
|
|
sudo ufw default allow outgoing
|
|
sudo ufw deny in on enp89s0 to any port 54322 proto tcp comment 'faunosteo dev postgres'
|
|
sudo ufw deny in on enp89s0 to any port 54323 proto tcp comment 'faunosteo dev studio'
|
|
sudo ufw deny in on enp89s0 to any port 54324 proto tcp comment 'faunosteo dev mailpit raw'
|
|
sudo ufw enable
|
|
|
|
# B. UFW already active with "deny (incoming)": the three ports are already refused
|
|
# unless a rule opens them; open what the devices need, from the private subnet only
|
|
sudo ufw allow in on enp89s0 from 192.168.1.0/24 to any port 5173,54321,54325 proto tcp comment 'faunosteo dev browser'
|
|
```
|
|
|
|
`enp89s0` and `192.168.1.0/24` are this machine's interface and subnet
|
|
(`ip -4 -o addr show`); adapt them if they change. Rules cover IPv4 and IPv6
|
|
(UFW `IPV6=yes`, the Ubuntu default).
|
|
|
|
Rollback:
|
|
|
|
```bash
|
|
sudo ufw status numbered # then, for each faunosteo rule, highest number first:
|
|
sudo ufw delete <n>
|
|
sudo ufw disable # only in case A, if UFW was inactive before
|
|
```
|
|
|
|
Impact: case A changes nothing for SSH, RDP or any other service (default
|
|
allow incoming); only the three ports stop answering on the LAN interface.
|
|
Case B adds an allow rule limited to the subnet.
|
|
|
|
### 3.3 Check
|
|
|
|
`pnpm dev:net-check`:
|
|
|
|
1. probes the allowed surfaces from a throwaway container on its own Docker
|
|
network (app 200, API health 200, REST without key 401, Mailpit gateway
|
|
401 without and 200 with the credentials);
|
|
2. prints the refusal checks to run **from another device** (`nc -zv -w 3
|
|
<host> 54322 / 54323 / 54324` must fail, `54321` must succeed): with Docker
|
|
rootless a container's traffic to the host's own address is delivered
|
|
locally and never crosses the LAN interface, so this machine cannot see its
|
|
own LAN firewall;
|
|
3. lists the published ports of the stack.
|
|
|
|
### 3.4 Studio from another device
|
|
|
|
```bash
|
|
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` (Kong), which the
|
|
device reaches directly.
|
|
|
|
### 3.5 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.
|
|
|
|
### 3.6 The API port 54321 and the stack's keys (checked 2026-10-24)
|
|
|
|
Measured on the host, no secret printed: `supabase/config.toml` sets no `jwt_secret` and no
|
|
signing keys, so the stack signs with the Supabase CLI's **public default** JWT secret and its
|
|
`service_role` key is the public demo key (`iss: supabase-demo`). Port 54321 is open to the LAN by
|
|
design (table above): any device of the private network that knows those public values can call
|
|
the API as `service_role`, past every RLS policy, on DEV data. Nothing of production is involved.
|
|
This is an owner decision (no automatic change): give the stack its own secret (a `jwt_secret` /
|
|
signing keys read with `env()` from a git-ignored file, then `pnpm db:reset` and new keys in
|
|
`.env.worker`), or narrow the 54321 allow rule to the test devices' addresses.
|
|
|
|
What the UFW listing alone does not prove for 54321, and how to check it (owner, by hand):
|
|
|
|
```bash
|
|
ss -ltnp 'sport = :54321' # who listens, on which address (0.0.0.0 / [::] expected)
|
|
sudo ufw status verbose # default incoming policy + any rule naming 54321
|
|
docker info -f '{{.SecurityOptions}}' # "rootless" expected: published ports are host sockets, UFW applies
|
|
sudo iptables -S DOCKER-USER 2>/dev/null # rootful Docker only: DNAT bypasses UFW, rules belong here
|
|
nc -zv -w 3 <DEV host> 54321 # from ANOTHER device: succeeds today (open by design)
|
|
nc -zv -w 3 <DEV host> 54322 # from another device: must fail (54323, 54324 too)
|
|
```
|
|
|
|
A DENY on 54322 to 54324 is effective only if the daemon is rootless (§3.1) and the probe from
|
|
another device fails; this machine cannot test its own LAN firewall (§3.3).
|
|
|
|
## 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` (part 1 all OK), then the part 2 commands from the
|
|
computer. 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>:54325` (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), `http://<host>:54324` (raw Mailpit) and
|
|
anything on `:54322` (PostgreSQL).
|