Browse documentation

🧭 Start Here

Blackcap Overview ✨ Blackcap Feature Catalog 🤖 AI Features 🧱 Technology, Administration, and Reliability Installation First Run

📘 User Guides

Administration and Operations Platform Configuration Organization Configuration Email and Consent Management

🚀 Deploy Blackcap

Platform Stacks and Raspberry Pi Hardware Raspberry Pi Deployment Raspberry Pi Client Services GCP Deployment Packaged Blackcap deployment Application Updates After Your First Blackcap Login: Self-Hosted Setup Guide Blackcap Release Notes Environment Variables and Secrets Reverse Proxy and TLS Background Jobs and Schedules

🛠️ Administer Blackcap

Organizations Users, Permissions, and Authentication Configuration Workspace Backups and Restore Database Administration Regression Testing Performance and Job Status Audit, Access Activity, and Logging GeoIP and Access Location Data Retention and Purge Support Chat Administration Support Requests API Tester and Postman Instance Reporting Third-Party Packages and Attribution AI Provider Usage and Billing Portals Microwave Pie licensing for Blackcap Microwave Pie licensing for Blackcap

🍽️ Use Recipes

Recipes and the Recipe Library Recipe Import and Discovery Recipe Editing and Cache Artifacts Recipe Sharing Social Recipe Import AI Recipe Image Generation 🪄 Adapt Recipe and 🎲 Variations

📅 Plan Meals

Meal Planner

🛒 Use Shopping Lists

Shopping Lists and Shop a List External and Household Shopping 🔗 Chrome Extension Shop With

🧺 Manage Kitchen Inventory

🧺 Kitchen Inventory

🖥️ Use Displays

Displays and Connections Assigning and Scheduling Display Content Remote Pi Client E-Ink Rendering Menu Refresh and Rendering Noun Project Footer Images

🧑‍🍳 Cook with Let’s Cook

🧑‍🍳 Let’s Cook 🧑‍🍳 Let’s Cook Controls and Timers

🤖 Use and Administer AI

🤖 AI in Blackcap 🤖 AI Providers and Connections 🤖 AI Seeds and Usage Support Chat

🔗 Use the Chrome Extension

🔗 Blackcap Chrome Extension 🔗 Chrome Extension Recipe Capture 🔗 Chrome Extension Shop With 🔗 Chrome Extension Release and Privacy

🎮 Play Games

Games and trivia Bramble Harvest — Player Guide Flavor Lab — Player Guide

🔌 Integrations

Email Integration Cloud Storage Integrations Voice Assistants Shop With Integrations Authentication Providers

⚙️ Develop Blackcap

Application Architecture Database Service and Data Access SQLite and PostgreSQL Database Migrations Background Job Architecture Testing Games platform — current developer reference Bramble Harvest developer tools API Architecture Security and Organization Scoping UI, Icons, and Documentation Assets Blackcap-Safe Emoji Support Chat Architecture Extending Support Chat Support Chat Model Benchmark Documentation Standards Terminology

⚠️ Troubleshoot Blackcap

⚠️ Troubleshooting Licensing Troubleshooting Deployment Troubleshooting Display Troubleshooting Recipe Import Troubleshooting 🤖 AI Troubleshooting Backup Troubleshooting Database Troubleshooting Diagnostic Organization Clones Support Chat

Configuration Workspace

Audience: System Admin, Org Admin, Deployment Administrator, Developer, Support
Related documentation: Organizations, Users, permissions, and authentication, Environment and secrets, GeoIP and access location, Data retention and purge

Purpose

The Configuration workspace is Blackcap's canonical UI for runtime settings that belong to the platform or an organization. It replaces duplicated INI-only administration while preserving a small bootstrap configuration for values required before the database can be opened.

Configuration is organized by scope and stable responsibility, not by implementation history. Search can locate pages and settings across the workspace. Page bodies hydrate lazily so opening Configuration does not load every setting and provider panel at once.

On desktop, the hierarchy/editor area is sized from its viewport position so the domain list and selected configuration panel can use the available screen height independently. Transient save/error flash messages above the workspace are excluded from that steady-state height calculation, so saving a setting does not permanently shorten the editor.

Scope model

  • Platform settings affect the entire Blackcap installation and normally require System Admin permissions.
  • Organization settings affect the Active Organization and are available only when the current user has the corresponding organization permission.
  • Display geometry and display-specific behavior are managed on Display Details rather than the general workspace. Legacy display-width/height mappings remain only for compatibility.
  • Bootstrap/environment values are not normal runtime settings. Database connection strings, encryption keys, filesystem roots, early logging, and similar startup dependencies stay in environment files or deployment configuration.

Changing the Active Organization changes the organization pages being viewed and edited; it must never expose another organization's values by accidental fallback.

Permissions

The workspace hides pages the current user cannot view. Important permission families include:

Configuration area Typical permission
General platform settings system.configure
Platform AI ai.admin
Purge policy data_purge.configure
Platform authentication providers platform.auth_providers.view / edit equivalent
Platform support settings platform.support.configure
Organization Menu, rendering, and Noun footer menu.configure
Meal Planner meal_planner.configure
Household List shopping_lists.edit
Organization login providers organization login-provider permission
Backup backup.configure
Recipe and share settings recipes.edit
Other organization integrations connections.configure

A visible secret field should show only a masked or replacement state. The application must never return the existing plaintext secret to the browser.

Configuration pages

Platform pages

The current platform workspace includes Country Flags, AI, Authentication Providers, Certificates & Public Access, Database, Email, GeoIP / Access Location, Performance, Providers, Purge, Recipe Capture, Recipe Discovery, Runtime, Security, Shop With Providers, Slow Recipe Websites, Support, Voice Assistant Providers, and—on package-managed installations only—Updates. Some are custom panels because they manage provider records or complex behavior rather than a flat setting list.

Organization pages

The current organization workspace includes Backup, Cookbook Categories, General Rendering, Household List, Inventory, Login Providers, Meal Planner, Menu, Noun Project Footer, Recipe Info, Recipe Rendering, and Share. Organization selection is explicit.

Display configuration

Resolution, display type, linking, credentials, default content, and other display-record properties belong on Display Details. They are not duplicated as generic organization settings.

Resolution and storage

DB-backed settings are read through the centralized settings service. The service validates scope, type, choices, permissions, secret behavior, and fallback/default rules. Feature code should not read the settings tables directly.

The typical resolution order is the explicitly stored value for the required scope, then the registered/default value. Platform and organization values are not interchangeable: an organization value must not override a platform-only setting, and a platform value must not leak as an organization-owned record.

Configuration changes are audited. Backups and restores include durable scoped settings as appropriate; encrypted secrets follow the connection/secret handling rules and should not be copied into diagnostic clones.

