Settings

A setting is a named value that changes what a server does, set with the settings command.

This page lists version 0.17.0 of the server, the newest release. An entry that names no version it was added in was in version 0.13.0.

settings list prints every setting your version has, its value, and where that value came from. The command acts on the server whose database its config file names. Learn more about how a command finds its server.

The server’s name is not a setting, because it is needed before there is a database to read: it is the name key in commentware.config.json.

Where a value comes from

A value stored with settings set wins, then the environment variable, then the shipped default. A variable set to the empty string counts as unset.

The variable settings list reads is the one in the shell you run it from. A server started elsewhere runs on the variables it started with. The unit service install writes keeps the variables of the shell that installed it. So list can name the shipped default while the server runs on a variable its unit holds, or name a variable your shell has that the server never saw.

A stored value is the same for both, and the server reads it each time it uses it. A changed variable reaches a server you started by hand when you start it again from a shell that has it. It reaches a service only when you run service uninstall and then service install from such a shell; restart keeps the unit as it is.

How a value is changed

settings set stores a value and settings unset removes it, so the variable or the default applies again:

commentware settings set screenshots off
commentware settings unset screenshots

set validates before it writes, so a value the server cannot use is refused when you type it rather than when something reads it.

hub-origin

Type: an http or https origin · Default: the hub origin the server ships with · Environment variable: PUBLIC_HUB_ORIGIN

Origin of the hub. Connection strings are built on it, and so are the links of a server whose own address is loopback.

Any other server builds the links it hands an agent, to a comment or to a document, on its own address: its publicOrigin, or else the address it binds. A server bound to every interface with no publicOrigin has localhost as its own address, so its links are built on the hub. Learn more about which site serves a comment link.

A server that belongs to a hub you host needs this set to that hub, or the connection strings it prints lead to the hub it ships with. A server set up by an install command from a hub other than the one it ships with already uses that hub: the commentware command the installer writes sets PUBLIC_HUB_ORIGIN to it when the variable is unset, and settings list then names the value environment, unless you stored a value. Set it on any other server:

commentware settings set hub-origin https://comments.example.com

A service takes its hub from the commentware command each time it starts, when the hub came from an install command. service install does not write that hub into the service, which makes it the one variable a service does not keep from the shell that installed it. To move the service to another hub, run the install command from that hub, then run commentware restart. A value stored with settings set wins over all of this.

If PUBLIC_HUB_ORIGIN is set in the shell that runs service install, service install writes that value into the service, and the service keeps it. A service that a version of Commentware before 0.14.0 installed has the hub from its install command written into it, and keeps it. To make that service take its hub from the commentware command, stop any server you started yourself with commentware stop, run commentware service uninstall, then run commentware service install in a shell where PUBLIC_HUB_ORIGIN is not set.

The extension does not use this setting.

screenshots

Type: on or off · Default: on · Environment variable: COMMENTWARE_SCREENSHOTS

Whether this server accepts new screenshots. Stored ones stay readable.

Off also stops the page text kept with each new comment. Learn more about what is kept about the page.

The sites screenshots command turns capture off for one site and leaves the rest:

commentware sites list
commentware sites screenshots app.example.com off

on there clears a site’s opt-out; it does not override the server. A server with screenshots off stays off everywhere. sites list marks which of the two applies to a site: off (this site) is turned back on with commentware sites screenshots <domain> on, and off (whole server) with commentware settings set screenshots on.

A domain can exist in more than one project. When it does, the command refuses rather than guessing, and prints the projects to choose between — pass --project.

resolved-purge-days

Type: a whole number of days, 0 or more · Default: 30 · Environment variable: COMMENTWARE_RESOLVED_PURGE_DAYS

A resolved thread is deleted, with its screenshots, once this many days have passed since it was resolved and, for an imported thread, since it arrived. 0 never deletes.

Learn more about the retention purge.

bundle-idle-days

Type: a whole number of days, 0 or more · Default: 7 · Environment variable: COMMENTWARE_BUNDLE_IDLE_DAYS

A document review with no revision and no comment for this many days ends, and its comments go with it. 0 never ends one.

This setting governs an experimental feature: it may change or be removed in any release.

Learn more about the retention purge.