Settings reference

This reference is generated from the checked-out server’s boot settings and registered module settings. It describes source defaults, not your running server’s values or a verified release. Internal state is excluded. Dedicated account, household, AI policy, and connection screens also store preferences outside this registry; follow configuration and AI setup for those.

How to read this reference

• Environment values take priority over saved values, then defaults. A value supplied by the environment locks the corresponding setting in the app. An empty environment variable counts as unset; removing an override can reveal an older saved value.
• Environment only settings require recreating the container after configuration changes. Other server settings belong to Settings → This server; household settings require a household owner or admin.
• Unset means no declared value. The description may explain a runtime fallback. Docker and Compose can override these defaults: for example, the image sets its data directory, version, and installation method.
• Switch environment values accept true, 1, yes, on or false, 0, no, off, ignoring case. Lists use commas between entries. Choices use the listed values. Invalid values are rejected; boot errors name the environment variable.
• Secret values are never included here. Back up the server secret with the data, and keep credentials out of logs and issues.

Compose variables such as MERRAN_PORT, MERRAN_IMAGE, and TZ are deployment controls, not entries in this server registry. See configuration. Enabling a module does not supply its dependencies or credentials. Read AI privacy before enabling external processing.

server.port

The port Merran listens on.

• Scope: server (environment only)
• Type: number
• Default: 3000
• Environment: PORT

Source definition

server.logLevel

How much goes in the log. debug helps with troubleshooting.

• Scope: server (environment only)
• Type: choice
• Default: info
• Environment: MERRAN_LOG_LEVEL
• Choices: fatal, error, warn, info, debug, trace, silent

Source definition

server.logFormat

auto is readable lines in a terminal and JSON everywhere else.

• Scope: server (environment only)
• Type: choice
• Default: auto
• Environment: MERRAN_LOG_FORMAT
• Choices: auto, pretty, json

Source definition

server.dataDir

Where Merran keeps its files, and its SQLite database when there’s no Postgres.

• Scope: server (environment only)
• Type: text
• Default: data
• Environment: MERRAN_DATA_DIR

Source definition

server.databaseUrl

A Postgres address. Leave it unset to use SQLite.

• Scope: server (environment only)
• Type: text
• Default: Unset
• Environment: DATABASE_URL

Source definition

server.secret

Signs sessions and seals saved keys. Unset: made once and kept in the data folder.

• Scope: server (environment only)
• Type: secret
• Default: Unset
• Environment: MERRAN_SECRET

Source definition

server.publicUrl

The address people use to reach Merran, like https://merran.example.com.

• Scope: server (environment only)
• Type: text
• Default: Unset
• Environment: MERRAN_PUBLIC_URL

Source definition

server.trustedProxies

Proxies in front of Merran whose X-Forwarded-For is believed: addresses or ranges, separated by commas (“172.16.0.0/12, 127.0.0.1”).

• Scope: server (environment only)
• Type: list
• Default: []
• Environment: MERRAN_TRUSTED_PROXIES

Source definition

server.version

The release this is: the Docker image sets it. From source, it’s the server package’s version.

• Scope: server (environment only)
• Type: text
• Default: Unset
• Environment: MERRAN_VERSION

Source definition

server.installMethod

How Merran was installed. The Docker image sets it.

• Scope: server (environment only)
• Type: choice
• Default: source
• Environment: MERRAN_INSTALL_METHOD
• Choices: source, docker

Source definition

ai.anthropicKey

A Claude key for the server, for the households the AI policy covers. Keys can also be added in Settings.

• Scope: server (environment only)
• Type: secret
• Default: Unset
• Environment: MERRAN_ANTHROPIC_API_KEY

Source definition

ai.openaiKey

An OpenAI key for the server, for the households the AI policy covers. Keys can also be added in Settings.

• Scope: server (environment only)
• Type: secret
• Default: Unset
• Environment: MERRAN_OPENAI_API_KEY

Source definition

ai.googleKey

A Gemini key for the server, for the households the AI policy covers. Keys can also be added in Settings.

• Scope: server (environment only)
• Type: secret
• Default: Unset
• Environment: MERRAN_GOOGLE_API_KEY

Source definition

video.enabled

Import recipes from TikTok, YouTube, Instagram and Facebook links. Needs yt-dlp and ffmpeg, which come with the Docker image, and AI.

• Scope: server
• Type: switch
• Default: true
• Environment: MERRAN_VIDEO_IMPORT

Source definition

video.autoUpdate

Keep yt-dlp up to date, at start and weekly: it breaks when sites change, and is fixed within days.

• Scope: server
• Type: switch
• Default: true
• Environment: MERRAN_YTDLP_AUTO_UPDATE

Source definition

video.ytDlpPath

Where yt-dlp is. Without it, Merran looks in its data folder’s tools folder, then on the PATH.

• Scope: server (environment only)
• Type: text
• Default: Unset
• Environment: MERRAN_YTDLP_PATH

Source definition

video.ffmpegPath

Where ffmpeg is. Without it, Merran looks in its data folder’s tools folder, then on the PATH.

• Scope: server (environment only)
• Type: text
• Default: Unset
• Environment: MERRAN_FFMPEG_PATH

Source definition

video.cookiesFile

A cookies.txt from a browser, for sites that want a signed-in session (often Instagram). Without it, Merran uses cookies.txt in its data folder, if there is one.