Custom configuration panels

  • Platform AI manages AI providers, use cases, profiles, and AI Seeds policy through dedicated services.
  • Authentication Providers manages platform provider definitions; organizations separately enable allowed providers.
  • Shop With Providers manages retailer/provider definitions used by the Chrome Extension.
  • Slow Recipe Websites manages capture sites identified by performance thresholds.
  • Certificates & Public Access is available on package-managed and source installations. It controls the 1–90 day certificate-renewal warning window (14 days by default), shows non-secret public HTTPS/DNS status, and—when GoDaddy is configured and the privileged host helper is installed—can rotate a verified PAT or update its expiration date without storing the PAT in Blackcap settings or PostgreSQL.
  • Platform Updates appears only for package-managed installations and controls Manual versus Automatic update checks, the dependent opt-in to apply approved forward updates when Blackcap restarts, how many hours the recent service-start update notice remains visible, and how many recent entries appear in Update History. Downgrades remain manual.
  • Organization Cookbook Categories manages the organization’s stable recipe-category hierarchy, ordering, moves, and category assignment cleanup.
  • Organization Meal Planner manages meal slots and related behavior.
  • Organization Inventory includes Expiring Soon Warning for Full Inventory Tracking. It is an organization-scoped integer from 1–365 days, defaults to 7, and is evaluated against the organization's local calendar date whenever physical Package freshness status is derived. Changing it does not rewrite Package rows; warning state updates immediately.
  • Organization Login Providers controls which configured authentication providers are available to the organization.

Complete registered setting reference

The tables below are generated from CONFIG_SETTING_DEFINITIONS so this guide covers every registered flat setting. Custom panels listed above may have additional records managed by their own services. Internal/deprecated mappings are identified and are not normal workspace controls.

Platform settings

Alexa

Setting Key Type Purpose
Enable Alexa Custom Skill voice_assistant_providers.alexa.enabled boolean Allow Alexa account linking and skill fulfillment for Blackcap Voice.
Alexa OAuth Client ID voice_assistant_providers.alexa.oauth_client_id string Client ID configured in the Alexa skill account-linking settings.
Alexa OAuth Client Secret voice_assistant_providers.alexa.oauth_client_secret string (secret) Client secret configured in the Alexa skill account-linking settings. Stored encrypted at rest.
Alexa Skill ID voice_assistant_providers.alexa.skill_id string Alexa skill application ID, such as amzn1.ask.skill.... Used to reject requests for other skills.

Alexa OAuth

Setting Key Type Purpose
Allowed Alexa Redirect URLs voice_assistant_providers.alexa.allowed_redirect_urls textarea Paste the full Alexa Redirect URLs from the Alexa Developer Console, one per line. Leave blank to allow standard Alexa account-linking redirect URLs.
Alexa Access Token Seconds voice_assistant_providers.alexa.access_token_seconds integer Lifetime for access tokens issued to Alexa.
Alexa Refresh Token Days voice_assistant_providers.alexa.refresh_token_days integer Lifetime for refresh tokens issued to Alexa.
Alexa Authorization Code Seconds voice_assistant_providers.alexa.authorization_code_seconds integer Lifetime for one-time authorization codes during account linking.

Alexa Security

Setting Key Type Purpose
Verify Alexa Signatures voice_assistant_providers.alexa.verify_signature boolean Validate Alexa request signature certificate headers for production skill requests.
Allow Unsigned Alexa Debug Requests voice_assistant_providers.alexa.allow_unsigned_debug boolean Development-only bypass for signature validation. Keep disabled outside local testing.
Alexa Timestamp Tolerance Seconds voice_assistant_providers.alexa.timestamp_tolerance_seconds integer Maximum allowed Alexa request clock skew. Amazon guidance is 150 seconds.

Country Flags

Setting Key Type Purpose
Enable Country Flags access_activity.country_flags_enabled boolean Show compact country flag indicators in Admin UI access summaries. Icon Mode controls the preferred graphical style.
Country Flag Icon Mode access_activity.country_flag_icon_mode string (choices: svg, emoji, code) Use bundled SVG flag assets when available, emoji flags when requested, or country-code fallback for compact access-location indicators.

Certificates & Public Access

Setting Key Type Purpose
Certificate renewal warning days certificates.renewal_warning_days integer Number of days before the current HTTPS certificate expires when Blackcap should elevate a known renewal timer or DNS-credential problem into the high-priority System warning. Valid range 1–90; default 14.

Database

Setting Key Type Purpose
DB Provider database.backend readonly Startup-level database provider selected in [database] backend in the INI file. Change this in the INI/environment and restart Blackcap; it is shown here for clarity only.
Search Result Limit database.search_result_limit integer Default maximum number of rows returned by database browser searches.
Use SQLite Runtime database.use_sqlite_runtime boolean Legacy runtime toggle retained for rollback. Hidden from the generic Configuration UI because the active database provider is selected by [database] backend in the INI file.

Email

Setting Key Type Purpose
Email Sharing Enabled email.enabled boolean Enable outbound email features such as recipe sharing and support notifications when SMTP is configured.
SMTP Host email.smtp_host string SMTP server hostname used for outbound Blackcap email.
SMTP Port email.smtp_port integer SMTP server port used for outbound Blackcap email.
SMTP Username email.smtp_username string Username Blackcap uses when authenticating to the SMTP server.
SMTP Password email.smtp_password string (secret) Password or app password Blackcap uses when authenticating to the SMTP server. Stored encrypted at rest.
Use TLS email.use_tls boolean Use TLS/STARTTLS when connecting to the SMTP server.
From Address email.from_address string Email address used as the sender for outbound Blackcap email.
Email Brand Name email.branding_name string Text branding shown even when remote email images are blocked. Default: Blackcap by Microwave Pie.
Blackcap Email Logo URL email.blackcap_logo_url string Stable public HTTPS PNG URL for the Blackcap email header. Default: https://microwavepie.com/assets/blackcap-logo.png. Query strings and fragments are rejected to prevent tracking identifiers.
Microwave Pie Email Logo URL email.microwave_pie_logo_url string Stable public HTTPS PNG URL for the Microwave Pie email header. Default: https://microwavepie.com/assets/microwavepie-logo-192.png. Query strings and fragments are rejected to prevent tracking identifiers.
Email Website URL email.branding_website_url string Public HTTPS Microwave Pie or Blackcap website URL shown in the shared email footer.
Email Support URL email.branding_support_url string Public HTTPS support URL available to branded email templates.

GeoIP / Access Location

Setting Key Type Purpose
Enable GeoIP Lookup geoip.enabled boolean Enable optional local GeoIP lookup for access activity. Access is never blocked if lookup fails.
GeoIP Provider geoip.provider string (choices: none, maxmind) GeoIP provider. The supported local provider is the MaxMind-compatible MMDB reader.
MMDB Database Path geoip.maxmind_database_path string Local MaxMind-compatible country MMDB file path. DB-IP Lite MMDB files can also be used with this reader.
GeoIP Update Source geoip.update_source string (choices: dbip_lite, maxmind_geoipupdate, manual) Automatic updater source. DB-IP Lite downloads need no account. MaxMind geoipupdate requires /etc/GeoIP.conf credentials.
DB-IP Lite URL Template geoip.dbip_lite_url_template string Advanced: download URL template for DB-IP Lite country MMDB. Use {year_month} for YYYY-MM.
Show Country Flags geoip.show_country_flags boolean Show country flags on the login page and displays for troubleshooting. Country activity is still tracked when this is off.

Google Home

