Document provisioning requirements, enable prettier formatting of markdown files

Author: davidje13

.prettierrc.json

@@ -1,4 +1,5 @@
 {
   "singleQuote": true,
-  "trailingComma": "all"
+  "trailingComma": "all",
+  "proseWrap": "always"
 }

README.md

@@ -14,17 +14,17 @@ Requires [Node.js 20 or above](https://nodejs.org/en/).
 npm start
 ```
 
-The site will be available at <http://localhost:5000/>, using a mock
-Google authentication server and an in-memory database.
+The site will be available at <http://localhost:5000/>, using a mock Google
+authentication server and an in-memory database.
 
 See [CONTRIBUTING.md](docs/CONTRIBUTING.md) for full guidance on local
 development.
 
 ## Building for deployment
 
 You can find pre-built releases at
-[Refacto/releases](https://github.com/davidje13/Refacto/releases),
-or you can build your own:
+[Refacto/releases](https://github.com/davidje13/Refacto/releases), or you can
+build your own:
 
 ```sh
 npm run build
@@ -36,49 +36,77 @@ The output is placed in `build`.
 
 ### With Docker
 
-You can deploy using the [Docker Hub image](https://hub.docker.com/r/refacto/refacto):
+You can deploy using the
+[Docker Hub image](https://hub.docker.com/r/refacto/refacto):
 
 ```sh
 docker run -d -e INSECURE_SHARED_ACCOUNT_ENABLED=true -p 5000:5000 refacto/refacto
 ```
 
-(see the image details for information on how to configure and secure docker deployments).
+(see the image details for information on how to configure and secure docker
+deployments).
 
 ### Without Docker
 
 You will need to have Node.js 20 or newer installed in the deployment
 environment.
 
-[Download and unpack a release](https://github.com/davidje13/Refacto/releases) (or
-[build your own](#building-for-deployment)), then in the release directory run:
+[Download and unpack a release](https://github.com/davidje13/Refacto/releases)
+(or [build your own](#building-for-deployment)), then in the release directory
+run:
 
 ```sh
 npm install --omit=dev
 INSECURE_SHARED_ACCOUNT_ENABLED=true ./index.js
 ```
 
+### Provisioning
+
+Refacto does not require much CPU or RAM allocated to run smoothly. You should
+be able to provision the minimum available CPU on your platform of choice, and
+at least 0.5GB RAM (provision 1GB if you expect very heavy usage). One area
+which can be improved by allocating more CPU is the password login: this will be
+noticeably faster with more CPU resource available (or you can
+[enable more hashing rounds](./docs/SECURITY.md#work-factor) to increase
+security).
+
+Note that because Refacto uses Web Sockets for live collaboration, you will need
+to ensure your deployment is capable of holding open a large number of
+simultaneous connections (at least one per expected concurrent user, plus some
+extra for static asset and API requests). For small deployments this is not a
+concern, as the defaults are usually ample.
+
+You should _not_ enable any auto-scaling provided by your platform. Where
+possible, set the maximum number of instances to 1 (note that some platforms
+enable auto-scaling by default). For efficiency reasons, Refacto needs all
+participants in a particular retro to be connected to the same server, otherwise
+they will not see each other's changes in real time. Most deployments will not
+need more than a single small instance to run Refacto successfully, but if you
+have a very high load and _need_ additional instances, see
+[Load Balancing in the services documentation](docs/SERVICES.md#load-balancing)
+for an example of how to correctly load balance using an NGINX reverse proxy.
+
 ### Configuration
 
 By default:
 
-- no authentication providers are available (setting `INSECURE_SHARED_ACCOUNT_ENABLED`
-  means everybody who can access the site will be able to see all retros);
-- an in-memory database is used
-  (all data will be lost when the process ends);
-- blank secrets are used for encryption and password hashing
-  (you can use `./scripts/random-secrets.mjs` to generate a set of
-  secure random secrets for a deployment);
+- no authentication providers are available (setting
+  `INSECURE_SHARED_ACCOUNT_ENABLED` means everybody who can access the site will
+  be able to see all retros);
+- an in-memory database is used (all data will be lost when the process ends);
+- blank secrets are used for encryption and password hashing (you can use
+  `./scripts/random-secrets.mjs` to generate a set of secure random secrets for
+  a deployment);
 - Giphy integration is not enabled;
 - haveibeenpwned integration _is_ enabled;
 - the server listens on port `5000`.
 
-See [SERVICES.md](docs/SERVICES.md) and
-[SECURITY.md](docs/SECURITY.md) for details.
+See [SERVICES.md](docs/SERVICES.md) and [SECURITY.md](docs/SECURITY.md) for
+details.
 
-The full list of recognised configuration options (and their default
-values) can be found in
-[config/default.ts](./backend/src/config/default.ts)
-(nested properties are joined and written in `UPPER_SNAKE_CASE`).
+The full list of recognised configuration options (and their default values) can
+be found in [config/default.ts](./backend/src/config/default.ts) (nested
+properties are joined and written in `UPPER_SNAKE_CASE`).
 
 Typical values to configure are:
 
@@ -103,10 +131,10 @@ TOKEN_SECRET_PASSPHRASE="<value-from-random-secrets.mjs>" \
 
 ## Services
 
-See the [services documentation](docs/SERVICES.md) for details on
-setting up a database and integrating with authentication providers.
+See the [services documentation](docs/SERVICES.md) for details on setting up a
+database and integrating with authentication providers.
 
 ## Extra security
 
-See the [security documentation](docs/SECURITY.md) for details on
-configuring additional security for deployments.
+See the [security documentation](docs/SECURITY.md) for details on configuring
+additional security for deployments.

docs/CONTRIBUTING.md

@@ -7,13 +7,12 @@ npm start
 ```
 
 The site (both frontend resources and backend API) will be available at
-<http://localhost:5000/>. The frontend will automatically rebuild if
-changed, but the backend will not (looking for a good Rollup HMR plugin!)
+<http://localhost:5000/>. The frontend will automatically rebuild if changed,
+but the backend will not (looking for a good Rollup HMR plugin!)
 
-By default, this will run a mock Google authentication provider and an
-in-memory database. To enable real authentication providers (e.g.
-Google sign in) and data persistence, see the
-[services documentation](./SERVICES.md).
+By default, this will run a mock Google authentication provider and an in-memory
+database. To enable real authentication providers (e.g. Google sign in) and data
+persistence, see the [services documentation](./SERVICES.md).
 
 ## Running tests
 
@@ -49,37 +48,36 @@ To automatically build and run the server, and run tests against it:
 npm run test:e2e
 ```
 
-During development, the build time can be significant. An alternative
-is to run the application in the background in watch mode using
-`npm start -- --mock-sso` (this differs from `npm start` because it
-uses a mock Google single-sign-on endpoint even if you have configured
-a real client ID), then run the end-to-end tests against that
-deployment:
+During development, the build time can be significant. An alternative is to run
+the application in the background in watch mode using `npm start -- --mock-sso`
+(this differs from `npm start` because it uses a mock Google single-sign-on
+endpoint even if you have configured a real client ID), then run the end-to-end
+tests against that deployment:
 
 ```sh
 TARGET_HOST=http://localhost:5000/ MODE=dev npm run test:e2e
 ```
 
-(`MODE=dev` disables the download time test, as the site is much
-larger when built in dev mode via `npm start`)
+(`MODE=dev` disables the download time test, as the site is much larger when
+built in dev mode via `npm start`)
 
 Run end-to-end tests with non-headless browsers:
 
 ```sh
 HEADLESS=false npm run test:e2e
 ```
 
-The server logs generated during the end-to-end test run are written
-to `e2e/build/app.log`.
+The server logs generated during the end-to-end test run are written to
+`e2e/build/app.log`.
 
 ## Building
 
 ```sh
 npm run build
 ```
 
-The output will be placed in `build`. Specify the `PORT` environment
-variable when running (defaults to 5000):
+The output will be placed in `build`. Specify the `PORT` environment variable
+when running (defaults to 5000):
 
 ```sh
 cd build
@@ -100,19 +98,19 @@ This client ID is configured for use on `localhost` on ports 80, 443, 8080,
 8443, and 5000. The client secret is not required, as Refacto does not access
 any personal data.
 
-See the [services documentation](./SERVICES.md) for details on
-setting up a database and integrating with authentication providers.
+See the [services documentation](./SERVICES.md) for details on setting up a
+database and integrating with authentication providers.
 
-See the [security documentation](./SECURITY.md) for additional
-considerations when running in production.
+See the [security documentation](./SECURITY.md) for additional considerations
+when running in production.
 
 ## Dependency management
 
-Add dependencies within the `backend`, `frontend` or `e2e` directories;
-not in the root of the project.
+Add dependencies within the `backend`, `frontend` or `e2e` directories; not in
+the root of the project.
 
-Remember that runtime dependencies should be installed with `--save`,
-and build / test dependencies should be installed with `--save-dev`.
+Remember that runtime dependencies should be installed with `--save`, and build
+/ test dependencies should be installed with `--save-dev`.
 
 ### Examples
 
@@ -135,16 +133,19 @@ npm install --save-dev selenium-webdriver
 
 ## Browser Support
 
-The latest versions of Google Chrome and Mozilla Firefox are supported,
-and the end-to-end tests will run in both (see [Running tests](#running-tests)).
+The latest versions of Google Chrome and Mozilla Firefox are supported, and the
+end-to-end tests will run in both (see [Running tests](#running-tests)).
 
 ## Library documentation
 
 - React: <https://reactjs.org/docs/react-api.html>
 - `update`: <https://github.com/davidje13/json-immutability-helper>
 - Wouter: <https://github.com/molefrog/wouter>
 - Jest: <https://jestjs.io/docs/en/api>
-- Flexible Testing Library React <https://github.com/davidje13/flexible-testing-library-react>
+- Flexible Testing Library React
+  <https://github.com/davidje13/flexible-testing-library-react>
 - Jest DOM Matchers <https://github.com/testing-library/jest-dom>
-- Supertest: <https://github.com/visionmedia/supertest> and <https://visionmedia.github.io/superagent/>
-- Selenium: <https://seleniumhq.github.io/selenium/docs/api/javascript/module/selenium-webdriver/>
+- Supertest: <https://github.com/visionmedia/supertest> and
+  <https://visionmedia.github.io/superagent/>
+- Selenium:
+  <https://seleniumhq.github.io/selenium/docs/api/javascript/module/selenium-webdriver/>