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.
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, Database, Email, GeoIP / Access Location, Performance, Providers, Purge, Recipe Capture, Recipe Discovery, Runtime, Security, Shop With Providers, Slow Recipe Websites, Support, and Voice Assistant Providers. 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, Household List, Login Providers, Meal Planner, Menu, Noun Project Footer, Recipe Rendering, Recipe Info, Share, General Rendering, and Let’s Cook. 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.
- Organization Meal Planner manages meal slots and related behavior.
- 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. |
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. |
| 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. |
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. |
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 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 Unused AI Asset Retention setting. |
| 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 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 normalized capture evidence for completed, failed, or cancelled imports. |
| Social Import Retention Days | social_recipe_imports.terminal_import_retention_days |
integer | Days to retain terminal social-import records after compact recipe provenance has been saved. |
Recipe Discovery
| Setting | Key | Type | Purpose |
|---|---|---|---|
| Recipe Discovery Search Enabled | recipe_discovery.search_provider_enabled |
boolean | Enable Recipe Discovery search. Manual URL preview remains available when this is disabled. |
| Recipe Discovery Search Provider | recipe_discovery.search_provider_type |
string (choices: manual_only, google_embedded_cse) | Provider used by Recipe Discovery search. Google Search uses the browser Search Element with only the engine ID; no API key is required. |
| Google Search Engine ID | recipe_discovery.google_cse_id |
string | Google Programmable Search Engine ID used when embedded Google Recipe Discovery search is enabled. |
| Recipe Discovery Result Limit | recipe_discovery.search_result_limit |
integer | Maximum number of Recipe Discovery search results shown before the user chooses a recipe to preview or import. |
| 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 will add each phrase as a negative quoted Google term. |
| Excluded Title Terms | recipe_discovery.excluded_title_terms |
textarea | One per line. Blackcap will add each term as a negative intitle filter. |
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. |
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. |
Menu
| 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. |
Noun Project Footer
| 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. |
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
- Select Platform or the intended Active Organization.
- Open the named configuration page.
- Review explanatory text, current value, scope, and any dependent connection/service.
- Save through the page action so validation and audit logging run.
- 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.