Setting Key Type Purpose
Enable Google Home voice_assistant_providers.google_home.enabled boolean Allow Google Home Cloud-to-cloud account linking and fulfillment for Blackcap display actions.
Google Home OAuth Client ID voice_assistant_providers.google_home.oauth_client_id string Client ID configured in the Google Home Cloud-to-cloud account-linking settings.
Google Home OAuth Client Secret voice_assistant_providers.google_home.oauth_client_secret string (secret) Client secret configured in the Google Home Cloud-to-cloud account-linking settings. Stored encrypted at rest.

Google Home OAuth

Setting Key Type Purpose
Allowed Google Home Redirect URLs voice_assistant_providers.google_home.allowed_redirect_urls textarea Paste the Google Home OAuth redirect URLs from the Google Home Developer Console, one per line. Leave blank to allow standard oauth-redirect.googleusercontent.com redirects.
Google Home Access Token Seconds voice_assistant_providers.google_home.access_token_seconds integer Lifetime for access tokens issued to Google Home.
Google Home Refresh Token Days voice_assistant_providers.google_home.refresh_token_days integer Lifetime for refresh tokens issued to Google Home.
Google Home Authorization Code Seconds voice_assistant_providers.google_home.authorization_code_seconds integer Lifetime for one-time authorization codes during Google Home account linking.

Updates

These settings are registered at platform scope but the Updates configuration page is exposed only when Blackcap is running from a managed package.

Setting Key Type Purpose
Automatic update checks updates.automatic_check_enabled boolean When enabled, consume Microwave Pie management-service update decisions from normal instance heartbeats and perform one fresh discovery check at each packaged service start. When disabled, only an explicit System Admin Check for Updates performs discovery.
Apply approved update on restart updates.auto_apply_on_restart boolean Requires Automatic update checks. During a Blackcap restart, perform one fresh pre-start check and automatically prepare/apply only an approved forward update through the independent updater before the application begins serving. Downgrades are never automatic.
Service-start update notification hours updates.service_start_notification_hours integer How long the green recent automatic-update notice remains eligible after a successful service-start update. Default 24 hours; 1–720. A newer successful update or restore suppresses the older notice immediately.
Update History display count updates.update_history_display_limit integer Number of recent package update/restore attempts shown in the System Update History pop-up. Default 10; 1–100. Host retention remains capped separately at 100 entries.

Performance

Setting Key Type Purpose
Performance Metrics Enabled performance.enabled boolean Record lightweight operational performance metrics for System Admin diagnostics.
Slow Request Threshold Ms performance.slow_request_threshold_ms integer Only request/page timings slower than this threshold are recorded, unless the route returns HTTP 500+.

Providers

Setting Key Type Purpose
Noun Project API Key provider.noun_project.api_key string Platform Noun Project API key used for icon lookups during menu and recipe enrichment.
Noun Project Secret Key provider.noun_project.secret_key string (secret) Platform Noun Project secret used with the API key. Stored encrypted at rest.
Dropbox App Key provider.dropbox.app_key string Dropbox app key used for Blackcap cloud backup account linking.
Dropbox App Secret provider.dropbox.app_secret string (secret) Dropbox app secret used for backup OAuth. Stored encrypted at rest.
Dropbox Redirect URI provider.dropbox.redirect_uri string Public callback URL registered with Dropbox for backup account linking.
Google Drive Client ID provider.google_drive.client_id string Google OAuth client ID used for Google Drive backup linking.
Google Drive Client Secret provider.google_drive.client_secret string (secret) Google OAuth client secret used for Google Drive backup linking. Stored encrypted at rest.
Google Drive Redirect URI provider.google_drive.redirect_uri string Public callback URL registered with Google for Google Drive backup linking.
Google OAuth Enabled provider.google_oauth.enabled boolean Legacy platform Google login toggle. Current login-provider enablement is managed on the Login Providers configuration page.
Google OAuth Client ID provider.google_oauth.client_id string Legacy Google sign-in OAuth client ID. Current provider credentials are managed on Authentication Providers.
Google OAuth Client Secret provider.google_oauth.client_secret string (secret) Legacy Google sign-in OAuth client secret. Stored encrypted at rest; current provider credentials are managed on Authentication Providers.
Instacart API Key provider.instacart.api_key string (secret) Platform API key provided by Instacart for an approved application. Leave blank when API access is unavailable.
Instacart Environment provider.instacart.environment string (choices: production, development) Shared Instacart API environment used by enabled organization connections.
Instacart API Base URL provider.instacart.endpoint_base_url string Shared API base URL override. Leave blank to use the default for the selected environment.
Instacart Impact Partner ID provider.instacart.impact_partner_id string Optional Impact affiliate partner ID provided for approved Instacart partner accounts.
Instacart Link Expiration Days provider.instacart.link_expiration_days integer Shared expiration window for generated Instacart shopping-list links.
Instacart Return Link URL provider.instacart.linkback_base_url string Optional shared URL back to Blackcap or your site shown from Instacart shopping-list pages.

Ingredients

Platform → Ingredients is the System Admin-owned canonical ingredient catalog. Blackcap keeps stable ingredient identities and attaches external source records rather than allowing a provider to become the canonical database. The first synchronization source is TheMealDB. Its ingredient rows and imagery are mapped to canonical Blackcap records, with source provenance retained for each mapping/image.

TheMealDB synchronization is a tracked background job. Source thumbnails are downloaded with bounded/time-limited requests, validated by Pillow, normalized to 96 × 96 while preserving aspect ratio, and cached under Blackcap runtime data so normal rendering does not depend on TheMealDB's CDN after synchronization. Missing/failed images do not fail the full catalog sync.

The default visual resolution order is cached TheMealDB image → emoji → existing cached Noun Project image → generic placeholder. No new Noun Project lookup is triggered by this feature. The administrative page exposes source attribution in thumbnail tooltips and persistent page-level TheMealDB attribution.

Canonical rows track manual overrides so provider refreshes preserve administrator display names, category changes, aliases, fallback emoji, preferred visual choice, and local active/inactive decisions. Missing provider rows are marked source-inactive rather than deleting the canonical ingredient. The page also shows normalized coverage from FoodKeeper Shelf Life and Ingredient Densities without forcing either to a one-to-one schema relationship.

Ingredient Densities

Platform → Ingredient Densities is a System Admin-only catalog used by Kitchen Inventory when recipe consumption and package capacity cross between volume and weight. It is platform data rather than organization settings. Each row contains an ingredient label, density in g/mL, aliases used for logical-ingredient matching, active state, and optional notes. The seed catalog includes common flours, sugars, fats/oils, syrups, dairy, soy sauce, oats, rice, cocoa, cornstarch, salt, and a required Water / default fallback row. The seeded all-purpose flour value is 0.507 g/mL; the fallback defaults to 1.000 g/mL.

Upgrades add missing Blackcap seed rows without overwriting edits to existing rows. Seeded canonical keys remain stable if their display labels are renamed; manually added rows follow their edited ingredient name. The fallback cannot be deactivated from Configuration. When no ingredient-specific row matches, Blackcap uses the active water fallback, records the fallback in quantity/forecast metadata, and caps runout confidence at low. Same-dimension conversions do not consult this catalog.

FoodKeeper Shelf Life

Platform → FoodKeeper Shelf Life is the System Admin-owned shelf-life catalog used by Full Kitchen Inventory Tracking to create one-time Estimated Best By dates for newly acquired physical Packages that do not already have a printed/manual date. The end-to-end Package decision flow is documented in Kitchen Inventory → How FoodKeeper estimation works.

