Configure an instance

Most people only need the defaults, plus --public-url once Savorum is reachable from other devices. Look up a setting here when another page sends you, or when you hit a limit.

How settings work

Give each setting as a command-line flag or a SAVORUM_* environment variable. A flag wins over the environment, and both win over settings saved in the app. An invalid or unknown SAVORUM_* value stops Savorum from starting. savorum serve --help lists every flag and its default for your version.

All settings

Flag	Environment	Default
--database	SAVORUM_DATABASE	Required
--assets	SAVORUM_ASSETS	assets beside the database
--listen	SAVORUM_LISTEN	127.0.0.1:8080
--trusted-proxy	SAVORUM_TRUSTED_PROXIES	None
--display-name	SAVORUM_DISPLAY_NAME	No override
--public-url	SAVORUM_PUBLIC_URL	No override
--default-locale	SAVORUM_DEFAULT_LOCALE	No override
--default-measurement	SAVORUM_DEFAULT_MEASUREMENT	No override
--storage-access	SAVORUM_STORAGE_ACCESS	owner
--dns-sd	SAVORUM_DNS_SD	On
--auth-enabled	SAVORUM_AUTH_ENABLED	Off
--session-idle	SAVORUM_SESSION_IDLE	720h
--session-absolute	SAVORUM_SESSION_ABSOLUTE	4320h
--auth-providers-file	SAVORUM_AUTH_PROVIDERS_FILE	None
--token-default-days	SAVORUM_TOKEN_DEFAULT_DAYS	90
--token-maximum-days	SAVORUM_TOKEN_MAXIMUM_DAYS	365
--token-allow-nonexpiring	SAVORUM_TOKEN_ALLOW_NONEXPIRING	Off
--connect-origin	SAVORUM_CONNECT_ORIGIN	No override
--hosting-bootstrap-file	SAVORUM_HOSTING_BOOTSTRAP_FILE	Disabled
--idle-timeout	SAVORUM_IDLE_TIMEOUT	0 (disabled)
--maintenance-socket	SAVORUM_MAINTENANCE_SOCKET	Disabled
--print-recipe-limit	SAVORUM_PRINT_RECIPE_LIMIT	250
--bulk-limit	SAVORUM_BULK_LIMIT	100
--suggestion-limit	SAVORUM_SUGGESTION_LIMIT	50
--lookup-limit	SAVORUM_LOOKUP_LIMIT	200
--grocery-addition-limit	SAVORUM_GROCERY_ADDITION_LIMIT	200
--durable-byte-limit	SAVORUM_DURABLE_BYTE_LIMIT	0 (no limit)
--sqlite-memory-limit	SAVORUM_SQLITE_MEMORY_LIMIT	0 (set from memory)
--webhook-trusted-networks	SAVORUM_WEBHOOK_TRUSTED_NETWORKS	None
--webhook-failure-limit	SAVORUM_WEBHOOK_FAILURE_LIMIT	10

Some values have limits, and a value outside them stops startup:

• --bulk-limit: 1 to 500. Larger requests run as background jobs.
• --session-idle: 1 minute to 180 days. --session-absolute is at least the idle lifetime and at most 365 days.
• --token-maximum-days: at most 3650.
• --webhook-failure-limit: 1 to 100 failed deliveries in a row before a webhook pauses.
• --idle-timeout: 0, or at least one minute.

What some settings do:

• --trusted-proxy can be repeated. Separate environment values with commas. Any flag replaces the environment list.
• --dns-sd announces Savorum on your local network. Turn it off with --dns-sd=false.
• --webhook-trusted-networks lists private networks webhooks may reach. Without it, webhooks reach public addresses only.
• --idle-timeout stops Savorum after a quiet period, once background work finishes.
• --maintenance-socket takes an absolute path for a private local socket that keeps Savorum awake during maintenance.
• --connect-origin sets an optional Savorum Connect address. --hosting-bootstrap-file is for managed hosting and needs sign-in turned on.
• --durable-byte-limit caps how much your library may store, and --sqlite-memory-limit caps database memory. See Maintain storage and integrity.

Turn on authentication

Sign-in is off by default. To turn it on, create an administrator with savorum user create-admin, then start Savorum with --auth-enabled. Outside sign-in services are listed in a JSON file named by --auth-providers-file; see Single sign-on. Their secrets are read from separate files, never from saved settings, and never appear in any API response.

Set an external origin

Set --public-url to the exact address people use, with no path, query, or login details. Savorum only accepts requests for that address. Use it with a reverse proxy rather than listening on every address.

Protect stored data

By default, Savorum creates files readable only by its own user (0600 files, 0700 folders). This covers the database, photos and files, backups, and restored data.

Use SAVORUM_STORAGE_ACCESS=group only when several system accounts must share the data. It uses 0660 files and 0770 folders. Create a dedicated group, set ownership on the parent folders, use a setgid parent when several accounts create files, and pass the same setting to every server and maintenance command. Savorum changes modes but doesn’t guess ownership. Don’t use a broad login group or world-readable storage.

Two private folders sit beside the database file. <database>.webhook-secrets holds webhook signing keys and isn’t in a plain backup, so back it up with the same care. <database>.automation-artifacts holds export files made by jobs, deleted 24 hours after each job starts.

Set up PDF and photo import

Importing a PDF, a scan, or a photo needs Poppler and Tesseract on the server, plus a /bin/sh that supports ulimit. This works on Linux and macOS. A PDF that already contains text doesn’t need Tesseract.

brew install poppler tesseract           # macOS
apt install poppler-utils tesseract-ocr  # Debian or Ubuntu

The standard container image has neither these tools nor a shell. Use the document-tools image instead.

Each file can be up to 32 MiB, and a PDF up to eight pages. Savorum reads one file at a time and gives it 20 seconds. A second import while one is running is refused, not queued.

On Linux, Savorum limits each tool’s memory. macOS doesn’t allow that, so on an untrusted or shared Mac, set a memory limit for the host or container.

Printing large books

A printed document holds at most 250 recipes by default; change it with --print-recipe-limit. If a print fails with HTTP 413, the document is too big for the server’s memory. Print fewer recipes at once, or give the server more memory.

Savorum uses up to 70% of the server’s or container’s memory, unless you set GOMEMLIMIT. As a rough guide for one document:

Server memory	Recipes in one document
512 MB	about 70
1 GB	about 200
2 GB or more	the default 250

Long recipes and many photos need more. Savorum prints one document at a time, with up to two more waiting for as long as 90 seconds. Raising the recipe limit adds no memory.

The first print after each start prepares the typesetter, which takes time and memory. Savorum caches that work under XDG_CACHE_HOME (or ~/.cache). On a read-only system, set XDG_CACHE_HOME to a writable folder that belongs to the Savorum user and that no other user can write to.

Next: Single sign-on, if you want people to use an existing sign-in service. Otherwise, Maintain storage and integrity.