Platform Configuration

Audience: System Admin Related: Administration and Operations · Organization Configuration · Configuration Workspace · GeoIP and Access Location · Data Retention and Purge · Performance and Job Status

This guide covers the ongoing and operationally significant areas under Administration → Configuration → Platform. It is intentionally task-oriented: what to review, when to change it, what a healthy state looks like, and which settings should normally be left alone after initial setup.

It does not try to repeat every field in the Configuration reference. Provider credentials, SMTP setup, login-provider applications, Shop With providers, voice-assistant credentials, database-provider selection, and runtime executable paths are primarily setup/change-management concerns. They are included only where an administrator should periodically verify health or know when to revisit them.

Before changing platform configuration

Platform configuration affects the entire Blackcap installation and can affect every organization. Before a broad change:

1. Confirm that you are working under Platform, not Organization configuration.
2. Understand whether the change affects new data only or immediately changes existing behavior.
3. Prefer one logical change at a time when troubleshooting.
4. For higher-risk changes, confirm that a recent backup exists.
5. After a significant change, review System → Logs, Job Status, and the affected feature.
6. Run an appropriate regression test after changes that affect shared runtime behavior, recipe processing, AI, authentication, rendering, database behavior, or data retention.

What deserves recurring attention

Platform area	Typical cadence	Why it matters
Country Flags	Periodically / after GeoIP growth	Keeps SVG flag coverage aligned with observed and expected country codes.
GeoIP / Access Location	Monthly and after proxy/network changes	Confirms the local country database, updater, lookup, and real-client-IP capture remain healthy.
FoodKeeper Shelf Life	Periodically / when catalog data changes	Keeps USDA-derived freshness guidance current while preserving Blackcap customizations.
Ingredient Densities	As inventory conversion issues are found	Controls volume↔weight conversion when Kitchen Inventory must bridge measurement families.
Slow Recipe Websites	Weekly/monthly on active capture systems	Prevents known slow sites from degrading URL-only quick add and provides retry/recovery controls.
Recipe Discovery	As sources/search quality change	Maintains curated include/exclude rules, source coverage, provider search behavior, and Plan Meals source quality.
Performance	After performance tuning or deployment changes	Controls whether metrics are collected and what request duration is considered slow.
Purge	Monthly / after retention-policy changes	Governs scheduled retention across jobs, AI history, performance, backups, audit history, and other operational data.
Certificates & Public Access	Monthly on public installs	Controls warning policy and exposes public HTTPS/DNS health.
Updates	Periodically on package-managed installs	Controls package update checks and optional approved-update behavior.
AI	Periodically / after provider releases	Maintains available models, pricing, Quality Profiles, and AI Seed policy.
Security	Periodically / after network/auth changes	Keeps session, trusted-proxy, extension-origin, and external-URL trust assumptions current.

The main Administration and Operations covers the operational workflows for AI, certificates, updates, purge execution, performance review, and overall system health. The sections below focus on the Platform configuration areas that need additional hands-on catalog or policy maintenance.

Manage Country Flags

Navigation: Administration → Configuration → Platform → Country Flags

Country Flags controls how Blackcap presents country indicators in access summaries and maintains the bundled SVG assets used by the interface.

What to review

Review:

• whether Enable Country Flags is appropriate for the installation;
• Country Flag Icon Mode (svg, emoji, or country-code fallback);
• how many SVG assets are currently bundled;
• MaxMind Country Coverage and the number of common country codes still missing an SVG;
• whether the optional generation tools are available when new SVG assets need to be generated.

Missing SVG assets are not a service outage. Blackcap falls back to emoji or country code while preserving the location tooltip.

Update flag assets

Use 🎌 Update Observed Flags when access activity has introduced countries that do not yet have a generated SVG asset. This is the smaller, targeted operation.

Use 🌐 Generate MaxMind Country Flags when you want the bundled assets to cover the common country-code catalog before those countries are observed. This can take longer when many files are missing.

Flag generation requires the optional host tools shown by the panel. They are operating-system tools, not Python Package Review dependencies. If the page says generation tools are missing, install them only when SVG generation is actually needed; Blackcap continues to function with its normal fallbacks.

Healthy Country Flag state

A healthy configuration has the intended icon mode, a populated SVG directory, and either complete/common MaxMind coverage or an understood fallback for the remaining country codes.

Country flags depend on GeoIP for country identification, so investigate GeoIP first when the country itself is wrong or missing.

Maintain the GeoIP database and access-location health

Navigation: Administration → Configuration → Platform → GeoIP / Access Location

Blackcap uses a local MaxMind-compatible MMDB reader for country-level access location. GeoIP enriches access activity; lookup failure does not block access.

