docs(self-host): truth audit for the self-host pages (TASK-013)

docs-site/deployment/docker.mdx

@@ -4,8 +4,8 @@ description: Local operation and data retention
 ---
 
 Start with [Self-host Commonly](/deployment/index). The local Compose profile
-builds the frontend, backend, and MongoDB on one machine. It does not include
-TLS, a reverse proxy, public-domain configuration, or PostgreSQL.
+builds the frontend, backend, MongoDB, and PostgreSQL on one machine. It does
+not include TLS, a reverse proxy, or public-domain configuration.
 
 From the repository root, check the API after `./install.sh`:
 
@@ -21,6 +21,6 @@ docker compose --env-file .env -f docker-compose.local.yml ps
 docker compose --env-file .env -f docker-compose.local.yml down
 ```
 
-The `down` command keeps the MongoDB volume. Adding `-v` removes the volume
-and its data. For logs, updates, and optional settings, follow the
+The `down` command keeps the MongoDB and PostgreSQL volumes. Adding `-v` removes
+both volumes and their data. For logs, updates, and optional settings, follow the
 [repository's local deployment guide](https://github.com/Team-Commonly/commonly/blob/main/docs/deployment/SELF_HOSTED.md).

docs-site/deployment/environment-variables.mdx

@@ -3,9 +3,11 @@ title: Environment variables
 description: Configuration sources for self-hosting
 ---
 
-The local installer creates an ignored `.env` with a generated `JWT_SECRET`
-when one is missing. Keep it private and keep the value stable so existing
-sessions continue to work.
+If there is no `.env` file, the local installer creates an ignored one with a
+generated `JWT_SECRET` and `PG_PASSWORD`. If `.env` exists without `PG_PASSWORD`,
+the installer adds one. If `.env` exists without a non-default `JWT_SECRET`,
+`./install.sh` stops and asks you to set one. Keep the value private and stable
+so existing sessions continue to work.
 
 The local profile forwards only the variables listed in
 [`docker-compose.local.yml`](https://github.com/Team-Commonly/commonly/blob/main/docker-compose.local.yml).

docs-site/deployment/index.mdx

@@ -6,7 +6,7 @@ description: Local setup with Docker Compose
 ## Before you start
 
 You need Git, Docker Engine with the Compose v2 plugin, OpenSSL if the installer
-must create `.env`, and free ports `3000` and `5000`. Check Docker with
+must create or update `.env`, and free ports `3000` and `5000`. Check Docker with
 `docker compose version`.
 
 ## Start
@@ -20,12 +20,15 @@ cd commonly
 ```
 
 Open [http://localhost:3000](http://localhost:3000). The installer builds and
-starts the local frontend, backend, and MongoDB. It creates an ignored `.env`
-file with a generated `JWT_SECRET` if you do not already have one. Keep that
-file; changing the secret signs everyone out.
-
-This Compose setup is for one local or private machine. It has no TLS, reverse
-proxy, or public-domain configuration. Keep its ports off the public internet.
+starts the local frontend, backend, MongoDB, and PostgreSQL. If there is no `.env`
+file yet, it creates an ignored one with a generated `JWT_SECRET` and
+`PG_PASSWORD`. Keep that file; changing the secret signs everyone out.
+
+This Compose setup is for one machine. It has no TLS, reverse proxy, or
+public-domain configuration. Keep its ports off the public internet. The
+frontend is built to call `http://localhost:5000`, so a browser on another
+device would call its own localhost, not this machine. Open the app on the
+machine that runs it.
 
 For health checks, updates, and data retention, follow the
 [local deployment guide](https://github.com/Team-Commonly/commonly/blob/main/docs/deployment/SELF_HOSTED.md).

docs/audits/claim-table.md

@@ -75,6 +75,36 @@ Owner: TASK-013. Source: `docs-site/deployment/index.mdx`, `docker.mdx`, `kubern
 
 | Page | Claim | Verdict | Evidence | Date |
 |---|---|---|---|---|
+| index | Needs Git, Docker Engine with the Compose v2 plugin, OpenSSL, and free ports 3000 and 5000 | TRUE | Compose v2 check `install.sh:15-17`; openssl `install.sh:31-33`, `:43-45`; published ports `docker-compose.local.yml:71`, `:126`. The installer does not check the ports, so "free" is advice | 2026-10-27 |
+| index | Check Docker with `docker compose version` | TRUE | Same command is the Compose v2 check at `install.sh:15` | 2026-10-27 |
+| index | "Run the same three steps shown on the Commonly home page" | TRUE | `frontend/src/v2/landing/V2LandingPage.tsx:36` (`SELF_HOST_COMMAND`: the same clone, `cd`, `./install.sh`, joined with `&&`) | 2026-10-27 |
+| index | The three commands: `git clone https://github.com/Team-Commonly/commonly.git`, `cd commonly`, `./install.sh` | TRUE | `V2LandingPage.tsx:36`; `install.sh` exists at repo root | 2026-10-27 |
+| index | Open http://localhost:3000 after install | TRUE | `install.sh:62` prints `App: http://localhost:3000`; frontend port `docker-compose.local.yml:126` | 2026-10-27 |
+| index | The installer builds and starts the frontend, backend, MongoDB and PostgreSQL | TRUE | `install.sh:57` (`up -d --build`); services `docker-compose.local.yml:24` (postgres), `:43` (mongo), `:58` (backend), `:114` (frontend) | 2026-10-27 |
+| index | With no `.env`, the installer creates an ignored one with a generated `JWT_SECRET` and `PG_PASSWORD` | TRUE | `install.sh:21-37` (JWT), `:42-48` (PG_PASSWORD); `.env` is ignored at `.gitignore:12` | 2026-10-27 |
+| index | Changing the secret signs everyone out | TRUE | Tokens verify against `JWT_SECRET` at `backend/middleware/auth.ts:113`, so a new secret fails existing tokens. Not walked | 2026-10-27 |
+| index | Compose setup is for one machine; no TLS, reverse proxy or public-domain configuration | TRUE | `docker-compose.local.yml` has four services and no proxy or TLS service (`:24`, `:43`, `:58`, `:114`); header states "Local, single-machine setup" (`:2`) | 2026-10-27 |
+| index | Keep its ports off the public internet | TRUE | Backend and frontend publish `5000` and `3000` (`docker-compose.local.yml:71`, `:126`); the database services publish none | 2026-10-27 |
+| index | The frontend calls `http://localhost:5000` (build-time) | TRUE | `docker-compose.local.yml:120` (`REACT_APP_API_URL=http://localhost:5000`) | 2026-10-27 |
+| index | A browser on another device would call its own localhost, so open the app on the machine that runs it | TRUE | Follows from the build-time URL at `docker-compose.local.yml:120`. Not walked from a second device | 2026-10-27 |
+| index | Health checks, updates and data retention are in the local deployment guide | TRUE | Link target `docs/deployment/SELF_HOSTED.md` exists | 2026-10-27 |
+| index | Public deployments: Kubernetes guide and Helm values reference | TRUE | Link targets `docs/deployment/KUBERNETES.md` and `docs/self-hosting/helm-reference.md` exist; `k8s/helm/commonly/values.yaml` exists | 2026-10-27 |
+| docker | The local profile builds frontend, backend, MongoDB and PostgreSQL on one machine, with no TLS, reverse proxy or public-domain configuration | TRUE | `docker-compose.local.yml:24`, `:43`, `:58`, `:114`; no TLS or proxy service | 2026-10-27 |
+| docker | `curl --fail --silent http://localhost:5000/api/health` checks the API | TRUE | `backend/server.ts:283` mounts `/api/health`; `backend/routes/health.ts:21` returns `status: 'healthy'`; backend port `docker-compose.local.yml:71` | 2026-10-27 |
+| docker | `docker compose --env-file .env -f docker-compose.local.yml ps` and `down` | TRUE | Compose file exists at repo root; `install.sh:68-69` prints the same `--env-file … -f docker-compose.local.yml` form for `logs` and `down`. `ps` is not printed by the installer, but is a valid Compose v2 subcommand | 2026-10-27 |
+| docker | `down` keeps the MongoDB and PostgreSQL volumes; `-v` removes both | TRUE | Named volumes `mongo-data` and `postgres-data` at `docker-compose.local.yml:134-136`; `-v` removes named volumes per Compose semantics. Not run | 2026-10-27 |
+| docker | Logs, updates and optional settings are in the repository's local deployment guide | TRUE | Link target `docs/deployment/SELF_HOSTED.md` exists | 2026-10-27 |
+| environment-variables | With no `.env`, the installer creates one with a generated `JWT_SECRET` and `PG_PASSWORD` | TRUE | `install.sh:21-37`, `:42-48` | 2026-10-27 |
+| environment-variables | If `.env` exists without `PG_PASSWORD`, the installer adds one | TRUE | `install.sh:42-48` (appends `PG_PASSWORD` under `umask 077`) | 2026-10-27 |
+| environment-variables | If `.env` exists without a non-default `JWT_SECRET`, `./install.sh` stops and asks you to set one | TRUE | `install.sh:22-28` (exits 1 on a missing or `change-me-in-production-…` value) | 2026-10-27 |
+| environment-variables | Keep the value private and stable so existing sessions continue | TRUE | Tokens verify against `JWT_SECRET` at `backend/middleware/auth.ts:113` | 2026-10-27 |
+| environment-variables | The local profile forwards only the variables listed in `docker-compose.local.yml` | TRUE | Backend `environment:` list `docker-compose.local.yml:72-112`; no `env_file:` in the file (grep count 0). `--env-file` only supplies `${…}` interpolation (`install.sh:57`) | 2026-10-27 |
+| environment-variables | Putting a variable in `.env` does not make the local profile forward it | TRUE | Same evidence as the row above: only listed variables reach the backend container | 2026-10-27 |
+| environment-variables | `.env.example` covers broader development and deployment settings | TRUE | `.env.example:46` (`JWT_SECRET`) and the wider file | 2026-10-27 |
+| environment-variables | Connector setup follows its guide and the self-hosting guide | TRUE | Link target `docs/deployment/SELF_HOSTED.md` exists | 2026-10-27 |
+| kubernetes | The three-step install is a local Compose setup and does not supply TLS, ingress, database, secrets or a backup plan | TRUE | `docker-compose.local.yml` has no TLS, ingress or backup service; the database is a local container (`:24`, `:43`); secrets come from `.env` | 2026-10-27 |
+| kubernetes | Repository deployment guide and Helm values reference are the Kubernetes path | TRUE | `docs/deployment/KUBERNETES.md` and `docs/self-hosting/helm-reference.md` exist; `k8s/helm/commonly/values.yaml` exists | 2026-10-27 |
+| kubernetes | Choose image, database, secrets, ingress and backup settings before running Helm | TRUE | Advice; the chart exposes these as values in `k8s/helm/commonly/values.yaml`. Not walked | 2026-10-27 |
 
 ## Pricing