Configuration

Configuration Source Priority

The add-in resolves each setting by checking these sources in order, stopping at the first match:

1. Admin database Config profile — used once the admin database has been activated (see Moving Settings to the Admin Database).
2. notes.ini — the traditional Domino configuration file.
3. Environment variables — If a setting is not found in the database or notes.ini, the OS environment is checked.

Required settings have no built-in default. The add-in will refuse to start if any required setting is absent from all sources.

Required Settings

The following settings must be configured before the add-in will start:

Full Settings Reference

The Configuration form in file_admin.nsf is organized into tabs. Settings are grouped below to match that structure.

Basic tab

Authentication tab

Search tab

Limits tab

Pausing background work under load

Thumbnail generation and search indexing are optional work: generating a thumbnail decodes an image or drives a Collabora conversion, and indexing extracts a file's content and ships it to the search service. Both compete for CPU with the requests users are actually waiting on.

To keep the server responsive, both pause whenever CPU utilisation stays at or above HEAVY_LOAD_CPU_PERCENT (default 80) for at least five seconds. CPU is measured for the whole system, not just this task, so load from Domino itself (compact, updall, replication), from Collabora, or from any other process counts.

Nothing is lost, and nothing starves. Both queues are durable documents in the data database (ThumbnailRecord and SearchRecord notes), and while the server is busy the records are still created — only their processing waits. Specifically:

• A worker waits between records, never part-way through one, so a file is never left half-processed.
• It resumes within half a second of load dropping, so a lull is used immediately.
• If load never drops, it still lets one record through every 60 seconds. A server that is permanently busy therefore drains its backlog slowly, rather than never.

This is visible in the server log at debug level (it fires on every busy spell, so it is kept out of the normal log stream — raise the log level to see it when diagnosing why background work is lagging):

System under heavy load (94% CPU), pausing thumbnail generation
Load cleared (31% CPU), resuming thumbnail generation
Still under heavy load (91% CPU) after 60s, processing one thumbnail generation record anyway to keep the queue draining

Console commands are never refused: tell files search-sync and tell files rebuild-search-index always run, and the work they queue is then paced the same way as everything else.

In a container, CPU is measured against the container's own CPU limit when one is set (cgroup v1 and v2 are both supported), not against the host. This matters: a pod limited to 4 cores on a 64-core node can be fully CPU-throttled while the node as a whole looks idle. With no CPU limit set, the whole machine is measured, which is then the correct reading. The source is logged once, on the first sample:

Load is measured from the container's CPU quota
Load is measured from the host CPU (/proc/stat)

Set HEAVY_LOAD_CPU_PERCENT to 0 to disable the check entirely and restore the previous behaviour, in which background work always runs at full speed regardless of load. If CPU utilisation cannot be read at all, the check fails open — background work runs as before, and a warning is logged once.

Collabora tab

CLAMAV tab

Not in admin db

Public Link Permissions

The current value is reported to clients via the capabilities API:

GET /ocs/v1.php/cloud/capabilities

Moving Settings to the Admin Database

Once the service is running with notes.ini settings, you can migrate the configuration into the admin database using either of the following methods:

Method 1 — Domino console command

> tell files migrate-config

This copies all recognised FILES_* settings from notes.ini into the Config profile document in file_admin.nsf and removes them from notes.ini. From that point on, the admin database is the active configuration source.

Method 2 — Configuration form button

Open file_admin.nsf in a Notes client, navigate to the Configuration form, and click the Migrate Config button. The button issues the same tell files migrate-config command automatically.

After migration, edit settings directly in the Config profile document in file_admin.nsf. Changes take effect after reloading the add-in (tell files quit followed by load files), or on the next scheduled reload, depending on your environment.