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
- Open System and verify the expected Blackcap version, instance health, database mode, and active organization.
- 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.
- 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.
- 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:
- Create an app/client with the identity provider.
- 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.
- Configure the client ID, client secret, provider endpoint/tenant/scopes as requested by Blackcap, then save and test with a separate user account.
- 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
- Platform Configuration
- Organization Configuration
- Email and Consent Management
- Administration and Operations
- AI Provider Billing
- Database Administration
- Installation โ separate OS/application-install procedure