diff --git a/docs-site/deployment/docker.mdx b/docs-site/deployment/docker.mdx index 2482bc920b..8ecbbc85e9 100644 --- a/docs-site/deployment/docker.mdx +++ b/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). diff --git a/docs-site/deployment/environment-variables.mdx b/docs-site/deployment/environment-variables.mdx index b414a65ae5..c912df8b32 100644 --- a/docs-site/deployment/environment-variables.mdx +++ b/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). diff --git a/docs-site/deployment/index.mdx b/docs-site/deployment/index.mdx index 9f265193a1..f71d90c1eb 100644 --- a/docs-site/deployment/index.mdx +++ b/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). diff --git a/docs/audits/claim-table.md b/docs/audits/claim-table.md index 7ec6662401..9085e53e8b 100644 --- a/docs/audits/claim-table.md +++ b/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