• Scope: server (environment only)
• Type: text
• Default: Unset
• Environment: MERRAN_YTDLP_COOKIES

Source definition

nutrition.usdaKey

A USDA FoodData Central key for calculating nutrition from ingredients. Without one, AI estimates require configured AI access.

• Scope: server
• Type: secret
• Default: Unset
• Environment: MERRAN_USDA_KEY

Source definition

sites.enabled

Read recipe sites’ feeds in the background, for following sites and starter collections: the suggested sites and any a household follows, every few hours, as Merran and following robots.txt.

• Scope: server
• Type: switch
• Default: true
• Environment: MERRAN_RECIPE_SITES

Source definition

photos.enabled

Enable optional AI photos for recipes without a photo. Requires eligible OpenAI or Google access; provider charges vary. Generated photos never replace a real photo.

• Scope: server
• Type: switch
• Default: false
• Environment: MERRAN_AI_PHOTOS

Source definition

photos.auto

Make one by itself for each recipe added without a photo (typed in, read from text, or from the assistant). Never for a whole library moved in at once.

• Scope: server
• Type: switch
• Default: true
• Environment: MERRAN_AI_PHOTOS_AUTO

Source definition

photos.style

How the household’s AI photos look, all alike, so the library looks like one cookbook.

• Scope: household
• Type: choice
• Default: marble
• Environment: None
• Choices: marble, rustic, bright, moody

Source definition

voice.provider

Who reads cook steps aloud: the device, Kokoro, or OpenAI. OpenAI requires eligible AI access and incurs provider charges. Unset: Kokoro when its address is configured, otherwise the device.

• Scope: server
• Type: choice
• Default: Unset
• Environment: MERRAN_VOICE
• Choices: device, kokoro, openai

Source definition

voice.kokoroUrl

Where Kokoro answers, like http://kokoro:8880. It may be on the home network.

• Scope: server
• Type: text
• Default: Unset
• Environment: MERRAN_KOKORO_URL

Source definition

voice.kokoroVoice

Kokoro’s voice: af_heart unless another is picked.

• Scope: server
• Type: text
• Default: Unset
• Environment: MERRAN_KOKORO_VOICE

Source definition

voice.openaiVoice

OpenAI’s voice: marin unless another is picked.

• Scope: server
• Type: text
• Default: Unset
• Environment: MERRAN_OPENAI_VOICE

Source definition

stores.krogerClientId

Your Kroger developer app’s client ID, from developer.kroger.com: for Kroger’s stores (Fry’s, Ralphs, King Soopers…), their products, prices and sales, and sending a list to the cart.

• Scope: server
• Type: text
• Default: Unset
• Environment: MERRAN_KROGER_CLIENT_ID

Source definition

stores.krogerClientSecret

Your Kroger developer app’s client secret.

• Scope: server
• Type: secret
• Default: Unset
• Environment: MERRAN_KROGER_CLIENT_SECRET

Source definition

stores.walmart

Experimental: Walmart through Merran’s browser extension, in each person’s own Walmart tab. It finds each thing on the list, Merran picks a product, and it fills their Walmart cart. It stops at Walmart’s check that it’s a person and asks them, and it may need fixing whenever Walmart changes its site.

• Scope: server
• Type: switch
• Default: false
• Environment: MERRAN_WALMART

Source definition

stores.yours

The stores the household shops at, by key (“costco”, “target”), for Find on the list. Its Kroger store, and Walmart when the server has it on, count without being here.

• Scope: household
• Type: list
• Default: []
• Environment: None

Source definition

stores.leanOnSales

How much Fill the week and the weekly autoplan lean on what’s on sale at the household’s store: off, some, or lots. Only real deals count, not sales barely off the usual price.

• Scope: household
• Type: choice
• Default: some
• Environment: None
• Choices: off, some, lots

Source definition

stores.weeklyBudget

What the household means to spend on food in a week, in its store’s currency (dollars at Kroger). Fill the week and the weekly autoplan pick recipes that fit what’s left of it more often. Empty for none.

• Scope: household
• Type: number
• Default: Unset
• Environment: None

Source definition

errorTracking.dsn

Where to send errors: the DSN from Sentry, GlitchTip or Bugsink. Unset, errors stay in the server’s log.

• Scope: server
• Type: text
• Default: Unset
• Environment: MERRAN_SENTRY_DSN

Source definition

errorTracking.environment

The environment errors are filed under, to tell servers apart.

• Scope: server
• Type: text
• Default: production
• Environment: MERRAN_SENTRY_ENVIRONMENT

Source definition

errorTracking.sampleRate

The share of errors to send, from 0 (none) to 1 (all).

• Scope: server
• Type: number
• Default: 1
• Environment: MERRAN_SENTRY_SAMPLE_RATE

Source definition

telemetry.enabled

Send the Merran project an anonymous summary once a day. off turns it off for good.

• Scope: server
• Type: switch
• Default: false
• Environment: MERRAN_TELEMETRY

Source definition

updates.check

Check GitHub every six hours for a newer release and show its notes to the server administrator. This does not install updates. GitHub receives the network request; see the privacy guide.

• Scope: server
• Type: switch
• Default: true
• Environment: MERRAN_UPDATE_CHECK

Source definition

Next steps

Use troubleshooting for startup errors and locked settings, household roles for access rules, and updating, backups, and recovery before changing the installation.