Files
faunosteo/docs/development/ENVIRONMENTS.md
T

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).