fhirsmith 0.18.1 → 1.0.0

package/CONFIGURATION.md

@@ -0,0 +1,305 @@
+# FHIRsmith Configuration
+
+The server is configured by `config.json` in the data directory (see
+[Data Directory](README.md#data-directory)), plus a few environment variables.
+`config-template.json` is a starting point: it has every section, with comments, and every
+module turned off - set `"enabled": true` on the ones you run. `config.json` is JSON, except that
+it may have comments: `//` to the end of the line, and `/* ... */`.
+
+Upgrading? See [Upgrading to 1.0.0](#upgrading-to-100).
+
+The top level of `config.json` has the server-wide settings described here, and a
+`modules` section with an entry for each module (see [Modules](#modules)).
+
+## Server
+
+Create a `config.json` file in your data directory (use `config-template.json` as a starting point):
+
+```json
+{
+  "hostName" : "[descriptive name for the server]",
+  "server": {
+    "port": 3000,
+    "cors": {
+      "origin": "*",
+      "credentials": true
+    }
+  },
+  "modules": {
+    // per modules...
+  }
+}
+```
+
+| Option | Default | Description |
+|---|---|---|
+| `server.maxBodyMB` | `50` | Largest request body accepted, in MB. A body is read whole into memory before it is parsed, so this bounds what one request can take. A bigger body gets a 413: an OperationOutcome (too-costly) on a tx endpoint, and the module's own handling elsewhere. The largest IG Publisher request seen on build.fhir.org was 1.39 MB, so 50 leaves plenty of room. The ips module reads its own bodies, with its own limit |
+
+Behind nginx, nginx's `client_max_body_size` is checked first. If it is lower than `maxBodyMB`, nginx refuses a bigger body with its own 413 HTML page before FHIRsmith sees it, so set it at or above `maxBodyMB` to get FHIRsmith's OperationOutcome; if it is higher, `maxBodyMB` applies. Requests of over 100 MB have been seen, caused by client-side issues: choose `maxBodyMB` (default 50) and the nginx limit with that in mind. See [nginx.md](nginx.md).
+
+### Memory
+
+`server.memory` sets the memory guard: fractions of the memory limit (the cgroup limit, such
+as `MemoryMax` on the systemd unit, or else the machine's RAM), measured against process RSS;
+with a role, against the whole cgroup's private memory (see [cluster.md](cluster.md#memory)).
+
+| Option | Default | Description |
+|---|---|---|
+| `server.memory.rejectFraction` | `0.85` | Above this, new requests get 503 + `Retry-After` |
+| `server.memory.abortFraction` | `0.92` | Above this, running operations are aborted with 422 too-costly |
+| `server.memory.trimAllocator` | `false`; `true` with a role | Whether the server returns the C allocator's free memory (`malloc_trim`, Linux) while refusing, and, with a role, once after loading. Without a role it is off unless set `true`; with one, `false` is for diagnosis. See [cluster.md](cluster.md#memory) |
+
+### Cluster
+
+To use more than one CPU core for terminology on one machine, a master and several tx
+workers share the data directory and `config.json` (started by `node cluster.js`, or by hand
+with `--role`). Their settings are in `server.cluster`, documented with the arrangement in
+[cluster.md](cluster.md): the launcher's (`workers`, `maxOutstanding`, `queueSeconds`,
+`recycleSeconds`, the fast lane, ...) under
+[The launcher](cluster.md#the-launcher-clusterjs), and what the processes share
+(`sharedCache`, `cacheAffinity`, `sharedCacheMaxMB`, `sharedClosure`) under
+[Options](cluster.md#options). With no role, `server.cluster` is ignored.
+The status panel's snapshot of every process (`statusSeconds`) is under
+[Status](cluster.md#status).
+
+### Statistics
+
+`stats` sets the request counters and the graphs on `/` and `/dashboard`.
+
+| Option | Default | Description |
+|---|---|---|
+| `stats.enabled` | `true` | `false`: the counters are kept in memory only |
+| `stats.database` | `stats.db` | The counters' SQLite file, under the data folder's `databases` directory |
+| `stats.intervalMinutes` | `10` | How often the counters are written to the database; also the graphs' sample interval, unless `sampleSeconds` is set (a server with no role, as before) |
+| `stats.sampleSeconds` | `intervalMinutes`; with a role, 60 at most | How often the graphs take a sample. With a role (cluster.md), at most a minute unless set, so the graphs of a short session can be read. The graphs show 24 hours; under the launcher at most 1,440 samples a process, so with less than a minute they show less. The counters are still written every `intervalMinutes` |
+
+## Logging
+
+Add a `logging` section to `config.json` to control log behaviour. All fields are optional and have sensible defaults:
+
+```json
+{
+  "logging": {
+    "level": "info",
+    "console": true,
+    "consoleErrors": false,
+    "maxFiles": 14,
+    "maxSize": "50m",
+    "flushInterval": 2000,
+    "flushSize": 200
+  }
+}
+```
+
+| Option | Default | Description |
+|---|---|---|
+| `level` | `"info"` | Minimum level to log: `error`, `warn`, `info`, `debug`, or `verbose` |
+| `console` | `true` | Write log lines to stdout/stderr. Disable when running as a systemd service where console output goes to the journal and is redundant |
+| `consoleErrors` | `false` | Whether `error` and `warn` levels appear on the console. When `false`, errors and warnings are written to the log file only |
+| `maxFiles` | `14` | Number of daily log files to retain before old ones are deleted |
+| `maxSize` | `0` (unlimited) | Maximum size per log file before rotation. Accepts human-readable strings: `"20m"`, `"1g"`, or a raw byte count |
+| `flushInterval` | `2000` | Milliseconds between buffered writes to disk. Increase to reduce I/O under heavy load |
+| `flushSize` | `200` | Number of buffered log lines that trigger an immediate flush regardless of the timer |
+
+Log files are written to the `logs/` subdirectory of the data directory as `server-YYYY-MM-DD.log`. A `server.log` symlink always points to the current day's file, so `tail -f data/logs/server.log` tracks the active log without needing to know the date.
+
+## Email and the Daily Report
+
+The server can email a short markdown report on itself once a day. It needs two things in
+`config.json`: an SMTP server to send through, and someone to send to:
+
+```json
+{
+  "email": {
+    "host": "smtp.example.org",
+    "port": 587,
+    "user": "fhirsmith",
+    "password": "...",
+    "from": "FHIRsmith <fhirsmith@example.org>"
+  },
+  "dailyReport": {
+    "to": ["ops@example.org"]
+  }
+}
+```
+
+`user`/`password` are optional (an open relay); `secure` defaults to true for port 465 and
+to STARTTLS otherwise. Without an `email` block nothing is emailed, and without
+`dailyReport.to` there's no report (`dailyReport.enabled: false` turns it off explicitly).
+
+The report, titled "`{hostName}` daily report", goes out at midnight (the server's local
+time), or as soon as the server is up again if it was down at midnight. It has a paragraph
+on the server's stability since the last report - how much of the time it was up, restarts,
+the longest outage, and any upgrade (from the run history in the statistics database, so
+`stats.enabled: false` leaves the uptime unknown); under the launcher (`cluster.js`), a
+paragraph on the cluster - processes that exited or were recycled, how long they were
+unavailable, and the requests the launcher refused or abandoned itself (see
+[cluster.md](cluster.md#the-daily-report)); a paragraph from each running module that
+has something to report (by default, none do); and a paragraph on the system - version,
+Node.js and OS, how long this run has been up, the log files and the free disk space they're
+drawing on, plus anything the npm audit check has found (packages with known vulnerabilities and
+what to do about them, or a newer FHIRsmith release). If any background task's last run failed, a
+final section lists them. When the last report was sent is kept in `daily-report.json` in the data
+directory.
+
+A module takes part by implementing `dailyReport({since, now})`, returning its paragraph as
+markdown (or a promise of it); an empty return means it has nothing to say that day. The
+request counts a module quotes come from `stats.countsSince(since, now)`, the per-operation
+counts in the statistics database for the period. The modules that report:
+
+| Module | Reports |
+|---|---|
+| Terminology server | how many of each operation were performed, over all its endpoints |
+| Terminology server registry | client requests answered by the API, servers registered, and any server that answered none of the registry's scans in the period |
+| Packages | packages served (tarball downloads) and new package versions found by the crawler |
+| XIG | pages served, and whether the database could be accessed (and whether the last download failed) |
+| Testing | pages served, test reports received, and the number held |
+| SMART Health Links | QR codes created (SMART Health Links and Verifiable Health Links), link accesses, and the documents stored to serve them |
+| IPS | pages served, IPS documents received, and the number stored |
+| Publisher | publication runs started, and how many finished successfully |
+
+## Environment Variables
+
+| Variable | Description | Default |
+|---|---|---|
+| `FHIRSMITH_DATA_DIR` | Path to the data directory | `./data` |
+| `PORT` | Server port (overrides config) | from config.json |
+| `FHIRSMITH_ROLE` | `master` or `tx-worker`, as `--role` (see [cluster.md](cluster.md#roles)). Not set: an ordinary single server | none |
+| `FHIRSMITH_INSTANCE_CODE` | This process's cache-id prefix, as `--instance-code` (see [cluster.md](cluster.md#roles)) | a master: `modules.tx.instanceCode`, and with none it stops with an error; a worker: none, and it stops with an error. The launcher gives `m0`, `tx1`, ... |
+| `FHIRSMITH_WORKERS` | How many tx-workers `node cluster.js` starts, as `--workers` (`server.cluster.workers`) | from the CPUs and memory |
+| `FHIRSMITH_CACHE_WAIT_MS` | How long a tx-worker waits for the master to build a cache it reads (see [cluster.md](cluster.md#what-runs-where)) | `300000` (5 minutes) |
+| `NODE_ENV` | Node environment. Express and other libraries check it (in development mode, Express's error pages include stack traces). If it isn't set the server sets it to `production`, or to `development` when run with `npm run dev` | `production` |
+
+## Modules
+
+Each module has its own entry under `modules`, documented with the module:
+
+| Module | Configuration |
+|---|---|
+| `tx` - terminology server | [tx/README.md](tx/README.md#configuration) |
+| `registry` - terminology server registry | [registry/documentation/configuration.md](registry/documentation/configuration.md) |
+| `packages` - package server | [packages/readme.md](packages/readme.md) |
+| `shl` - SMART Health Links | [shl/readme.md](shl/readme.md) |
+| `ips` - IPS documents | [ips/readme.md](ips/readme.md) |
+| `testing` - test reports | [testing/readme.md](testing/readme.md) |
+| `folder` | [folder/readme.md](folder/readme.md) |
+| `npmprojector` | [npmprojector/readme.md](npmprojector/readme.md) |
+| `token` | [token/security_guide.md](token/security_guide.md) |
+| `xig` | [xig/readme.md](xig/readme.md) |
+| `vcl` | [vcl/readme.md](vcl/readme.md) |
+| `publisher` | [publisher/readme.md](publisher/readme.md) |
+
+## Upgrading to 1.0.0
+
+1.0.0 is a big upgrade from 0.17 and 0.18. Most servers won't need to change any settings, but
+every operator should check these. Each item says who it affects; the [CHANGELOG](CHANGELOG.md)
+has the detail.
+
+### Every server
+
+- **Node.js 24** or later (`engines` in package.json). After upgrading Node, `npm ci` (there
+  are new dependencies) - or `npm rebuild` for the native ones.
+- **Start command**: `npm start` is now `node --expose-gc server.js`. A service that runs
+  `node server.js` still works (the memory guard sets the flag itself), but add `--expose-gc`.
+  `--port` or `--instance-code` without `--role` now stops the server with an error (they used
+  to be ignored): drop them from a single server's command line.
+- **`NODE_ENV`** is `production` when it isn't set (`npm run dev`: `development`). Set it
+  yourself if you relied on development mode (Express's error pages with stack traces).
+- **Keep-alive**: idle connections are kept for 65 s (was Node's 5 s), longer than nginx's
+  upstream `keepalive_timeout` (60 s by default). If you set nginx's higher, keep it under 65 s.
+- **Memory guard** (new, on by default): above 85% of the memory limit (the cgroup's - systemd
+  `MemoryMax` - or else the machine's RAM) new requests get 503, and above 92% running
+  operations are aborted (422). If your memory limit is tight, check `server.memory` ([Memory](#memory)).
+- **Request size**: `server.maxBodyMB` (default 50) is now a setting. nginx's
+  `client_max_body_size` must be at least as big, or clients get nginx's HTML 413 rather than an
+  OperationOutcome.
+- **`config.json` may have comments** (`//` and `/* */`), and `config-template.json` now has
+  every module turned off.
+- **New, optional**: `email` and `dailyReport.to` ([the daily report](#email-and-the-daily-report) -
+  nothing is sent without both), `npmAudit` (a periodic `npm audit` of the server; set
+  `"enabled": false` on a server with no internet access), `accessibility.checkPanel`,
+  `stats.sampleSeconds`.
+- **Cluster mode** (`node cluster.js`, [cluster.md](cluster.md)) is new and opt-in: `server.js`
+  runs as before.
+
+### tx (terminology server)
+
+- **Expansion limits**: the defaults are now `externalLimit` 10000 (was 3000) and `internalLimit`
+  100000 (was 10000), and there's a new `walkLimit` (default 10 x `internalLimit`) for paging.
+  The three are checked at startup: one that isn't a whole number above 0, or
+  external <= internal <= walk not holding, **stops the server**. If you set any of them, check
+  them. Bigger expansions now succeed, so a busy server may use more memory.
+- **Value sets with an exclude or an import are limited** like any other (they used to come
+  back whole, whatever their size): a client that expands a big one unpaged now gets a 422
+  too-costly, and should page it.
+- **`Tools/Java` is no longer special**: the IG Publisher and the tx-ecosystem test runner get
+  the configured limits like any client (they used to be held to 3000/10000).
+- **`x-too-costly-threshold`** can only lower the limit: a value above `internalLimit` is cut
+  down to it, and `0` (or anything that isn't a positive whole number) is ignored - it no
+  longer means "no limit".
+- **Memory caps** with defaults (see the `Limits:` line in the startup log): `cacheMaxConcepts`,
+  `cacheMaxTotalConcepts`, `expansionCacheMaxCodes`, `usageTrackerMaxCodes`,
+  `usageTrackerMaxCodeLength`, `languageTagCacheSize`. A client may now get `cache-id-unknown`
+  (or 422) for a `$cache-control` cache that grew too big.
+- **New, optional**: `snomed` (load SNOMED CT editions memory-mapped, or prewarmed - see
+  tx/README.md), and `ecosystem` (`$validate-code` for code systems held by other servers in
+  the terminology ecosystem; off by default).
+- **`pruneTerminologyCache`** (new, default false): delete the databases, caches and packages
+  in `terminology-cache` that the library no longer uses. Turn it on for a server that has the
+  data directory to itself.
+- **`instanceCode`** is checked at startup, and a cluster master needs one.
+- **VSAC** (`vsacCfg`): the default `baseUrl` is https (an http one is logged as a warning);
+  value sets are read from the database when asked for, with a cache sized by `valueSetCacheMB`
+  (default 64); a value set version VSAC doesn't have is now not found.
+- **Language packs**: a `lang-pack` or `extension-codes` supplement is used without being
+  referenced only when it is marked `codesystem-supplement-global` = `true`. The
+  `global-lang-pack` code is gone. If you load language packs, check they are marked.
+- **Behaviour, with no setting**: `regex` filters match the whole value (LOINC regex value sets
+  may select fewer codes); ICD-11 codes are entity ids; a resource that both THO and a core
+  package provide is available in both versions; for LOINC answer lists, `answers-for` is the
+  filter (`LIST` still works, for backwards compatibility only); `$cache-control` caches are
+  never carried over a restart.
+- **Rebuilds** (optional, for the new features): SNOMED CT caches for alternate identifiers and
+  concrete values, and any built in a time zone ahead of UTC (their effectiveTimes are a day
+  early); the LOINC database for its mappings, its Part translations (`PartName` designations,
+  from every linguistic variant) and without the blank answer code that externally defined
+  answer lists added. RxNorm's new index is added to an existing database at load. Coming from
+  0.16 or earlier, the package value set and concept map caches rebuild themselves once, so
+  the first start is slower.
+
+### Other modules
+
+- **registry**: `maxResponseMB` (default 100) limits what the crawler reads from a server. New,
+  optional: `oauth`, client credentials for servers that need a token to be scanned.
+- **packages**: the crawler refuses packages over its new limits (`maxDownloadMB` 250,
+  `maxUnpackedMB` 4096, `maxFileMB` 50, `maxFiles` 250000); raise them only if a real package
+  is refused.
+- **packages, signing** (on by default, `npmSigning`): the registry signs every version, so
+  `npm audit signatures` works against it. At the first start it makes its key,
+  `npm-signing-key.pem` next to the database (`npmSigning.keyFile`) - **back it up**: clients
+  check signatures against the published key - and signs the versions it already holds in the
+  background (`/packages/-/npm/v1/keys` is a 404 until it's done; progress in `/packages/status`).
+  Set `"enabled": false` to opt out.
+- **packages, publishers' signatures**: `crawler.signatures` defaults to `check` (a signature
+  that fails is logged and the package stored anyway); `require` refuses unsigned packages and
+  doesn't read feeds that list no keys. Feeds' keys are in `package-feeds.json`.
+- **packages, `/packages/feed-check`** (on by default, `feedCheck`): anyone can have the server
+  download and check a feed's packages (one run at a time, at most `maxItems` 50 and
+  `maxTotalMB` 500). Set `"enabled": false` if you don't want that on your server.
+- **xig**: `POST /xig/update` only works when `updateToken` is set.
+- **ext-tracker**: set `token` (the IG Publisher's) so only the publisher can submit.
+- **token**: the JSON API takes the API key in a header (`Authorization: Bearer` or
+  `X-API-Key`), not the URL - clients must change. The session cookie is now `Secure` when the
+  request came over https, which behind nginx needs `X-Forwarded-Proto` (`cookieSecure`
+  overrides).
+- **publisher**: the administrator's password is now `adminPassword` in the config (set at
+  every start). Without it, an administrator that still has the old fixed default password
+  (`admin123`) gets a random one at startup, which is logged - set `adminPassword`, or look in
+  the log.
+- **ips**: to use a validator jar of your own, set `validator.jar`, rather than replacing
+  `bin/validator_cli.jar`. `validator.checkIpsCodes` is gone (validator 7.0.4 refuses it);
+  `validator.autoLoadPackages` (default true) lets the validator load the packages that define
+  extensions it doesn't know.
+
+There are no manual data migrations: the databases that changed migrate themselves at startup.
+

package/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2025-2026, Health Intersections Pty Ltd and the FHIRsmith contributors
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -32,12 +32,19 @@ These are not being actively developed at present.
 ## Planned
 
 * R4/R6 interconverter
+* Full RESTful server implementation
+
+## Open Areas of Work 
+
+* How to handle expansions and validations of some kinds of invalid value sets 
+* more efficient CodeSystem implementations 
+* more work on internationalization of IPS documents and the IPS repository generally
 
 ## Summary Statement
 
 * Maintainers: Grahame Grieve, Italo Macêdo, Josh Mandel, Jose Costa Teixeira
 * Issues / Discussion: Use github issues
-* License: BSD-3
+* License: BSD-3-Clause (see [LICENSE](LICENSE))
 * Contribution Policy: Make PRs. PRs have to pass all the tests
 * Security Information: See [security.md](security.md)
 
@@ -51,23 +58,25 @@ in-build support for SSL, rate limiting etc. See [nginx.md](nginx.md) for how to
 
 ## Quick Start
 
-There are 4 executable programs:
+There are 5 executable programs:
 * the server (`node server`)
+* the cluster server (`node cluster`) - for high performance uses (see [cluster.md](cluster.md))
 * the terminology importer (`node --max-old-space-size=8192 tx/importers/tx-import XXX`) - see [Doco](tx/importers/readme.md)
 * the test cases (`npm test`)
 * the test cases generater (`node tx/tests/testcases-generator.js`)
 
-Unless you're developing, you only need the first two
+Unless you're developing, you only need the first three
 
 FHIRsmith is open source - see below, and you're welcome to use it for any kind of use. Note,
-though, that if you support FHIRsmith commercially as part of a managed service or product, you
-are required to be a Commercial Partner of HL7 - see (link to be provided).
+though, that if you support FHIRsmith commercially as part of a managed service or product, 
+and you seek support for your implementation from the project team, you are required to be a
+Commercial Partner of HL7 - consult [The FHIR Product Director](mailto:fhir-director@hl7.org).
 
 ### Quick Start
 
 * Install FHIRSmith (using docker, or an NPM release, or just get the code by git)
 * Figure out the data directory
-* Provide a configuration to tell the server what to run (see documentation below, or use a [prebuilt configuration]/configurations/readme.md)
+* Provide a configuration to tell the server what to run (see [CONFIGURATION.md](CONFIGURATION.md), or use a [prebuilt configuration](configurations/readme.md))
 * Run the server
 
 For further details of these steps, read on
@@ -116,115 +125,17 @@ npm install
 mkdir -p data data/logs
 
 # Copy example configuration
-cp config.example.json data/config.json
+cp config-template.json data/config.json
 
-# Edit configuration as needed
+# Edit configuration: every module is off until you set "enabled": true (comments are allowed)
 nano data/config.json
 ```
 
-Each Module has it's own entry in the config, as described by the module
-
-### Basic Configuration
-
-Create a `config.json` file in your data directory (use `config-template.json` as a starting point):
-
-```json
-{
-  "hostName" : "[descriptive name for the server]",
-  "server": {
-    "port": 3000,
-    "cors": {
-      "origin": "*",
-      "credentials": true
-    }
-  },
-  "modules": {
-    // per modules...
-  }
-}
-```
-
-### Logging Configuration
-
-Add a `logging` section to `config.json` to control log behaviour. All fields are optional and have sensible defaults:
-
-```json
-{
-  "logging": {
-    "level": "info",
-    "console": true,
-    "consoleErrors": false,
-    "maxFiles": 14,
-    "maxSize": "50m",
-    "flushInterval": 2000,
-    "flushSize": 200
-  }
-}
-```
-
-| Option | Default | Description |
-|---|---|---|
-| `level` | `"info"` | Minimum level to log: `error`, `warn`, `info`, `debug`, or `verbose` |
-| `console` | `true` | Write log lines to stdout/stderr. Disable when running as a systemd service where console output goes to the journal and is redundant |
-| `consoleErrors` | `false` | Whether `error` and `warn` levels appear on the console. When `false`, errors and warnings are written to the log file only |
-| `maxFiles` | `14` | Number of daily log files to retain before old ones are deleted |
-| `maxSize` | `0` (unlimited) | Maximum size per log file before rotation. Accepts human-readable strings: `"20m"`, `"1g"`, or a raw byte count |
-| `flushInterval` | `2000` | Milliseconds between buffered writes to disk. Increase to reduce I/O under heavy load |
-| `flushSize` | `200` | Number of buffered log lines that trigger an immediate flush regardless of the timer |
-
-Log files are written to the `logs/` subdirectory of the data directory as `server-YYYY-MM-DD.log`. A `server.log` symlink always points to the current day's file, so `tail -f data/logs/server.log` tracks the active log without needing to know the date.
-
-### Email and the Daily Report
-
-The server can email a short markdown report on itself once a day. It needs two things in
-`config.json`: an SMTP server to send through, and someone to send to:
-
-```json
-{
-  "email": {
-    "host": "smtp.example.org",
-    "port": 587,
-    "user": "fhirsmith",
-    "password": "...",
-    "from": "FHIRsmith <fhirsmith@example.org>"
-  },
-  "dailyReport": {
-    "to": ["ops@example.org"]
-  }
-}
-```
+### Configuration
 
-`user`/`password` are optional (an open relay); `secure` defaults to true for port 465 and
-to STARTTLS otherwise. Without an `email` block nothing is emailed, and without
-`dailyReport.to` there's no report (`dailyReport.enabled: false` turns it off explicitly).
-
-The report, titled "`{hostName}` daily report", goes out at midnight (the server's local
-time), or as soon as the server is up again if it was down at midnight. It has a paragraph
-on the server's stability since the last report - how much of the time it was up, restarts,
-the longest outage, and any upgrade (from the run history in the statistics database, so
-`stats.enabled: false` leaves the uptime unknown); a paragraph from each running module that
-has something to report (by default, none do); and a paragraph on the system - version,
-Node.js and OS, how long this run has been up, the log files and the free disk space they're
-drawing on, plus anything the npm audit check has found (packages with known vulnerabilities and
-what to do about them, or a newer FHIRsmith release). If any background task's last run failed, a
-final section lists them. When the last report was sent is kept in `daily-report.json` in the data
-directory.
-
-A module takes part by implementing `dailyReport({since, now})`, returning its paragraph as
-markdown (or a promise of it); an empty return means it has nothing to say that day. The
-request counts a module quotes come from `stats.countsSince(since, now)`, the per-operation
-counts in the statistics database for the period. The modules that report:
-
-| Module | Reports |
-|---|---|
-| Terminology server | how many of each operation were performed, over all its endpoints |
-| Terminology server registry | client requests answered by the API, servers registered, and any server that answered none of the registry's scans in the period |
-| Packages | packages served (tarball downloads) and new package versions found by the crawler |
-| XIG | pages served, and whether the database could be accessed (and whether the last download failed) |
-| Testing | pages served, test reports received, and the number held |
-| SMART Health Links | QR codes created (SMART Health Links and Verifiable Health Links), link accesses, and the documents stored to serve them |
-| IPS | pages served, IPS documents received, and the number stored |
-| Publisher | publication runs started, and how many finished successfully |
+The server reads `config.json` from the data directory. See [CONFIGURATION.md](CONFIGURATION.md)
+for the server settings (port, body size, logging, email and the daily report), the environment
+variables, and where each module's own settings are documented.
 
 ### Start the Server
 
@@ -237,9 +148,10 @@ npm start
 ```
 
 The server will be available at `http://localhost:{port}` using the port specified in the config.
-In the production servers listed above, the server always sits behind an NGINX server which manages
+In the production servers listed above, the server should always sit behind an NGINX server which manages
 SSL, security, rate limiting etc. See [nginx.md](nginx.md) for configuration advice, including
-running several servers behind one front door.
+running several servers behind one front door. To use more than one CPU core for terminology on
+one machine, see [cluster.md](cluster.md): a master and several tx workers, behind nginx.
 
 ## Testing
 
@@ -274,6 +186,9 @@ Or run it inline:
 FHIRSMITH_DATA_DIR=/var/lib/fhirsmith fhirsmith
 ```
 
+For cluster mode (a master and tx-workers - see [cluster.md](cluster.md)), run `fhirsmith-cluster`
+instead of `fhirsmith`.
+
 ### Changing the Node.js version
 
 Some of FHIRsmith's dependencies (the SQLite drivers) are native modules, built for the
@@ -309,14 +224,6 @@ Available tags:
 - `vX.Y.Z`: Specific version (e.g., `v1.0.0`)
 - `cibuild`: Latest build from the main branch
 
-### Environment Variables
-
-| Variable | Description | Default |
-|---|---|---|
-| `FHIRSMITH_DATA_DIR` | Path to the data directory | `./data` |
-| `PORT` | Server port (overrides config) | from config.json |
-| `NODE_ENV` | Node environment | `production` |
-
 ### Windows Installation
 
 You can install as a windows service using [windows-install.js](utilities/windows-install.js). You might need to
@@ -420,7 +327,7 @@ or do it via a PR
    ./release.sh X.Y.Z
 ```
 
-   `gr.sh` checks that the release is ready - on `main` and pushed, the three versions in
+   `release.sh` checks that the release is ready - on `main` and pushed, the three versions in
    `package.json` and `package-lock.json` match, `CHANGELOG.md` has a dated section with the
    conformance statement, and `test-cases-report.json` passed, is from this version and is
    newer than the last code change - then submits the report to
@@ -448,7 +355,7 @@ or do it via a PR
 
 ## License
 
-[BSD-3](https://opensource.org/license/bsd-3-clause)
+[BSD-3-Clause](LICENSE) - see also [opensource.org](https://opensource.org/license/bsd-3-clause)
 
 ## Contributing