Microwave Pie
Browse documentation

🧭 Start Here

Blackcap Overview ✨ Blackcap Feature Catalog Installation First Run

🚀 Deploy Blackcap

Platform Stacks and Raspberry Pi Hardware Raspberry Pi Deployment Raspberry Pi Client Services GCP Deployment Application Updates 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 Requests API Tester and Postman Instance Reporting

🍽️ 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

📅 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

🧩 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

🔌 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 API Architecture Security and Organization Scoping UI, Icons, and Documentation Assets Blackcap-Safe Emoji Documentation Standards Terminology

⚠️ Troubleshoot Blackcap

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

Backups and Restore

Audience: Org Admin, System Admin, Deployment Administrator Related: Cloud Storage · Background Jobs And Schedules · Backups · Sqlite And Postgresql

Blackcap supports local backups and configured Dropbox or Google Drive destinations. Backups are organization-aware where appropriate, include database and filesystem artifacts according to the active database provider, and use restore staging with bounded retention.

SQLite deployments back up the local application database. GCP/PostgreSQL deployments should rely on Cloud SQL backup capabilities for the database while Blackcap backups protect supported application artifacts and organization exports. The default remote folder is host-aware.

Backup destinations

  • Local Only
  • Dropbox
  • Google Drive

Restore safety

Restores use staging, retain a bounded number of staged packages, validate package contents, and apply organization/provider boundaries. Review the job detail when a restore fails rather than manually copying partial database files.

Backups

Blackcap Pi backups include the primary application database:

  • data/blackcap.db
  • data/blackcap.db-wal when present
  • data/blackcap.db-shm when present

The backup process attempts a SQLite WAL checkpoint before collecting database files, then still includes sidecar files when they exist.

The database is now canonical for mutable backup control data:

  • cloud_backup_provider_tokens stores Dropbox/Google Drive provider token payloads encrypted in SQLite.
  • cloud_backup_state stores backup status/history by organization.
  • organization_backup_runs stores backup/export run history, including Default/full platform runs as backup_scope='platform'.

Legacy token/state files such as cloud_backup/tokens/*.json and backup_state.json are no longer active runtime state.

Filesystem artifacts intentionally included in backups

Backups include source/cache artifacts that are useful or expensive to regenerate:

  • recipe_cache/ or the active organization's scoped recipe-cache folder
  • noun_cache/ or the active organization's scoped downloaded-icon cache
  • emoji_cache/ for full/platform backups
  • local backup ZIP artifacts when retained by the backup destination

Shopping lists, shopping-list items, and recipe-cart state are also SQLite-only. New backups must not recreate or depend on shopping_lists/.

Noun Project rules are not stored in the icon cache folder; they live in noun_project_rules and are backed up through SQLite.

Filesystem artifacts intentionally excluded from backups

Generated display/render artifacts should not be treated as canonical backup data. They are regenerated by menu, recipe, meal-plan, receiver, and display-content push flows after restore.

Examples:

  • display_previews/
  • current_view.png
  • final_preview.png
  • recipe_preview.png
  • current_snippet.png
  • last_snippet.png
  • temp_full.png
  • ocr_preview.png
  • menu_crop_preview.png
  • cloud_backup/restore_staging/
  • migration_backups/
  • __pycache__/

Deprecated current recipe image

recipe_cache/current_recipe_image.png is deprecated and should no longer be created by recipe cache builds. Async cache generation only updates recipe-specific artifacts such as:

  • recipe_cache/<recipe_id>.pdf
  • recipe_cache/<recipe_id>.png
  • recipe_cache/<recipe_id>_rendered.png

Display-current state should be managed by display render/restore paths, not by background cache generation.

Auth database boundary

data/blackcap.db is the single primary SQLite database. Auth, user, membership, token, security, audit, application, configuration, backup, and Noun Project rule data now live in the same database.

Provider-aware platform backup

SQLite platform backups include the local database and available WAL sidecars. PostgreSQL platform backups contain Blackcap configuration and filesystem artifacts only; Cloud SQL automated backups and point-in-time recovery are the database recovery mechanism. Provider-specific platform backups cannot be restored across backends.

Scheduled backup due state and retention

Automatic backup due state is stored durably in the private internal service-state table and behaves the same on SQLite and PostgreSQL. Manual backups do not reset the scheduled interval. Failed scheduled backups retry after four hours, and a database lease prevents duplicate starts. Backup-history purge protects the newest configured runs per organization/scope/provider/destination plus the latest successful run.

On this page