Configuration reference

This page is for administrators. It lists every setting Libris reads: the environment variables in .env, and the settings an administrator can change at run time from Settings in the web interface. For each one you will find its default, what it does and when you would change it.

If you are installing Libris for the first time, you do not need any of this yet: scripts/setup.py (run by the installer) writes a working .env. Start with the Docker guide and come back here when you want to open Libris to your network, tune limits or change a default.

How configuration works

• .env is the only file you edit. It sits next to docker-compose.yml, is created by python3 scripts/setup.py from .env.example, and is read by the api, worker and migrate containers. Keep it private (mode 0600) and never commit it.

• Names are case-insensitive, but this page uses the upper-case form found in .env.example. A variable that is absent from .env takes the default shown here.

• Apply a change by recreating the containers:

  docker compose up -d --no-build --wait
  

  Every container reads the environment only when it starts. Run the same command with --profile codex if you use the Codex bridge.

• Invalid values stop the application. Each numeric setting has an allowed range (shown below). A value out of range, a SECRET_KEY shorter than 32 characters, or a METRICS_TOKEN / API_WEBHOOK_SECRET that is set but too short prevents the API and the worker from starting; docker compose logs api names the setting.

• Some settings can be overridden in the interface. Autopilot, budgets, webhooks, automatic recovery, the fair queue, SMTP mail, OpenViking memory and its cleanup, and SearXNG search have a page under Settings. There, a saved value wins over the environment. See Settings changed in the interface.

Installation and network

These variables are read by Docker Compose and the web server rather than by the application code.

Compose also sets DATABASE_URL, DATA_DIR=/data and TMPDIR=/data/tmp for the application containers; do not put them in .env for a Docker installation.

Security and access

Single sign-on has no environment variable either: an administrator gives the issuer, the client id and the secret in Réglages › Authentification unique, and Libris discovers the rest from {issuer}/.well-known/openid-configuration. The secret is encrypted with SECRET_KEY like every other secret; the address to declare at the provider is shown on the same screen and is built from the first ALLOWED_ORIGINS entry. An account opened by a provider has no Libris password and no Libris second step — both belong to the provider.

LDAP / Active Directory has no environment variable either: an administrator configures it in Paramètres › Authentification unique, card Annuaire LDAP / Active Directory, and the sign-in screen then offers a choice between the directory and a local Libris account. The step-by-step setup for OpenLDAP and Active Directory is in ldap.md. The settings are:

A directory account has no Libris password (password change, Mot de passe oublié, reset and local rename are refused), but keeps Libris’ second step: a directory only checks a password, so codes and security keys are offered and required as for a local account, and a recent proof (#102) is given with the directory password. Referrals are never followed, and failed directory sign-ins count in the same throttle as local ones for the same name.

There is no setting for the second step of a sign-in: each account turns it on for itself in Mon compte › Double authentification: a six-digit code from an authenticator application, a security key (WebAuthn), or both, plus ten single-use recovery codes. A key needs a secure context — HTTPS, or localhost — so an installation reached over plain HTTP on a LAN offers the authenticator only. An administrator may remove it from an account that lost its telephone — Réglages › Utilisateurs — which is written in the audit trail; nobody can turn it on in somebody else’s place. The automation API is untouched: a token is a secret of its own.

Sensitive account changes require a proof less than five minutes old, bound to the current browser session. This interval is deliberately not configurable and does not extend SESSION_DURATION_HOURS. A complete local sign-in counts immediately; WebAuthn must actually verify the user (PIN or biometrics), rather than just a touch. Existing sessions remain usable after an upgrade, but carry no fresh proof until confirmed.

For SSO administrators, qualify the identity provider before relying on account management: it must support a new authorization with prompt=login, max_age=0, and a signed, recent auth_time for the original issuer and subject. A normal SSO sign-in is not enough. The confirmation uses the same registered callback URL, fresh state/nonce and PKCE; the callback does not open a session and works without the SameSite=Strict cookie. The original window finishes the check with its own cookie. Test popups and the provider’s opener-isolation policy in the browsers used by administrators. Missing proof is refused without a silent-login loop or a fallback local password for an SSO identity; the account form keeps its draft.

Stop the API before applying or reverting this schema change. On downgrade, ordinary sessions and pending ordinary SSO sign-ins remain, but in-flight confirmation requests are removed: an older binary must never treat an account confirmation as a new login. Upgrading again does not resurrect proof timestamps. This guard covers account mutations and the personal recovery email, not every provider, SMTP or licence setting.

DEMO_MODE

Storage and paths

The defaults match the supplied image. Change them only when you run the backend outside Docker.

Sizing the connection pool. Every passage in flight renews its job’s lease, writes a checkpoint and reads its context, so it holds a connection for a moment, again and again. How many passages may be in flight is the sum of the providers’ Livres simultanés (max_concurrency) — not the largest of them, because books running on different providers add up — plus the loops that never stop: heartbeats, the outbox, mail, the licence. A pool smaller than that does not fail loudly: callers queue, wait DB_POOL_TIMEOUT, and are answered with an error that reads exactly like a database that is down.

Both processes say at start-up whether the pool covers the providers: db_pool=ok capacity=… providers=… in the log, or db_pool=undersized with what to raise. A log line reading status=pool_exhausted says the pool ran out; status=database_unavailable says the database itself did not answer. The defaults (40 + 40 per process) cover a busy installation with room to spare. Raising them means raising max_connections on the database service too — the supplied Compose file sets it to 200 for exactly this reason; otherwise the server becomes the next thing to run out.

Journal

Every service of the application (API, worker, migrations) writes its events to a file of its own in LOG_DIR, besides the usual container output; the production deployment script writes deploy.log there too. librisctl journal, or python -m app.journal inside a container, reads them as one chronology — see operations. The Compose file mounts LOG_DIR from the logs volume, or from the host directory named by LIBRIS_LOG_DIR (owned by uid 10001, mode 0700); the production scripts use $LIBRIS_PRODUCTION_BASE/logs (or LIBRIS_PRODUCTION_LOG_DIR).

Uploads and imports

A project archive that would exceed MAX_UPLOAD_MB or MAX_UNPACKED_MB is refused at export time, with the setting to raise, because it could not be imported again.

Translation pipeline

Autopilot

The autopilot takes a launched book from import to export without a human step; see autopilot. These variables are defaults that an administrator can override in Settings › Autopilot.

Change the thresholds when the autopilot accepts too much (raise them) or leaves too many decisions unmade (lower them).

Mail

Administrators can configure the transport in Settings → Email delivery without shell access or restarting the API and worker. Saved settings override the SMTP_* environment values below. The explicit off switch stops both queuing and sending; already queued messages remain in the outbox. Restore SMTP environment settings removes the override and applies the environment again.

The password is write-only and encrypted with the existing SECRET_KEY. Leave its field empty to keep it, or tick the explicit clear option to remove it. Back up SECRET_KEY along with the database; after a key change, enter the SMTP password again. TLS certificate verification cannot be disabled.

Queue a test email writes to the same outbox used by notifications and password recovery. A 202 answer means queued, not delivered: the worker must be running. Refresh the outbox to see pending, sending, sent and failed messages, attempts, retry time and a safe explanation. Neither the body, reset token, context nor raw server reply is returned. A repaired failed message can be queued again. Password reset messages cannot be retried here: request a fresh reset link instead of resending an expired one.

Multiple workers reserve each message atomically before delivery. A two-minute lease is renewed every forty seconds while a slow send is in progress; no SQL session is held during SMTP. A worker crash leaves a recoverable reservation, and eight interrupted attempts become a visible failure. Administrative retry resets the attempt budget but not ownership: a new opaque token fences out the old sender. No retry is allowed while sending. Delivery is at least once, not exactly once: SMTP acceptance followed by a crash before the local acknowledgement can cause redelivery. Retries retain their Message-ID, without assuming that the recipient deduplicates messages.

Stop old-version workers before upgrading: they do not recognize sending. Stop all mail workers before downgrading. The downgrade returns in-flight messages to the pending queue (or failed if their attempt budget was exhausted) before removing lease ownership; it deletes no mail. A message already accepted by SMTP can consequently be sent again after rollback.

Attachments are checked again against DELIVERY_MAX_MB immediately before MIME encoding, since a book can grow after it was queued. This check avoids expanding an oversized payload into base64; it does not itself bound the EPUB builder’s memory usage. Oversized attachments are visible as failures.

Libris tells a reader four things, and only four: a book is finished, a job stopped and is waiting for them, the licence’s word quota is running out, and the licence could not be renewed. Everything else it does in silence. A message is sent when something ended or is about to stop, never when something merely began — nobody wants a mail per passage, everybody wants one when the book is done.

Silence is the default. An account with no address receives nothing, and an installation upgrading to this version starts silent: a reader has to give an address, in My account › Notifications, and may turn off each kind and choose French or English. Nothing is sent from inside a request either: a message is written to email_outbox in the same transaction as the thing it announces, and the worker drains the queue, waiting a minute, then two, then four, up to six hours, and giving up after eight attempts.

Submission is authenticated to a real mail server. An anonymous relay is refused by half the world, and a notification that lands in a spam folder is a notification that was not sent.

Both TLS modes verify the server certificate and its host name before authentication or mail is sent. For a private certification authority, install its trust chain in the container’s trusted certificate store. A self-signed, expired or mismatched certificate is an error to correct at the mail server or in the trust store, not a reason to disable verification. A failed STARTTLS upgrade never falls back to sending credentials in clear text.

Where a reader’s own finished books are sent is set per account, in My account › Notifications: an address of its own, because a Kindle address is not a mailbox anyone reads. Setting it is the only opt-in there is — there is no kind to turn off, and an empty address sends nothing.

Licence

A licence sells accounts and machines. Accounts are the people who may sign into the installation. Creating an account past that number is refused — and only that: signing in, working, reading and exporting are never touched, because a licence that shrinks must not lock anyone out of the installation they are working in. Paramètres › Utilisateurs (Settings › Users) shows how many seats are held of how many. Machines are the installations the key may be activated on at once: 2 for the trial, 3 for Personal, 5 for Studio, 10 for Pro. When they are all taken, activating one more releases the oldest, provided it has held its place for at least 7 days; otherwise the activation is refused (move_too_soon). Release this machine in Settings › Licence frees a place at once — the thing to do before a move.

The words of the quota cycle — or of the calendar month with a licence server that predates cycles — reach the licence server with the heartbeat every LICENCE_HEARTBEAT_HOURS, and now also when a job ends — one call per job, never per passage, so the number an editor reads is at worst one book behind rather than an hour.

The quota renews on the subscription’s anniversary, not on the first of the month: a licence sold on the 12th starts a new quota on the 12th of every month (one begun on the 31st renews on the last day of shorter months). The licence server names the cycle in the certificate — its bounds, the plan’s allocation, and what the previous cycle overran, which it takes from this one, once. Libris counts its words in that cycle, reports the last words of an ended cycle to that cycle, and shows the date of the next quota in Settings › Licence. With a licence server that predates cycles, nothing changes: the calendar month, no carry-over.

A book is counted as soon as it is added, not as it is translated: all of its words, at the import, even if it is deleted afterwards without being translated. This holds for every road (import assistant, automation API, MCP, source watches, archive restore, second language) and for every chapter added or replaced later (only its new passages). A book is accepted while its words fit in what the cycle has left plus the margin LICENCE_QUOTA_OVERRUN_WORDS; beyond, it is refused whole (402 licence_quota_insufficient) and nothing is counted. Translating it, launching it again or redoing a passage then costs nothing more, even once the quota is reached; only a provider comparison, which calls the models on top, is still counted apart. Books added before this rule (0.16.4 and earlier) keep being counted as before, passage by passage as they are translated: nothing is counted again at the upgrade, the counter goes on from the number it had.

Libris is licensed software. An installation activates once with the key its reader bought, in Settings › Licence, and from then on runs on a certificate the licence server signs and renews every LICENCE_HEARTBEAT_HOURS (every hour by default). The certificate is what decides — not a setting and not the reply that carried it — and it is worth three days (72 hours, set by the licence server), so an outage at the licence server never interrupts anyone’s reading; a revocation stops the installation at the next renewal it manages to make. What is refused without a valid licence is the work that costs words — a launch, and every model call of a job already running, which pauses with stop_reason = licence and resumes once the licence allows work again. Everything already produced stays readable, exportable and deletable: a reader locked out never loses a book.

A revocation is the only kind of answer that takes the certificate away. Four refusals stop an installation — the licence is revoked, suspended, expired, or the server does not know the key — and anything else the licence server may answer, including a request it did not understand, counts as an outage: the certificate in hand keeps its three days, the reason is shown in Settings › Licence, and the next renewal tries again. A version of Libris newer than the licence server it calls must never be able to stop a licensed reader.

What this installation signs. At its first activation Libris draws an Ed25519 pair, keeps the private half encrypted with SECRET_KEY alongside the licence key, and sends the public half. Every report afterwards carries a counter, this machine’s clock and a signature over the whole report, so that what the licence server records cannot be forged by a third party nor replayed. Nothing to set up: an installation that holds no pair yet enrols one the next time it activates, and one whose key the server does not know activates again on its own rather than waiting for somebody. A reader who modifies their own copy can of course read that key out of their own database — this makes a report trustworthy against a third party, not against its owner.

The fingerprint sent to the licence server has two halves: a hash of the host’s machine-id, which changes when the reader changes machine and survives a redeployment, and an identifier Libris drew at its first start, which follows a restored backup. A container must be given the host’s machine-id — /etc/machine-id:/etc/machine-id:ro, as the Compose file does — or every recreation looks like a move to another machine and Libris falls back on a weaker fingerprint of its own.

What a plan grants

The certificate carries what the licence’s plan grants, and Libris applies it as it stands in the certificate, never from a setting:

Settings › Licence shows the plan, the words of the cycle and, for each right, whether it is included. The automation API and sharing come with the Studio and Pro plans, not with the trial nor the Personal plan. A certificate from a licence server that predates these rights does not name them, and keeps what it always allowed. The words, machines, accounts and prices of each plan, and the trial, are on libris-translate.com: the licence server grants them, the website publishes them, and this documentation does not repeat the numbers.

Perpetual certificate (end of the publisher’s activity)

If the publisher of Libris ends its activity, the licence server stops. Before it does, every valid licence receives by email a perpetual certificate (dev/libris-licence#29): signed with the same key as the hourly one, with no end date, no machine, and no word limit (quota.words = 0). It is bound to the licence key instead: its key_sha256 is the SHA-256 of the key as the licence server writes it (LIB-XXXX-XXXX-XXXX-XXXX), so the certificate alone is worth nothing, and with the key it works on any installation — a reinstallation, a new machine or a restored backup included.

Install it once, as an administrator:

• Settings › Licence › Perpetual certificate: paste the certificate (the line breaks and indentation of the letter do not matter) or choose the .libris-certificate file, and give the licence key unless the installation already holds it — in any case, with or without dashes;
• or from a shell, in the API container: docker compose exec -T api python -m app.licence.perpetual < licence.libris-certificate (the key must be saved already, or exported as LIBRIS_LICENCE_KEY and passed with docker compose exec -T -e LIBRIS_LICENCE_KEY api …; exit 0 installed, 1 refused);
• or through the API: POST /api/settings/licence/certificate with {"certificate": "…", "key": "…"} (administrators; 422 with invalid_certificate, key_required or key_mismatch).

The installation is written to the journal (licence=perpetual_installed). From then on Libris never calls the licence server again — no renewal, no report, no release — and no answer from anybody at its address can take the certificate away; Settings › Licence reads « Perpetual licence (the publisher has ended its activity) », with no end date and no renewal button. The words of each month are still counted locally, for the statistics, without any limit. Accounts, the automation API and sharing follow the certificate’s features exactly as with the hourly certificate; instances cannot be checked any more and is only indicative. Activating another key remains possible and replaces the perpetual certificate — keep the letter with the key.

A Libris published before this change refuses this certificate: update while the registry is still open (six months after the certificates are sent, the letter gives the date). The hourly certificate (v: 1) is unchanged: without an end date it is still an expired one.

Currency

The installation counts in one currency, chosen in Settings › Budgets: provider prices are entered in it, every cost computed from them is in it, and every amount the interface shows carries its symbol. Changing it states what the stored numbers are — it does not convert them.

A price list in another currency may be entered as it stands: the price fields carry a currency of their own, and the two prices are converted once, on saving, at the European Central Bank’s daily reference rates. They are fetched by the worker a few times a day (no account, no key, no setting), kept with the date they carry, and used for nothing else. An installation with no outbound access never fetches any: its own currency is then the only one offered, and nothing else changes.

Cost budgets

Spending caps, in the currency the installation counts in; see the user guide and the API reference. A book may have its own cap and an API token its own; these variables are the defaults that an administrator can override in Settings › Budgets.

Work window and daily ceiling

A fair queue knows how to order work; it did not know how to wait. Models are cheaper and less busy at night, electricity often is too, and somebody translating a five-hundred-chapter serial would rather it ran between one and seven than while they are using the machine. A book budget also stops one book, and nothing stopped an installation from spending a month’s worth in an afternoon because four volumes were launched together.

Both live in Settings › Budgets, in the Plage de travail et plafond du jour card; there is no environment variable, because both are decisions somebody changes with the seasons rather than at installation time. Off by default.

• The window is read on the server’s local clock. One that crosses midnight is the ordinary case: 01:00 to 07:00 means the night. A window whose two ends are equal, or that cannot be read, never stops anything — a misconfigured setting must not be a reason to refuse work.
• The ceiling is what the day may cost across every book, in the accounting currency. 0: none.

At a daylight-saving change, the next opening is a real instant: the repeated autumn hour may open the window a second time; a missing spring opening advances to the first existing minute inside the window. If the whole window is skipped, work waits until the following day’s opening. The ceiling counts token consumption at each call’s recorded price per million, since local midnight, not the sum of the provider’s price labels. Imported prices are already expressed in the installation’s single accounting currency; no live exchange-rate conversion happens here.

Neither interrupts anything brutally. Outside the window, or over the ceiling, the queue picks up nothing new, and a job already in flight is deferred at its next model call: it goes back to waiting with the next opening as its next_attempt, which is the mechanism retries already use, so it starts again on its own with nothing to click. A job the licence guard pauses needs a person; this one does not, because nothing is wrong. Its reason is window, and its message says when it comes back — “paused” without a time reads as broken.

Automation API

Limits of the automation API (/api/v1), used by scripts and other applications with API tokens. See the API reference.

Fair queue

Jobs are not started oldest first: the worker takes them by priority, then from the account with the fewest jobs running, in turn between accounts (see architecture). These variables are defaults that an administrator can override in Settings › Queue, where quotas can also be set per account.

Webhooks

Webhooks notify an integration when an API request finishes. They are off until at least one host is allowed. These variables are defaults that an administrator can override in Settings › Automation API.

Nextcloud / WebDAV connections

Each account may save connections to Nextcloud, ownCloud, a NAS or any WebDAV server (My account › Nextcloud / WebDAV connections), to import sources from it and to send finished books to it. The connector is an outgoing HTTP client aimed at an address people type, so it is off until an administrator lists the servers it may reach — as with SOURCE_WATCH_HOSTS, an installation upgrading to this version reaches nothing. These are installation settings (environment only).

Whatever these allow, the client keeps the rules of the webhooks and watched sources: the name is resolved once per call and the connection goes to the address checked (no DNS rebinding), the proxy variables of the server are ignored, a redirection is followed only to the same scheme, host and port (never elsewhere, so the credentials never leave the server they were typed for), and what is read is bounded — MAX_UPLOAD_MB for a file, like a file sent from the browser, a few megabytes for a folder listing. Passwords are encrypted with SECRET_KEY like providers’ keys, never returned by the API and never logged; after a SECRET_KEY change the interface asks for them again. Sending a book is queued for the worker with the retries of the library publication; a destination folder that does not exist is created (MKCOL), inside the connection’s address only. A connection may also receive every finished book of its account automatically (an option of the connection, off by default): nothing to configure on the installation beyond WEBDAV_HOSTS.

Memory and web search

Codex bridge

Used only by the optional Codex · ChatGPT account provider; see Codex.

Quality judge

A model of another provider that reads each finished passage and has its errors corrected; see Quality judge. Settings › Autopilot and a book’s settings override the variable.

Server resources

Data retention

The worker cleans up diagnostic data once at start-up and then every hour. 0 disables a rule. What each rule keeps, and how to measure it before applying, is explained in operations.

Settings changed in the interface

Administrators can change the following without restarting anything, from Settings in the web interface (or the matching API route, with an administrator session). The new value applies to the next decision the worker makes.

Other Settings pages (LLM providers, Prompts, Users, API tokens) hold data that exists only in the database; they have no environment equivalent.

Which value wins

From strongest to weakest:

1. The launch or request itself, e.g. "autopilot": false, "final_review": false, analysis_mode or threads in a launch or an API request.
2. The volume’s own settings: its autopilot switch, fallback providers, passage size, review mode, analysis mode, passages worked on at once and cost budget.
3. A value saved in Settings.
4. The environment variable in .env.
5. The built-in default shown on this page.

Details per page:

• Autopilot, Budgets and webhooks show the effective values next to the environment values. Go back to the environment values (DELETE) forgets everything saved on that page. Fallback providers are saved as provider ids; an unknown name is refused, and a provider deleted later is skipped.
• The global webhook secret entered in the interface is stored encrypted with SECRET_KEY and never shown again. It wins over API_WEBHOOK_SECRET; Forget the secret saved here falls back to the variable. If SECRET_KEY changed and the saved secret cannot be read, the variable is used.
• Automatic recovery shows the delay in force, the value of PROVIDER_RECOVERY_BASE_SECONDS and whether the delay was saved here (badge Delay saved here or Environment delay). Go back to the environment delay (DELETE) forgets the saved delay; the variable applies again to the next retries.
• Queue shows the values in force next to the environment values. Per-account rows override the installation’s quotas for one account (empty: the installation’s value; 0: no limit for that account) and may allow it to ask for High priority, which is otherwise reserved to administrators. An API token can have lower limits of its own (see API tokens). Go back to the environment values (DELETE) forgets the page, per-account rows included.
• Memory · OpenViking overrides the environment field by field. A key saved there is encrypted with SECRET_KEY; if it can no longer be read, OpenViking search is turned off and translation continues with the internal memory.
• OpenViking cleanup shows the switch in force, the value of OPENVIKING_CLEANUP_ON_DELETE and whether the switch was saved here. Go back to the environment value (DELETE) forgets it. The switch applies to the next deletions; cleanups already queued still run. Blocked counts cover the entire queue; an administrator can retire a pending cleanup after a root change without deleting its documents. The independent daily orphan scan is off by default and never removes anything. See OpenViking cleanup.
• SearXNG replaces the environment completely once saved: the saved URL and switch are used, even if SEARXNG_URL is set.