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

After Your First Blackcap Login: Self-Hosted Setup Guide

Audience: A System Admin who has already installed Blackcap on a Raspberry Pi, GCP VM, or another Linux server and logged in successfully for the first time. This guide covers application UI configuration, not installation, OS hardening, reverse-proxy setup, or shell commands. Use Installation for those prerequisites.

Blackcap can be used without every integration below. Start with a working local recipe, then configure optional providers as needed. Platform settings apply across the instance; Organization settings generally affect only the selected organization.

1. Confirm the installation and your administrative context

  1. Open System and verify the expected Blackcap version, instance health, database mode, and active organization.
  2. Open Administration โ†’ Configuration โ†’ Platform and check the environment and application URLs. Use the public HTTPS URL on a remotely accessible server; do not save an internal Pi hostname as a public callback URL.
  3. Visit Users / Permissions to confirm your System Admin role and create a separate daily-use Organization Admin account where appropriate. Test with a nonadmin account before inviting others.
  4. Use Backup to confirm a current backup destination and restoration plan. Set retention and scheduling appropriate to your installation. Keep a backup before experimenting with providers or imported recipes.

Pi: Expect fewer resources and slower large AI/cache/background jobs. Consider worker/memory guidance in the Pi documentation. General Linux/GCP: Confirm background workers, durable job recovery, outbound HTTPS, and PostgreSQL connectivity where enabled. These are deployment health checks, not UI configuration differences.

2. Security, HTTPS, sessions, and multifactor authentication

In Platform โ†’ Security / Authentication, review session lifetime, allowed origins and trusted proxy handling. Configure MFA for administrator accounts. If prompted to remember this browser for 90 days, use a persistent, normal browser profile; incognito sessions, cookie deletion, domain changes, and old full-version User-Agent bindings can require MFA earlier. Remembering a browser does not extend the underlying account session. Do not share one trusted-browser cookie across environments.

If users connect through an HTTPS reverse proxy, confirm the configured public host, secure cookies, and forwarded-request settings. Pi and Linux deployments follow the same UI steps but use different host and proxy topology. Do not enable untrusted forwarding merely to make redirects work.

3. Configure outbound email first

Go to Platform โ†’ Email / SMTP (see the email and consent management guide for the current fields). Add your sender identity, Reply-To address, SMTP host, port, TLS mode, account name and provider-issued credential/app password. Use the Test Email function and verify delivery, including spam folders. Set the service/notification sender used for invitations, account verification and recovery emails.

Where consent/tracker integration is enabled, verify communication preferences, sender mailbox registrations, unsubscribe/deletion behavior and bounce handling under the appropriate panels. Do not assume successful SMTP sending means bounce processing is configured. Use the Email & Consent Management guide to verify workflows.

Pi: Residential/ISP connections may block outgoing port 25; an authenticated submission service with TLS is preferred. GCP/Linux: Verify the cloud firewall or provider's outbound SMTP restrictions and configured DNS records. Credentials remain managed in Blackcap's secret settings, not in documentation.

4. External sign-in providers (optional)

In Platform โ†’ External Authentication / Login Providers, add each provider only when it is needed. For Google, Microsoft, or other supported OIDC/OAuth sources:

  1. Create an app/client with the identity provider.
  2. Copy the callback/redirect URI shown by Blackcap into the provider console; do not guess it. Redirect URLs must use the real public HTTPS host and exact path.
  3. Configure the client ID, client secret, provider endpoint/tenant/scopes as requested by Blackcap, then save and test with a separate user account.
  4. Confirm account linking, email verification, role mapping and fallback administrator login work before enabling public access.

Different deployment methods change the public hostname and external networking, not the basic steps in this UI. Keep a tested local administrator login available while configuring SSO.

5. Organizations, users, permissions and personal preferences

Create or configure the intended organization and invite members through Users. Review roles, recipe visibility, sharing, kitchen inventory, and the default settings for meal planning. Under Organization Configuration, configure dietary preferences and restrictions (which the Meal Planner and Adapt Recipe AI tools can use), recipe types and organizational defaults. Test that changes do not affect another organization.

6. AI providers, models, Quality Profiles and funding

In Platform โ†’ AI, add one or more provider connections (for example, OpenAI, Gemini, Anthropic) using their own API keys. Test connectivity and refresh each model catalog. Only enable models that support the use case and output format you need.