The table is editable platform data. A System Admin can change the canonical ingredient key, aliases, Pantry/Refrigerator/Freezer planning days, active state, and notes, or add a Blackcap-specific manual row. Editing any imported row marks it customized, which gives the platform override precedence during matching and protects it from later USDA refresh replacement.

Matching precedence

Only active rows participate in automatic matching. Blackcap normalizes the Kitchen Inventory item's canonical/display name and evaluates matches in this order:

  1. exact canonical ingredient key;
  2. exact alias;
  3. exact FoodKeeper display name.

For two otherwise equivalent matches, Blackcap prefers a customized row, then a current usda_foodkeeper row, then a bundled usda_foodkeeper_fallback row. This lets an administrator correct or specialize USDA guidance without changing organization-level Inventory records.

USDA refresh and fallback lifecycle

Migration 249 seeds a small bundled usda_foodkeeper_fallback catalog so basic estimates can work before the first successful online refresh. Refresh USDA FoodKeeper then fetches the current English FoodKeeper JSON catalog and normalizes usable product rows into the platform table.

A successful refresh:

  • inserts new USDA rows and updates existing non-customized USDA rows;
  • preserves customized USDA rows exactly as platform overrides;
  • removes non-customized bundled fallback rows because the full USDA catalog supersedes them;
  • preserves any fallback row that a System Admin customized;
  • marks non-customized USDA rows that disappeared from the current upstream catalog inactive instead of deleting them, so the change remains reviewable and previously generated Package dates remain unaffected;
  • records the last successful refresh timestamp/count shown by the Configuration UI.

If the USDA response contains no usable shelf-life product rows, the refresh fails rather than replacing the catalog with an empty result.

Duration normalization

For each Pantry/Refrigerator/Freezer zone, Blackcap prefers a numeric FoodKeeper from date of purchase value when one is available; otherwise it uses the normal numeric storage-duration value. Numeric ranges use the upper boundary as the planning date. Weeks are converted to seven-day intervals, months to 30-day planning intervals, and years to 365-day intervals. Durations outside Blackcap's supported 1–3650-day range are not accepted for editable planning values. Non-numeric guidance remains visible in the catalog but is not converted into an automatic date.

The generated Package type is Estimated Best By. It is internal/display-only: Admin, Mobile, Put Away, Product Photo Review, API Tester, and AI/manual date pickers do not offer it as a selectable type. The first user edit converts that Package date to ordinary Best By. Existing estimates are not recalculated when FoodKeeper data or Storage Locations later change, and estimated dates use the same Current / Expiring Soon / Expired calculations without ever changing Package availability automatically.

Purge

Setting Key Type Purpose
Enable Scheduled Purge purge.enabled boolean Run the scheduled purge worker when invoked by cron/systemd.
Scheduled Purge Dry Run purge.dry_run boolean Preview scheduled purge work without deleting records.
Purge Self-Deleted Accounts purge.account_lifecycle.enabled boolean When the scheduled purge runs, permanently remove accounts that confirmed delete and waited through the safety delay.
Self-Delete Safety Delay Hours purge.account_lifecycle.self_delete_delay_hours integer Confirmed self-delete requests become purge-eligible after at least this many hours. Values below 24 are treated as 24.
Purge Shopping Lists purge.shopping_lists.enabled boolean Allow scheduled purge to remove completed, archived, or deleted shopping-list data after the configured retention windows.
Completed Shopping Lists Retention Days purge.shopping_lists.completed_after_days integer Completed shopping lists are eligible after this many days.
Archived Shopping Lists Retention Days purge.shopping_lists.archived_after_days integer Archived/deleted shopping lists are eligible after this many days.
Purge Old Meal Plans purge.meal_plans.enabled boolean Allow scheduled purge to remove Meal Planner content after the Meal Slot date retention period.
Meal Plan Retention Days purge.meal_plans.after_days integer Meal Plans become purge-eligible this many days after the Meal Slot date. Default is 730 days (2 years).
Purge Archived Recipes purge.recipes.enabled boolean Allow scheduled purge to permanently remove archived/deleted recipe data after the configured retention windows.
Archived Recipes Retention Days purge.recipes.archived_after_days integer Recipes must be archived before they are eligible.
Deleted Recipes Retention Days purge.recipes.deleted_after_days integer Deleted recipe rows are eligible after this many days.
Purge Unused AI Assets purge.ai_unused_assets.enabled boolean Allow the scheduled platform purge to remove generated AI image candidates that were not saved with a recipe after the applicable retention period.
Global Unused AI Asset Retention Days purge.ai_unused_assets.after_days integer Global retention period for unused AI-generated image assets. This value is used for every AI use case when the global override is enabled and as a fallback when a use case no longer exists.
Override AI Use-Case Retention purge.ai_unused_assets.override_use_case_retention boolean Use the global unused AI asset retention period for every AI use case instead of each use case's individual AI Data Retention setting. This override applies only to unused generated assets.
Purge AI Operational History purge.ai_history.enabled boolean Remove terminal AI Jobs, AI Usage rows, completed job-linked Seed reservations/ledger entries, and related evidence after each AI use case's AI Data Retention period. Active work and current Seed balances are protected.
Purge Archived Kitchen Inventory purge.kitchen_inventory.enabled boolean Allow scheduled purge to permanently remove Kitchen Inventory items after their restore window.
Kitchen Inventory Restore Window Days purge.kitchen_inventory.archived_after_days integer Archived Kitchen Inventory items remain restorable for this many days. Default is 14 days.
Purge Old Background Jobs purge.background_jobs.enabled boolean Allow scheduled purge to remove old background job status/history rows after the configured retention windows.
Completed Job Retention Days purge.background_jobs.completed_after_days integer Successful background job rows are eligible for purge after this many days.
Failed Job Retention Days purge.background_jobs.failed_after_days integer Failed background job rows are eligible for purge after this many days.
Purge Performance Metrics purge.performance_metrics.enabled boolean Trim detailed and aggregate Performance screen metrics.
Performance Detail Retention Days purge.performance_metrics.detail_after_days integer Detailed performance events are eligible after this many days.
Performance Aggregate Retention Days purge.performance_metrics.aggregate_after_days integer Daily performance aggregates are eligible after this many days.
Purge Regression Test Run History purge.regression_test_runs.enabled boolean Remove historical regression run details/reports after the configured retention period.
Regression Test Run Retention Days purge.regression_test_runs.after_days integer Completed regression run details/reports are eligible after this many days. Default is 30 days.
Purge Audit Log purge.audit_log.enabled boolean Remove organization-scoped audit log rows after the configured retention period.
Audit Log Retention Days purge.audit_log.after_days integer Audit log rows are eligible after this many days. Default is 30 days.
Purge Display Assignment Batches purge.display_assignment_batches.enabled boolean Remove display assignment batch tracking rows after retention. Does not delete active display assignments.
Display Assignment Batch Retention Days purge.display_assignment_batches.after_days integer Display assignment batch rows are eligible after this many days. Default is 7 days.
Purge Setting Audit Log purge.setting_audit_log.enabled boolean Remove scoped configuration setting audit rows after the configured retention period.
Setting Audit Log Retention Days purge.setting_audit_log.after_days integer Setting audit log rows are eligible after this many days. Default is 30 days.
Purge Game History purge.game_history.enabled boolean Purge old completed arcade sessions, Recipe Memory history, garden events, and stale presence. Keep live games, progress, AI Seed redemption data, and deletion governance.
Game History Retention Days purge.game_history.after_days integer Default 7 days; applies to all short-lived game history resources as one Data Cleanup group.
Purge Data Cleanup History purge.data_purge_history.enabled boolean Remove completed Data Cleanup run and run-item history after retention.
Data Cleanup History Retention Days purge.data_purge_history.after_days integer Data Cleanup run history is eligible after this many days. Default is 7 days.
Purge Voice Assistant Command Log purge.voice_assistant_command_log.enabled boolean Remove Alexa/Google Home voice command request history after retention.
Voice Assistant Command Log Retention Days purge.voice_assistant_command_log.after_days integer Voice assistant command log rows are eligible after this many days. Default is 7 days.
Purge Recipe Share Audit purge.recipe_share_audit.enabled boolean Remove recipe share audit events after retention while keeping active share records.
Recipe Share Audit Retention Days purge.recipe_share_audit.after_days integer Recipe share audit rows are eligible after this many days. Default is 7 days.
Purge Revoked API Tokens purge.api_tokens.enabled boolean Remove revoked user/API tokens after the configured retention period.
Revoked API Token Retention Days purge.api_tokens.revoked_after_days integer Revoked API tokens are eligible after this many days. Default is 7 days.
Purge Access IP/Location Activity purge.access_activity.enabled boolean Remove retained raw IP/location access activity when scheduled purge runs.
Access IP/Location Retention Days purge.access_activity.after_days integer Raw access source IP/location rows and GeoIP cache entries are eligible after this many days.
Purge Completed User Invites purge.user_invites.enabled boolean Remove accepted, expired, and revoked invite rows after the configured retention period.
Completed Invite Retention Days purge.user_invites.completed_after_days integer Accepted, expired, and revoked invite rows are eligible after this many days. Default is 60 days.
Purge Backup Run History purge.backup_runs.enabled boolean Old backup run/status metadata is eligible for purge. Backup ZIP artifacts are not deleted by this rule.
Backup Run History Retention Days purge.backup_runs.after_days integer Completed and failed backup run metadata is eligible after this many days.
Backup Runs To Always Keep purge.backup_runs.keep_last integer Always keep this many newest backup run rows per organization.
Purge Cloud Backup Status History purge.cloud_backup_state.enabled boolean Trim old embedded backup status/history entries from cloud backup state rows.
Cloud Backup Status History Retention Days purge.cloud_backup_state.history_after_days integer Cloud backup provider state history entries are eligible for trimming after this many days.
Purge Restore Staging Files purge.restore_staging.enabled boolean Remove old temporary restore extraction folders/files.
Restore Staging Retention Days purge.restore_staging.after_days integer Temporary restore staging folders/files are eligible for purge after this many days.
Restore Staging Entries To Always Keep purge.restore_staging.keep_last integer Always keep this many newest restore staging entries even if they are older than the retention window.
Purge Let’s Cook Session Data purge.lets_cook_session_data.enabled boolean Completed Let’s Cook operational rows are eligible after this many days while compact history is retained separately.
Let’s Cook Session Data Retention Days purge.lets_cook_session_data.after_days integer Completed Let’s Cook session rows, recipes, steps, ingredients, timers, display state, and deferrals are eligible after this many days.
Purge Let’s Cook Session History purge.lets_cook_session_history.enabled boolean Allow scheduled purge to trim compact Let’s Cook summary/history rows after the configured retention window.
Let’s Cook Session History Retention Days purge.lets_cook_session_history.after_days integer Compact Let’s Cook summary/history rows are eligible after this many days.

