Configuration

The server is configured with environment variables; there is no configuration file. Most installations need none of them. Settings per tenant, such as retention or sync intervals, are made in the application.

With Docker, pass a variable with -e NAME=value, or under environment: in a Compose file.

Server

Variable	Default	Description
`COMPANION_DATA_DIR`	`/data` in the image	The data directory. See Backup for what is in it.
`COMPANION_ADDR`	`:8080`	HTTP listen address. Always open.
`COMPANION_TLS_ADDR`	`:8443`	HTTPS listen address. Listens only while a certificate is installed.
`COMPANION_TLS_CERT`		File with the PEM certificate chain. Set together with `COMPANION_TLS_KEY`. The files win over a certificate installed in the browser and are read again when they change. See HTTPS.
`COMPANION_TLS_KEY`		File with the unencrypted PEM private key.
`COMPANION_MASTER_KEY`		Base64 of a 32-byte key that encrypts tenant credentials. When unset, the key is generated as `master.key` in the data directory on first start. A key that does not match the database stops the server at start.

First administrator

Variable	Default	Description
`COMPANION_ADMIN_USERNAME`		Creates this administrator at start, but only while no user exists. Ignored afterwards.
`COMPANION_ADMIN_PASSWORD`		Its password, at least 8 characters.

You need neither: without them, the first page of a new installation creates the administrator. See Install.

Log sync and disk space

Retention, quotas, intervals and archiving are settings per tenant in the application: see Message Logs. Only what belongs to the server as a whole is a variable.

Variable	Default	Description
`COMPANION_ARCHIVE_DIR`		Directory that expired months of message logs are moved to, for tenants with “Archive expired periods” switched on. Mount a volume of its own there. When unset, such a tenant keeps its expired months and the application shows an alert.
`COMPANION_MIN_FREE_MB`	`1024`	Free space the data volume must keep. Below it, log sync pauses for every tenant until there is space again. Nothing is deleted. `0` turns the check off.
`COMPANION_EVICT_ON_LOW_DISK`	off	Below the minimum, also remove the oldest closed month of any tenant (archived if that tenant archives, deleted otherwise), even inside its retention. Without it, Companion never deletes a log before its retention is over, except for a tenant quota.

Values

Switches are on with 1, true, yes or on. Anything else, including an empty value, is off.
An invalid number is ignored with a line in the log, and the default is used.
An empty text value counts as unset.

Command line

The image’s program is /companion. Without arguments it runs the server. The other commands work on the data directory; user, tenant and tls are meant for a stopped server or a separate container on the same volume:

docker run --rm -it -v pizug_companion:/data pizug/companion:2.0.0 COMMAND

Command	Use
`user add`, `user list`, `user set-password`, `user delete`	Manage users without signing in. See Users & Roles.
`tenant list`	Tenants and their data directories.
`tenant rename --from OLD --to NEW`	Change a tenant key and move its directory. The server must be stopped.
`export`, `verify`	Consistent copies for a backup. See Backup.
`tls set`, `tls show`, `tls clear`	The stored HTTPS certificate. See HTTPS.
`healthcheck`	Exit code 0 when the local server answers. Used by the image’s health check.
`version`, `help`	The version, and this list.