Create and enable Quality Profiles for selected use casesโ€”Plan Meals, Create Recipe, Adapt Recipe, Recipe Image Generation, Support Chat and other features as required. Review model, context/output limits, reasoning effort, timeout, failure handling and AI Seed pricing. For Bulk Adapt Recipe, configure the base charge, number of Recipes included, additional Recipes per group and additional Seeds per group. Confirm funding/Seed balances, perform a small real-provider test, and verify AI Usage records input/output evidence and provider cost. Always review the estimate before authorizing spending.

Use AI Usage for full provider/Seed records and retention, not only the job progress indicator. Provider model deprecation indicators warn you when a Quality Profile needs reassignment. If a provider has a small structured-output limit, use fewer recipes per batch.

7. Recipe discovery, capture and optional external sources

Under Platform Configuration โ†’ Recipe Discovery / Providers, select the discovery/search providers you want and set API credentials, domains, include/exclude rules and appropriate quotas. Test a simple URL import and a manual recipe before scaling up. Configure external recipe imports, social-source providers and the Chrome extension only if you need them. Confirm captured images, editable content and the PDF/cache renderer work.

If using Google Drive or Dropbox for Blackcap cloud backups, configure those under Platform โ†’ Providers / Cloud Backup, test the connection, and verify that a backup reaches the intended destination. These are backup integrations, not general-purpose Recipe Library imports.

8. Shopping integrations and โ€œShop Withโ€ providers

Open Platform / Organization Configuration โ†’ Shopping / Shop With as presented on your installation. Enable only supported retailers or integrations needed by your users. Configure provider-specific IDs, tokens, store/region and permitted navigation when prompted. Test a shopping list containing two or three known ingredients, confirm quantity/multiplier behavior, and verify the external handoff does not disclose unrelated recipe data.

Some providers may only open a store/search page while others support richer cart handoff. Treat the configuration panel and current provider-specific documentation as authoritative for each integration. A provider account may be needed separately from Blackcap.

9. Kitchen inventory, catalog images, shelf life and optional utilities

In Platform Configuration, inspect the Ingredients catalog, TheMealDB image-sync option, USDA FoodKeeper shelf-life data and Ingredient Density tools. Sync/refresh only after reviewing the source/license requirements. Set organizational Kitchen Inventory mode (On Hand or Full with quantities) before entering inventory packages. If using estimated best-by dates, review that they are planning aidsโ€”not food-safety guarantees.

Configure GeoIP and country-flag updates only if access-location diagnostics are useful. Use the documented updater/schedule rather than repeated manual refreshes. Optional voice and external service integrations are configured only if you plan to use those features.

10. Displays, Letโ€™s Cook and the first end-to-end recipe

Add and test the selected display target: local Pi/e-ink, remote Pi client, hosted web receiver, kiosk or mock display as supported by your installation. For physical Pi displays, perform device/service pairing outside this guide, then confirm the configured receiver appears online in the UI.

Create or import a small recipe, verify its thumbnail and PDF, add it to a Meal Plan, add its ingredients to a Shopping List, open Letโ€™s Cook, and send it to an intended display. Create an adaptation only after the basic recipe works. Adaptations retain their own recipe ID, cache, source relationship and dietary metadata.

11. Maintenance and verification before inviting users

Review Database Maintenance, backup schedules, AI Usage retention, scheduled tasks and the System dashboard. SQLite-only maintenance options such as VACUUM do not apply to PostgreSQL. Run API Tester for a limited configuration smoke test, and schedule the normal System Admin Regression Tests during an idle periodโ€”especially on lower-memory Pi devices. Note that some live-provider regression steps may incur AI Seeds and a small actual provider charge.

Check the tracker heartbeat and license/package diagnostics if your installation uses the Microwave Pie tracker. Confirm email recovery, external login, one recipe cache, one background job, a small shopping handoff, and backup restoration before production use.

Installation-specific reminders

Topic Raspberry Pi / SQLite General Linux / GCP / PostgreSQL
Admin UI setup Same configuration steps Same configuration steps
Public URL / OAuth callback Use the Pi's reachable HTTPS hostname Use deployed HTTPS host/load balancer hostname
Database maintenance SQLite VACUUM can be scheduled PostgreSQL manages its own maintenance; hide SQLite controls
Job concurrency Prefer conservative worker/memory settings Configure according to available memory and worker capacity
Recipe displays May drive a local e-ink screen Usually uses web/kiosk or remote Pi receivers
Provider connectivity Verify ISP/router outbound restrictions Verify VPC/firewall/cloud egress rules
Backups Protect local SD/SSD storage Protect DB and persistent file/object storage

Further reading

On this page