Start with the diagnostics

Review the Status cards for:

• GeoIP enabled and the selected provider;
• whether the maxminddb Python package is available;
• whether the configured MMDB Database file exists, its size, and last-modified time;
• the number/type of observed access source IPs;
• Proxy/IP capture health, especially after Nginx, reverse-proxy, load-balancer, or trusted-proxy changes;
• updater source and whether the recommended blackcap_geoip_update.timer is installed/recording runs.

An old database file with no recent scheduled update is an administration problem even if lookups still return results.

Update the GeoIP database

Blackcap supports three operational approaches:

• DB-IP Lite — no provider account is required. Blackcap uses the configured monthly URL template and writes the downloaded MMDB to the configured target path.
• MaxMind geoipupdate — relies on host-level /etc/GeoIP.conf credentials and edition configuration. Blackcap does not store those credentials in platform settings.
• Manual — Blackcap does not automatically download the file; the administrator is responsible for keeping the configured MMDB current.

Use ⬇️ Update GeoIP DB Now when the configured updater is ready and you intentionally want an immediate refresh. For routine operation, prefer the installed scheduled timer over repeated manual updates.

Test lookups

Use Test Lookup with a known public IP after:

• replacing/updating the MMDB;
• changing the database path/provider;
• changing trusted proxy configuration;
• investigating a country attribution problem.

The test bypasses Blackcap's lookup cache so it reflects the current MMDB file.

If access activity shows only proxy/private addresses when a public deployment should expose client IPs, do not try to fix that by changing the country database. Review trusted proxy headers/CIDRs and reverse-proxy behavior.

See GeoIP and Access Location for the detailed security and proxy model.

Refresh and customize FoodKeeper Shelf Life

Navigation: Administration → Configuration → Platform → FoodKeeper Shelf Life

FoodKeeper Shelf Life is the platform catalog Blackcap uses to create an Estimated Best By date for a newly purchased physical Kitchen Inventory package when Full Inventory Tracking is enabled and the package does not already have a printed/manual freshness date.

The values are planning windows, not food-safety disposal rules. Blackcap does not automatically remove inventory when an estimated date is reached.

Review catalog status

The toolbar reports:

• active rows;
• customized rows;
• bundled fallback rows when applicable;
• the last USDA refresh time.

Use search to find an ingredient by display name, canonical ingredient, alias, source keyword, or category.

Refresh USDA FoodKeeper

Use ↻ Refresh USDA FoodKeeper periodically when you want Blackcap to reload the complete source catalog. Platform customizations are preserved across the refresh.

Refreshing the catalog does not rewrite Estimated Best By dates already stored on existing packages. FoodKeeper is evaluated when the physical package is created.

Customize a shelf-life rule

Edit a row when Blackcap's matching or usable numeric planning window needs a platform-specific correction. Each rule can contain:

• display name;
• canonical ingredient key;
• aliases;
• pantry days;
• refrigerator days;
• freezer days;
• active/inactive state.

Non-numeric source guidance such as “When Ripe” or “Not Recommended” can be retained as source context but does not create an automatic date.

Use Add shelf-life rule to fill a catalog gap or create a more-specific ingredient/alias match. Leave a storage location blank when Blackcap should not generate an estimate for that location.

If a user edits an Estimated Best By date on a package, Blackcap converts it to the normal user-managed Best By type. Later FoodKeeper changes do not overwrite that choice.

Healthy FoodKeeper state

A healthy catalog has a recent enough source refresh for your operating policy, the expected active rows, and only intentional customizations. Investigate repeated ingredient misses before adding many broad aliases; overly generic aliases can cause the wrong rule to match.

Manage Ingredient Densities

Navigation: Administration → Configuration → Platform → Ingredient Densities

Ingredient Densities are used only when Kitchen Inventory must convert between volume and weight for the same logical ingredient. Cups/tablespoons/teaspoons/fl oz/ml remain volume; oz/lb/g/kg remain weight.

When to maintain densities

This is usually an as-needed catalog rather than a weekly task. Review it when:

• a recipe quantity and an on-hand package quantity use different measurement families;
• Plan Meals/inventory availability appears wrong because Blackcap had to bridge volume and weight;
• runout calculations report that a fallback assumption was used;
• a common ingredient is missing or being matched to the wrong density row.

Add or edit a density

Each row contains:

• ingredient/display name;
• density in g/mL;
• comma-separated aliases;
• active state;
• source information.

Ingredient-specific active rows win over the Water/default fallback. Use canonical kitchen ingredient names and specific aliases rather than preparation-heavy phrases.

Blackcap keeps an active Water/default safety fallback (normally 1.000 g/mL) for unmatched ingredients. The fallback prevents the workflow from failing, but it is only an approximation and should not be treated as accurate for every ingredient.