Recipe Capture

Setting Key Type Purpose
Slow recipe website threshold slow_recipe_sites.threshold_seconds integer When recipe cache generation from a website takes longer than this many seconds, Blackcap adds the website to the slow recipe website list.
Enable Social Recipe Imports social_recipe_imports.enabled boolean Allow the normal Add Recipe URL flow and Chrome Extension to submit supported YouTube, TikTok, Instagram, Facebook Reel, and Pinterest recipe sources.
Enabled Social Providers social_recipe_imports.enabled_providers string Comma-separated supported providers enabled for this deployment.
Enable URL-Only Social Import social_recipe_imports.url_only_enabled boolean Allow supported social URLs to start an import without an extension capture.
Enable Extension Social Capture social_recipe_imports.extension_capture_enabled boolean Allow the Blackcap Chrome Extension to submit expanded captions and other normalized public page evidence.
Enable Social Recipe OCR social_recipe_imports.enable_ocr boolean Permit a registered OCR processor to receive selected recipe-card image evidence. No OCR provider is bundled.
Enable Social Recipe Transcription social_recipe_imports.enable_transcription boolean Permit a registered transcription processor to receive selected recipe audio evidence. No transcription provider is bundled.
Enable Social Recipe Frame Extraction social_recipe_imports.enable_frame_extraction boolean Permit a registered bounded frame-extraction processor. No frame processor is bundled.
Enable Social Recipe AI Normalization social_recipe_imports.enable_ai_normalization boolean Permit a registered AI processor to organize supported evidence without inventing missing recipe facts. No AI provider is bundled.
Enable Social Candidate Ranking social_recipe_imports.enable_candidate_ranking boolean Permit a registered processor to rank multiple source-derived recipe candidates.
Enable Optional Source Discovery social_recipe_imports.enable_optional_source_discovery boolean Permit a registered source-discovery processor to supplement deterministic explicit-link discovery.
Social Capture Payload Limit social_recipe_imports.max_capture_payload_bytes integer Maximum normalized Chrome Extension social-capture payload size in bytes.
Social Evidence Retention Days social_recipe_imports.evidence_retention_days integer Days to retain bulky capture/source/candidate evidence after an import is no longer actionable. Pending selection, pre-creation review, and Extension-capture requests keep their evidence through the longer terminal window.
Social Import Retention Days social_recipe_imports.terminal_import_retention_days integer Days to retain abandoned failed/cancelled/partial imports and stale selection/review/Extension-capture work that never created a recipe.

Recipe Discovery

Setting Key Type Purpose
Recipe Discovery Search Provider recipe_discovery.search_provider_type string (choices: manual_only, google_embedded_cse, google_agent_search, brave_search, tavily_search) Primary Recipe Discovery method and the search on/off control. Manual URL Only disables search; selecting another provider activates it. Google Programmable Search remains browser-rendered; Agent Search, Brave, and Tavily provide server-side curated search.
Google Search Engine ID recipe_discovery.google_cse_id string Google Programmable Search Engine ID / cx used only by the embedded/browser Recipe Discovery search. No API key is required for this browser-rendered option.
Google Agent Search Project ID recipe_discovery.google_agent_search_project_id string Google Cloud project that owns the Recipe Search website data store.
Google Agent Search Location recipe_discovery.google_agent_search_location string Agent Search data-store location. Basic website search normally uses global.
Google Agent Search Collection ID recipe_discovery.google_agent_search_collection_id string Collection containing the Recipe Search data store; normally default_collection.
Google Agent Search Data Store ID recipe_discovery.google_agent_search_data_store_id string Basic website-search data store containing the curated Recipe Search targets and target-site rules.
Google Agent Search App ID recipe_discovery.google_agent_search_app_id string Agent Search application/engine ID used to serve searches. Google recommends app/engine search; Blackcap can fall back to the data store if this is blank.
Google Agent Search Serving Config ID recipe_discovery.google_agent_search_serving_config_id string Serving config used for server-side Recipe searches; normally default_search.
Brave Search API Key recipe_discovery.brave_search_api_key secret Encrypted Brave Search subscription token. Not included in portable Recipe Search exports.
Brave Search Country recipe_discovery.brave_search_country string Two-letter country code for Brave Search localization, default US.
Brave Search Language recipe_discovery.brave_search_language string Brave Search language code, default en.
Tavily Search API Key recipe_discovery.tavily_search_api_key secret Encrypted Tavily API key. Not included in portable Recipe Search exports.
Tavily Search Depth recipe_discovery.tavily_search_depth string (basic/fast/ultra-fast/advanced) Tavily search depth. Basic/Fast/Ultra-fast use one credit; Advanced uses two. Basic is the default.
Tavily Search Language recipe_discovery.tavily_search_language string Tavily result language, default en.
Use Recipe Discovery Search for AI Plan Meals recipe_discovery.use_for_ai_plan_meals boolean For Find & Add, prefer provider-supplied grounded Recipe URLs that pass Blackcap source rules and can be captured; use the configured server-side Recipe Discovery provider per Recipe when the provider supplies no usable URL, the model has no web-search capability, or direct capture fails.
Recipe Discovery Result Limit recipe_discovery.search_result_limit integer Maximum total Recipe Discovery results made available, capped at 100 and paged 10 at a time. Tavily and Brave each return at most 20 web results per provider request/page, so larger configured pools can require additional provider requests. Blackcap de-duplicates the combined pool before applying the complete Recipe Search URL rules.
Recipe Discovery Extraction Timeout Seconds recipe_discovery.extraction_timeout_seconds integer Maximum time allowed for recipe extraction/preview before the import attempt is treated as timed out.
Positive Search Terms recipe_discovery.positive_terms textarea One per line. These terms are appended to Recipe Discovery searches to bias results toward specific recipe pages.
Excluded Search Phrases recipe_discovery.excluded_phrases textarea One per line. Blackcap adds each phrase as a negative quoted search term where the selected provider supports it.
Excluded Title Terms recipe_discovery.excluded_title_terms textarea One per line. Blackcap adds each term as a negative title filter where the selected provider supports it.

Google Agent Search uses Application Default Credentials (ADC) and IAM only. Blackcap does not store an Agent Search API key. Brave and Tavily use encrypted platform API-key settings and apply the current compatible Blackcap source rules on each request, so they require no persistent rule synchronization; Blackcap re-filters every returned URL locally. For Tavily, include rules are narrowed to a safe domain/path prefix when possible, path-specific exclusions stay local instead of being widened to an entire domain, and Blackcap requests up to 20 candidates per API call before applying its URL rules. Tavily searches also use a concise natural-language query instead of Google-specific search operators, and Tavily result-card descriptions are cleaned/truncated so extracted recipe-body text does not overwhelm the search UI. Brave likewise uses a concise provider-specific recipe query instead of the long Google negative/intitle operator string. Its inline Goggle preserves compatible include-path patterns where possible so category/roundup pages do not consume scarce provider result slots; interactive Brave searches build a bounded result pool from native 20-result pages, collapse overlap, and then page locally in Blackcap. When Agent Search is selected and configured, Blackcap automatically synchronizes enabled include/exclude rules after rule changes and after Recipe Discovery provider settings are saved. There is no separate auto-sync setting. On Google Cloud, grant the runtime service account the required Discovery Engine permissions and use a VM OAuth scope such as cloud-platform; the same identity serves Recipe searches and synchronizes Agent Search target-site include/exclude rules. Migration 246 removes the retired Custom Search JSON API key, Agent Search API key, and Agent Search authentication-mode settings from existing databases. Migration 250 removes the obsolete recipe_discovery.search_provider_enabled setting because recipe_discovery.search_provider_type is now the single source of truth for Recipe Discovery enablement.

Runtime

Setting Key Type Purpose
Host Device Type Override runtime.host_device_type_override string (choices: auto, raspberry_pi, generic_linux, docker, unknown) Optional branding/runtime override. Auto-detects Raspberry Pi when possible and otherwise uses generic Blackcap branding.
Default Python Path runtime.python_path string Default Python executable used by Blackcap subprocess renderers. On GCP this is typically /opt/blackcap_env/bin/python.
Menu Python Path runtime.menu_python_path string Python executable used when refreshing menu and meal-plan display content.
Recipe Python Path runtime.recipe_python_path string Python executable used when rendering recipe cache images and recipe display content.
Deep Clean Python Path runtime.deep_clean_python_path string Python executable used by the display deep-clean maintenance action.

Security

Setting Key Type Purpose
Google OAuth Allowed Domain security.google_oauth.allowed_domain string Platform-wide Google OAuth domain allow-list. Applies to all organizations.
Auto-link Verified Google Email security.google_oauth.auto_link_verified_email boolean Platform-wide Google OAuth auto-link policy. Applies to all organizations.
External Base URL security.external_base_url string Public HTTPS base URL for this Blackcap instance, such as https://ryan.redirectme.net. Required when TLS is terminated by stunnel or a reverse proxy before Gunicorn.
Login Provider External Base URL security.login_provider_external_base_url string Optional public HTTPS base URL used only for OAuth/OIDC browser login provider callbacks. Use this when voice assistants need the main External Base URL on port 443 but Admin login providers are registered on another public port such as 9443.
Extension Allowed Origins security.extension_allowed_origins string Platform-wide browser extension CORS allow-list.
Session Timeout Hours security.session_timeout_hours integer Idle browser session timeout in hours. Applies to all organizations.
Trust Proxy IP Headers security.trusted_proxy_headers_enabled boolean Only when enabled and the immediate peer is in Trusted Proxy CIDRs will Blackcap use X-Forwarded-For or X-Real-IP.
Trusted Proxy CIDRs security.trusted_proxy_cidrs textarea Comma or newline separated proxy CIDRs allowed to supply X-Forwarded-For/X-Real-IP client addresses.
Trust External HTTPS Base URL security.trust_external_base_url_https boolean Treat requests whose Host matches an HTTPS auth.external_base_url as secure. Required for stunnel/Gunicorn PROXY protocol because the backend hop is plain HTTP even when the browser used HTTPS. Keep Gunicorn bound to localhost when enabled.

Support

Setting Key Type Purpose
Enable Support Requests support_requests.enabled boolean Allow authenticated Admin users to send Support Request emails.
Support Email Address support_requests.email_address string Destination inbox for Support Request emails. No default is provided.
Case Prefix support_requests.case_prefix string Prefix prepended to generated support case numbers.
Next Case Number support_requests.next_case_number integer Next numeric support case value. Case numbers are formatted as prefix + five digits.
Organization Requests Per Hour support_requests.org_hourly_limit integer Maximum Support Requests one organization can send per hour. Use 0 to disable this Support-specific limit.