Changes affect future quantity reconciliation and runout calculations. Existing physical package quantities are not rewritten.

Healthy Ingredient Density state

A healthy catalog has accurate entries for ingredients that frequently require volume↔weight conversion, a valid active fallback, and no broad alias that unintentionally captures unrelated foods.

Manage Slow Recipe Websites

Navigation: Administration → Configuration → Platform → Slow Recipe Websites

Blackcap persists domains whose recipe cache builds exceed the configured slow-site threshold. The list survives performance-metric purges because it is operational behavior, not merely performance history.

Understand the effect

An active slow domain blocks URL-only quick add for that website so users do not repeatedly initiate a path known to be too slow. Full active-page capture and Recipe Discovery remain available.

The default threshold is 50 seconds unless the platform has changed it.

Review the list

For each domain, review:

• status and source;
• last full recipe URL;
• threshold at detection;
• historical maximum/average cache time;
• sample count;
• last detected time;
• last retry status/time/duration;
• notes.

A large or rapidly growing list can indicate website changes, network problems, extraction regressions, or a threshold that is too aggressive for the hardware/deployment.

Retry a site

Use 🔁 Retry when a full recipe URL is stored and you want Blackcap to test whether the site has become fast enough again. Retry queues a background cache-build test. A successful result under the threshold re-enables the domain for normal quick-add behavior.

If Retry is unavailable, re-add the website with a full recipe URL so Blackcap has something concrete to test.

Use the delete/remove action to intentionally take an active site off the slow list. Use Reactivate when a previously removed site should again be treated as slow.

Manually add a site

Use Manually add a website for a known problematic domain that Blackcap has not automatically detected yet. A full URL is preferable because it also becomes the retry test URL.

Curate Recipe Discovery sources and rules

Navigation: Administration → Configuration → Platform → Recipe Discovery

Initial search-provider credentials/configuration are mostly setup work. The curated source rules and source quality, however, are ongoing administration because recipe sites change over time.

Review source/search health

Periodically review:

• the selected search provider is still intentional;
• AI Plan Meals Recipe Sources status;
• tracked recipe-website/source counts;
• provider server-search tests when supported;
• source-site CSV export when investigating where Plan Meals or Add Recipe is finding content.

Use Restore Search Defaults only when you intentionally want to reset search-tuning defaults. Provider settings, credentials, and curated Recipe Search rules are retained by that operation.

Maintain include/exclude rules

Blackcap owns curated Recipe Search rules independently from the search provider:

• Include rules define eligible recipe pages/sites.
• Exclude rules win over includes and remove noisy categories/tags/non-recipe sections.
• rules can be enabled, disabled/draft, filtered by website/type/status, added individually, or bulk-added;
• search configuration can be exported/imported without exporting API keys or Google Application Default Credentials.

Brave and Tavily receive the current rules on each search. Google Agent Search synchronizes target-site changes to its configured search application, and Blackcap still applies its URL-pattern rules to returned results.

Add a new recipe source safely

Use Add New Recipe Source Wizard rather than adding an untested broad production include pattern:

1. enter the proposed include pattern and a representative test search;
2. select Add Draft & Test;
3. review every returned URL in the preview;
4. add exclusions for category/tag/index/noise patterns as needed;
5. change the draft pattern or query and Update Draft & Test again when necessary;
6. activate the source only when the returned URLs are acceptably recipe-focused.

Draft sources are not used by production Recipe Discovery or Plan Meals until activated.

Treat source curation and Slow Recipe Websites as complementary: a source may be high-quality enough to include in search while still being too slow for URL-only quick add.

Maintain Performance configuration

Navigation: Administration → Configuration → Platform → Performance

The Performance configuration is small but important:

• Performance Metrics Enabled controls collection of lightweight operational metrics used by System Admin diagnostics.
• Slow Request Threshold Ms controls which successful request/page timings are retained as slow; HTTP 500+ requests are still important regardless of the normal threshold behavior.

Normally leave performance metrics enabled. Change the threshold only when you have a clear reason, such as adapting diagnostics to very different hardware or reducing noise after reviewing real Performance-page data.

Do not raise the threshold simply to make slow-request warnings disappear. Use Administration → Performance to understand the underlying latency first.

Maintain Purge/retention policy

Navigation: Administration → Configuration → Platform → Purge

Purge is one of the most consequential platform configuration areas because it controls retention for many operational domains: jobs, performance metrics, regression runs, audit/access activity, AI history/assets, backup run metadata, restore staging, user invites/tokens, sharing history, Let’s Cook history, and more.