Organization settings

Backup

Setting Key Type Purpose
Remote Folder backup.remote_folder string Cloud folder/path used for this organization’s Dropbox or Google Drive backups.
Preferred Provider backup.preferred_provider string (choices: local, dropbox, google_drive) Default destination selected for manual backups in this organization.
Enable Automatic Backup backup.auto.enabled boolean Allow scheduled backup checks to create automatic backups for this organization.
Automatic Backup Provider backup.auto.provider string (choices: local, dropbox, google_drive) Destination used when scheduled automatic backups run.
Automatic Backup Frequency Days backup.auto.interval_days integer Minimum number of days between automatic backups for this organization. Set to 0 to run at every scheduled check.
Automatic Backups To Retain backup.auto.retain_count integer Number of newest automatic backup files to keep for this organization before older ones become eligible for cleanup.

General Rendering

Setting Key Type Purpose
Crop Left render.crop_left integer Left crop applied before generated menu and meal-plan rendering.
Crop Top render.crop_top integer Top crop applied before generated menu and meal-plan rendering.
Crop Right render.crop_right integer Right crop applied before generated menu and meal-plan rendering.
Body X Offset render.body_x_offset integer Horizontal content offset for generated menu and meal-plan images.
Body Y Offset render.body_y_offset integer Vertical content offset for generated menu and meal-plan images.

Household List

Setting Key Type Purpose
Enable Household List household_list.enabled boolean Enable the built-in persistent Household List for this organization.
External Sync Freshness household_list.external_sync_freshness_minutes string (choices: always, 15, 30, 60, 240, never) How fresh External Shopping List syncs should be before Blackcap suggests syncing before shopping.
Default Include in Admin Shop a List household_list.default_include_admin_shop_a_list boolean Default Include Household List to on for the Admin Shop a List page.
Default Include in Mobile Shop a List household_list.default_include_mobile_shop_a_list boolean Default Include Household List to on for the Mobile Shop a List page.

Internal

Setting Key Type Purpose
Menu Source Probe State menu.source_probe_state json (internal/compatibility) Cached HTTP/body-hash metadata for lightweight menu source change detection.

Kitchen Inventory

Setting Key Type Purpose
Expiring Soon Warning inventory.expiring_soon_days integer Number of organization-local calendar days before a dated physical Package is considered Expiring Soon. Valid range 1–365; default 7.

Let’s Cook

Setting Key Type Purpose
Show Full Recipe Before Current Step lets_cook.show_full_recipe_review_before_current_step boolean Start current-step Let’s Cook sessions with a full recipe review before moving into step-by-step cooking.

Meal Planner

Setting Key Type Purpose
Display Refresh Delay Seconds meal_planner.display_refresh_debounce_seconds integer After meal-plan edits, wait this many seconds after the latest change before refreshing displays that are currently showing the Meal Plan. Set to 0 for immediate refresh.
Setting Key Type Purpose
Menu URL menu.url string Source URL captured for the organization menu display. Changing it changes what the Menu renderer fetches and caches.
Page wait seconds menu.page_wait_seconds float Seconds to wait after loading the Menu URL before capture/OCR. Increase when the source page renders slowly.
Type K Menu Rendering menu.type_k_render_mode string (choices: crisp_bw, perceptual_four_tone, native_four_gray) Rendering strategy used for photographic Menu captures on the Waveshare 13.3-inch Type K panel. Crisp Black & White is the reliable default; Perceptual Four Tone uses black/white halftone patterns; Native Four Gray remains experimental.
Menu Contrast menu.processing.contrast float Contrast multiplier applied during menu image processing before display/OCR output.
Menu Sharpness menu.processing.sharpness float Sharpness multiplier applied during menu image processing to improve text readability.
Menu Image Threshold menu.processing.threshold integer Black/white conversion threshold for processed menu images rendered to e-ink-style displays.
OCR Scale menu.processing.ocr_scale float Upscale factor used before OCR so smaller menu text is easier to recognize.
OCR Threshold menu.processing.ocr_threshold integer Black/white threshold used on the OCR-preprocessed menu image.
Menu Diff Threshold menu.processing.diff_threshold float Image-change threshold used to decide whether a refreshed menu capture is meaningfully different.
Setting Key Type Purpose
Footer Placement noun_footer.placement string (choices: menu_and_meal_plan, menu_only, meal_plan_only, none) Choose where the Noun Project footer is rendered.
Footer Height noun_footer.height integer Reserved footer area for generated menu and meal-plan images when the footer is enabled.
Icon Y Offset noun_footer.icon_y_offset integer Footer icon vertical offset for generated menu and meal-plan images.
Text Y Offset noun_footer.text_y_offset integer Footer text vertical offset for generated menu and meal-plan images.
Max Footer Icons noun_footer.max_icons integer Maximum number of Noun Project icons rendered in the footer.
Icon Size noun_footer.icon_size integer Footer icon size in pixels.
Footer Font Path noun_footer.font_path string Font used for footer labels.
Footer Font Size noun_footer.font_size integer Footer label font size in pixels.

Recipe Fonts

Setting Key Type Purpose
Recipe Font Path recipe.fonts.font_path string Optional font file path for normal recipe text. Leave blank to use the platform default font.
Recipe Bold Font Path recipe.fonts.bold_font_path string Optional font file path for bold recipe text. Leave blank to use the platform default bold font.
Recipe Emoji Font Path recipe.fonts.emoji_font_path string Optional emoji font path used when recipe or metadata rendering includes emoji characters.

Recipe Info

Setting Key Type Purpose
Green Time Max Minutes recipe_metadata.total_time.green_max_minutes integer Total-time pill is green when total time is at or below this many minutes.
Yellow Time Max Minutes recipe_metadata.total_time.yellow_max_minutes integer Total-time pill is yellow above green and at or below this many minutes; longer recipes use the red style.
Green Time Background recipe_metadata.total_time.green_background string Background color for quick/green total-time pills on recipe cards and search/add tiles.
Green Time Text recipe_metadata.total_time.green_text string Text color for quick/green total-time pills on recipe cards and search/add tiles.
Green Time Border recipe_metadata.total_time.green_border string Border color for quick/green total-time pills on recipe cards and search/add tiles.
Yellow Time Background recipe_metadata.total_time.yellow_background string Background color for medium/yellow total-time pills on recipe cards and search/add tiles.
Yellow Time Text recipe_metadata.total_time.yellow_text string Text color for medium/yellow total-time pills on recipe cards and search/add tiles.
Yellow Time Border recipe_metadata.total_time.yellow_border string Border color for medium/yellow total-time pills on recipe cards and search/add tiles.
Long Time Background recipe_metadata.total_time.red_background string Background color for long/red total-time pills on recipe cards and search/add tiles.
Long Time Text recipe_metadata.total_time.red_text string Text color for long/red total-time pills on recipe cards and search/add tiles.
Long Time Border recipe_metadata.total_time.red_border string Border color for long/red total-time pills on recipe cards and search/add tiles.
Very Low Cleanup Max Score recipe_metadata.cleanup.very_low_max_score integer Cleanup pill is very low when the estimated score is at or below this value.
Low Cleanup Max Score recipe_metadata.cleanup.low_max_score integer Cleanup pill is low above very low and at or below this value.
Medium Cleanup Max Score recipe_metadata.cleanup.medium_max_score integer Cleanup pill is medium above low and at or below this value.
High Cleanup Max Score recipe_metadata.cleanup.high_max_score integer Cleanup pill is high above medium and at or below this value; higher scores use very high.
Very Low Cleanup Background recipe_metadata.cleanup.very_low_background string Background color for very low cleanup estimate pills on recipe cards and search/add tiles.
Very Low Cleanup Text recipe_metadata.cleanup.very_low_text string Text color for very low cleanup estimate pills on recipe cards and search/add tiles.
Very Low Cleanup Border recipe_metadata.cleanup.very_low_border string Border color for very low cleanup estimate pills on recipe cards and search/add tiles.
Low Cleanup Background recipe_metadata.cleanup.low_background string Background color for low cleanup estimate pills on recipe cards and search/add tiles.
Low Cleanup Text recipe_metadata.cleanup.low_text string Text color for low cleanup estimate pills on recipe cards and search/add tiles.
Low Cleanup Border recipe_metadata.cleanup.low_border string Border color for low cleanup estimate pills on recipe cards and search/add tiles.
Medium Cleanup Background recipe_metadata.cleanup.medium_background string Background color for medium cleanup estimate pills on recipe cards and search/add tiles.
Medium Cleanup Text recipe_metadata.cleanup.medium_text string Text color for medium cleanup estimate pills on recipe cards and search/add tiles.
Medium Cleanup Border recipe_metadata.cleanup.medium_border string Border color for medium cleanup estimate pills on recipe cards and search/add tiles.
High Cleanup Background recipe_metadata.cleanup.high_background string Background color for high cleanup estimate pills on recipe cards and search/add tiles.
High Cleanup Text recipe_metadata.cleanup.high_text string Text color for high cleanup estimate pills on recipe cards and search/add tiles.
High Cleanup Border recipe_metadata.cleanup.high_border string Border color for high cleanup estimate pills on recipe cards and search/add tiles.
Very High Cleanup Background recipe_metadata.cleanup.very_high_background string Background color for very high cleanup estimate pills on recipe cards and search/add tiles.
Very High Cleanup Text recipe_metadata.cleanup.very_high_text string Text color for very high cleanup estimate pills on recipe cards and search/add tiles.
Very High Cleanup Border recipe_metadata.cleanup.very_high_border string Border color for very high cleanup estimate pills on recipe cards and search/add tiles.

Recipe Layout

Setting Key Type Purpose
Split Column Ratio recipe.two_page_left_column_ratio float Left-column width ratio for split-column recipe rendering.

Recipe Rendering

Setting Key Type Purpose
Recipe Margin recipe.rendering.margin integer Outer padding in pixels around generated recipe pages before auto-fit adjustments.
Recipe Minimum Margin recipe.rendering.min_margin integer Smallest margin the recipe renderer may use when shrinking layout to fit the page.
Recipe Section Gap recipe.rendering.section_gap integer Vertical spacing in pixels between recipe sections such as ingredients, steps, and notes.
Recipe Threshold recipe.rendering.threshold integer Black/white image threshold used when generating monochrome recipe render output.
Default Recipe Layout recipe.default_layout string (choices: single_page, two_page) Default layout for newly added recipes in this organization. Existing recipes are not changed.

Recipe Typography

Setting Key Type Purpose
Recipe Title Font Size recipe.typography.title_font_size integer Starting title font size for generated recipes. Auto-fit may reduce it to avoid clipping.
Recipe Heading Font Size recipe.typography.heading_font_size integer Starting section heading font size for generated recipe layouts.
Recipe Body Font Size recipe.typography.body_font_size integer Starting body text font size for ingredients, instructions, and notes in generated recipe layouts.
Recipe Small Font Size recipe.typography.small_font_size integer Starting small-text font size for compact recipe details and secondary metadata.
Recipe Minimum Title Font Size recipe.typography.min_title_font_size integer Smallest title font size allowed when auto-fitting a generated recipe.
Recipe Minimum Heading Font Size recipe.typography.min_heading_font_size integer Smallest section heading font size allowed when auto-fitting a generated recipe.
Recipe Minimum Body Font Size recipe.typography.min_body_font_size integer Smallest body font size allowed when auto-fitting recipe content.
Recipe Minimum Small Font Size recipe.typography.min_small_font_size integer Smallest secondary text size allowed during recipe auto-fit.
Recipe Line Spacing recipe.typography.line_spacing integer Additional vertical spacing in pixels between recipe text lines.

Share

Setting Key Type Purpose
From Name share.from_name string Display name used as the sender for recipe sharing emails from this organization.
Email PDF Page Size share.email_pdf_page_size string (choices: letter, a4, legal) Page size used when attaching recipe PDFs to email shares.
Recipe PDF Orientation share.recipe_pdf_orientation string (choices: portrait, landscape) Controls portrait vs. landscape recipe PDF/cache rendering for this organization. Changing it creates a separate render variant and may require cache rebuilds.
Preferred Recipe Units share.recipe_preferred_units string (choices: as_written, us_customary, metric) Presentation preference for recipe ingredient and instruction units. Original recipe text is preserved; only clearly parsed measurements are converted.
Maximum US Volume Unit share.recipe_max_us_volume_unit string (choices: cup, quart) Upper display unit when scaling US volumes; defaults to cups.
Maximum Metric Volume Unit share.recipe_max_metric_volume_unit string (choices: ml, l) Upper display unit when scaling metric volumes; defaults to liters.

Display settings

Deprecated Display Geometry

Setting Key Type Purpose
Width (Deprecated) display.width integer (internal/compatibility) Deprecated: use the display resolution fields on Display Detail.
Height (Deprecated) display.height integer (internal/compatibility) Deprecated: use the display resolution fields on Display Detail.

Saving and validating changes

  1. Select Platform or the intended Active Organization.
  2. Open the named configuration page.
  3. Review explanatory text, current value, scope, and any dependent connection/service.
  4. Save through the page action so validation and audit logging run.
  5. Validate the affected feature. Most DB-backed changes take effect without restarting the application; startup-only environment or service changes require the deployment-specific restart.

Do not edit settings tables directly to bypass validation. Use the INI export/bootstrap prune tools only for their documented migration and diagnostic purposes.

Troubleshooting

A page is missing

Check the current user's permission and, for organization pages, the Active Organization. Platform pages are not shown to ordinary organization users.

A setting appears not to take effect

Confirm the correct scope and organization, inspect the setting audit, review the feature-specific cache/reload behavior, and verify that an environment/bootstrap value is not intentionally authoritative for that dependency.

A secret is blank after save

Existing secrets are intentionally not returned. Leave the field unchanged to retain the current encrypted value or enter a replacement explicitly.

Search finds a page but not a specific setting

Custom provider pages may expose records rather than flat registered settings. Open the page and use its dedicated controls.

Developer maintenance

Register simple settings declaratively, use dedicated services for complex records, keep scope and permission explicit, make migrations idempotent, and update this guide when adding a new custom page. Do not add direct SQL or large configuration logic to route modules.

On this page