Use the Configuration page to maintain policy. Use Administration → Data Cleanup to review recent runs, dry-run the policy, execute it intentionally, and confirm scheduled purges are actually occurring.

When changing retention:

1. understand the data domain and whether the rule deletes primary data, operational history, or temporary artifacts;
2. prefer a dry run before a broad new policy;
3. verify keep last protections where available;
4. review the next scheduled purge and its result in Job Status;
5. confirm that the changed retention still supports troubleshooting, reconciliation, and compliance needs.

See Data Retention and Purge.

Review Certificates, Updates, and AI from Platform Configuration

These are recurring platform areas, but their full workflows are already covered in the main administration guide:

• Certificates & Public Access — maintain warning policy and inspect public HTTPS/DNS health. Use System for the operational certificate/DNS view.
• Updates — package-managed installations only; controls update-check/auto-apply policy. Use System → Blackcap Updates to actually review/prepare/apply releases.
• AI — provider connections, model/pricing refresh, model availability, Quality Profiles, and AI Seed policy. Use AI Usage for spend/reconciliation.

See Administration and Operations for those workflows.

Periodically review Security configuration

Navigation: Administration → Configuration → Platform → Security

Security settings should not change frequently, but they should be reviewed after network/proxy/authentication changes and periodically on public installations.

Important assumptions include:

• session timeout;
• trusted proxy header enablement;
• trusted proxy CIDRs;
• external/public base URL trust behavior;
• Chrome Extension allowed origins;
• Google-auth linking/domain policy where applicable.

Do not enable trusted proxy headers broadly just to make GeoIP show a public address. Trust only the proxy/network ranges that actually terminate traffic for Blackcap.

Organization login-provider enablement and internal-login MFA policy live under Organization → Login Providers rather than the platform Security page.

Platform areas that are mostly setup or change-management

The following Platform configuration pages are important, but they generally do not justify routine edits merely as an administration ritual:

Area	Revisit when…
Authentication Providers	OAuth/OIDC provider credentials, callback URLs, or supported login providers change.
Email	SMTP host/credentials/sender/branding changes or email delivery fails.
Provider	Shared Dropbox/Google Drive/Noun Project/shopping-provider credentials change.
Shop With Providers	A retailer/site definition, URL template, or browser-helper behavior changes.
Voice Assistant Providers	Alexa/Google Home credentials, skill/project configuration, or account-linking behavior changes.
Support	Support Requests routing, limits, email address, or case numbering changes.
Recipe Capture / Social Recipe Imports	Supported social capture behavior, OCR/transcription/frame-extraction policy, payload limits, or source workflow changes.
Database	Search-result limits need tuning. The active database provider itself is startup/deployment configuration and is shown read-only.
Runtime	Host-device branding override or Python subprocess paths need a deliberate deployment change.

For these areas, use the canonical Configuration Workspace reference and the feature/integration documentation rather than changing settings during routine health checks.

A practical monthly Platform Configuration review

A useful monthly review is short and evidence-driven:

1. Open GeoIP / Access Location and confirm the MMDB file/update schedule and a test lookup.
2. Open Country Flags and confirm coverage/fallbacks are acceptable.
3. Check FoodKeeper Shelf Life refresh age and whether custom rows still make sense.
4. Review Slow Recipe Websites for stale/recoverable domains and unexpected growth.
5. Review Recipe Discovery source/rule health if users actively depend on discovery or Plan Meals Find & Add.
6. Review Performance and Purge policy only against actual Performance/Data Cleanup evidence; do not tune them reflexively.
7. Review Certificates/Updates/AI according to the operating cadence in the main Administration guide.
8. Review Security after any network, reverse-proxy, external URL, authentication, or extension-origin change.

Ingredient Densities are normally reviewed when the system exposes a bad volume↔weight assumption, not because a calendar says to edit them.

What good platform configuration looks like

A well-maintained platform normally has:

• current/working GeoIP data and correct real-client-IP capture;
• country indicators with acceptable SVG/fallback coverage;
• a FoodKeeper catalog that has been refreshed according to your operating policy, with only intentional customizations;
• ingredient density overrides only where real conversion accuracy requires them;
• a slow-site list that explains known URL-only quick-add exceptions rather than accumulating forgotten domains indefinitely;
• curated Recipe Discovery rules that return recipe-focused sources without excessive noise;
• performance collection enabled with a meaningful slow-request threshold;
• retention policy that is actually being executed and leaves enough history for administration/support;
• no casual changes to security, runtime, database-provider, or provider-credential settings without a specific reason.

When those conditions are true, most Platform configuration should remain stable. Administration should be driven by provider/source changes, observed system behavior, and operational evidence—not by a desire to continually change settings.