Zest — User Manual

Zest is a self-hosted culinary diary that stores your recipes, memories, and the stories around the table. This manual covers everything you need to get started and make the most of every feature.

1. Installation

Requirements

  • • Docker and Docker Compose installed on your machine
  • • About 200 MB of disk space (image + dependencies)
  • • Any hardware: Raspberry Pi 4, NAS, old laptop, cloud VM — anything that runs Docker

Quick Start 

git clone https://github.com/MartinSantosT/myzest.git
cd myzest
cp .env.example .env
docker compose up -d

Open http://localhost:8000 in your browser. That's it.

Secure Your Instance

  1. Change the secret key — Open .env and replace the default value: 

    # Generate a secure key:
python -c "import secrets; print(secrets.token_urlsafe(32))"

    Paste the result as ZEST_SECRET_KEY in your .env file, then restart: 

    docker compose down && docker compose up -d

  2. Change the default password — Log in with admin@zest.local / admin, then go to Settings → Profile and update your password immediately.

Custom Port

Edit docker-compose.yml to change the port: 

ports:
  - "3000:8000"   # Access Zest on port 3000

Reverse Proxy

If you're exposing Zest to your local network or the internet, place it behind a reverse proxy (Nginx, Caddy, Traefik, or Nginx Proxy Manager). See the README for an example Nginx configuration.

2. First Steps

When you first log in, Zest shows a brief onboarding experience:

  1. Welcome — Introduction to Zest's philosophy
  2. Your recipes, your story — How to create or import your first recipe
  3. Memories — What makes Zest different: connecting photos and moments to recipes

You can skip the onboarding at any time, or click "Create my first memory" to jump right in.

The Dashboard

After onboarding, you'll see the main dashboard with:

  • • Recipe grid — All your recipes displayed as cards with photos, ratings, and time estimates
  • • Sidebar (left) — Navigation between Recipes, What to Cook, Shopping List, Cookbooks, Memories, and Settings
  • • Search bar — Filter recipes by text, category, tag, or rating
  • • + New Recipe button — Create a new recipe from scratch

3. Recipes

Creating a Recipe

  1. Click + New Recipe (or the orange button in the top right)
  2. Fill in the details:
    • ◦ Title (required)
    • ◦ Description — A short intro or story about the dish
    • ◦ Prep Time & Cook Time — In minutes
    • ◦ Servings — How many portions the recipe makes
    • ◦ Photo — Click the image area to upload a hero photo. You can add up to 4 photos total (1 hero + 3 additional)
  3. Ingredients — Add one per row. Each ingredient has structured fields:
    • ◦ Quantity (number)
    • ◦ Unit (cups, grams, tbsp, etc.)
    • ◦ Name (the ingredient itself)
    • ◦ Note (optional: "finely chopped", "room temperature")
  4. Steps — Add preparation steps in order. Drag to reorder if needed.
  5. Categories & Tags — Assign categories and color-coded tags (see section 4)
  6. Click Save

Editing a Recipe

Click any recipe card to open its detail view, then click the Edit (pencil) button. All fields are editable. Changes are saved when you click Save.

Deleting a Recipe

In the recipe detail view, click Delete (trash icon). You'll be asked to confirm. Deletion removes the recipe, its ingredients, steps, images, and any associated cookbook entries. Linked memories are preserved but their recipe association is removed.

Rating & Favorites

  • • Rating — Click the stars (1–5) on any recipe card or in the detail view
  • • Favorites — Click the heart icon to toggle a recipe as favorite. Use the sidebar filter to view only favorites.

Multi-Photo Support

Each recipe supports up to 4 photos: one hero image (displayed on the card) and 3 additional photos visible in the detail view. Click the "+" area below the hero image to add more photos.

4. Categories & Tags

Categories

Categories are broad classifications for your recipes (e.g., "Mexican", "Desserts", "Soups", "Quick Meals").

  • • Adding categories — In the recipe modal, type in the category field. If it doesn't exist, Zest creates it automatically.
  • • Autocomplete — As you type, matching categories appear as suggestions.
  • • A recipe can belong to multiple categories.

Tags

Tags are flexible, color-coded labels for cross-cutting concerns (e.g., "Spicy", "Kid-friendly", "Date night", "Meal prep").

  • • Adding tags — In the recipe modal, select existing tags or create new ones.
  • • Custom colors — Each tag has a color. Click the color swatch to change it.
  • • Filtering — Click any tag in the sidebar or recipe grid to filter by that tag. Multiple filters can be combined.

5. Importing Recipes from URLs

Zest includes a powerful 4-tier scraping engine that can extract recipes from virtually any cooking website.

How to Import

  1. Click the "Import from URL" option in the sidebar
  2. Paste the URL of the recipe page
  3. Click Scrape
  4. Zest shows a preview with the extracted data: title, description, ingredients, steps, times, servings, and photo
  5. Review and edit anything before saving
  6. Click Save to add it to your collection

How the Scraper Works

Zest tries four methods in order, using the first one that succeeds:

  1. recipe-scrapers library — Supports 400+ popular cooking sites with site-specific parsers
  2. JSON-LD — Reads structured data embedded in the page (Schema.org Recipe format)
  3. Microdata — Reads HTML microdata attributes
  4. Heuristic analysis — Intelligent CSS selector matching for unstructured pages

Imported recipes are automatically tagged with the "Imported from Internet" category and a blue badge showing the source domain.

6. Ingredients & Portion Calculator

Structured Ingredients

Each ingredient has four fields:

  • • Quantity — A number (supports decimals: 0.5, 1.25, etc.)
  • • Unit — The measurement (cups, grams, ml, tbsp, tsp, oz, lb, etc.)
  • • Name — The ingredient name
  • • Note — Optional details ("diced", "at room temperature", "optional")

Portion Calculator

On any recipe detail view:

  1. Look for the servings indicator (e.g., "Serves 4")
  2. Use the + and − buttons to adjust the number of servings
  3. All ingredient quantities recalculate proportionally in real-time
  4. Fractions are displayed beautifully: ½, ⅓, ¼, ⅔, ¾

For example, a recipe for 4 servings with "2 cups of flour" scaled to 6 servings shows "3 cups of flour".

7. What to Cook?

This is one of Zest's unique features. It answers the question: "I have chicken, rice, and onion — what can I make?"

How to Use

  1. Click "What to Cook?" in the sidebar
  2. Start typing an ingredient name — suggestions appear from your recipe database
  3. Click to add ingredients to your list
  4. Zest instantly shows matching recipes, ranked by match percentage

Understanding the Results

Each result shows:

  • • Match percentage — How many of the recipe's ingredients you have (green = 75%+, orange = 50%+, gray = below 50%)
  • • Missing ingredients — Highlighted in red so you know what you'd need to buy
  • • Portion adjustment — Scale the recipe right from the results
  • • "Add to Shopping List" — One click to add the missing ingredients to your shopping list

8. Shopping List

Adding Items

There are several ways to add items to your shopping list:

  • • From any recipe detail view, click "Add to Shopping List"
  • • From the "What to Cook?" results, click "Add missing items"
  • • Manually type items in the shopping list view

Smart Combining

When you add ingredients from multiple recipes, Zest combines them intelligently. If Recipe A needs 200g rice and Recipe B needs 100g rice, your shopping list shows 300g rice.

Using the List

  • • Check off items as you shop
  • • The list persists between sessions
  • • Clear completed items or the entire list when done

9. Memories

Memories are what makes Zest different from every other recipe manager. A Memory connects photos, dates, locations, and stories to a recipe — turning your recipe collection into a culinary diary.

Creating a Memory

  1. Click Memories in the sidebar
  2. Click + New Memory
  3. Fill in the details:
    • ◦ Title — "Christmas dinner 2025", "First attempt at sourdough", etc.
    • ◦ Photos — Upload up to 10 photos. JPEG photos with EXIF data will auto-fill the date and location.
    • ◦ Date — When it happened (auto-detected from photo EXIF if available)
    • ◦ Location — Where it happened (auto-detected from GPS coordinates via reverse geocoding)
    • ◦ Story — The description of what happened, who was there, why it was special
    • ◦ Linked Recipe — Associate this memory with a recipe from your collection
  4. Click Save

Photo Features

  • • Multi-photo upload — Select multiple photos at once
  • • EXIF auto-detection — Zest reads the date and GPS coordinates from JPEG photos automatically
  • • Reverse geocoding — GPS coordinates are converted to readable place names (e.g., "Brooklyn, New York")
  • • HEIC/HEIF support — iPhone photos work out of the box
  • • Image optimization — Photos are automatically resized (max 1920px) and converted to JPEG for optimal storage

Viewing Memories

  • • Grid view — All memories displayed as cards with cover photo, date, location, and linked recipe
  • • Detail view — Click any memory to see the full photo gallery, story, and metadata
  • • From recipe view — Each recipe shows its associated memories in a dedicated section

Editing & Deleting

  • • Click the Edit button in the memory detail view to modify any field or add/remove photos
  • • Click Delete to permanently remove the memory and its photos

10. Moment Cards

Moment Cards turn your memories into beautiful, shareable images designed for social media.

Generating a Card

  1. Open any memory that has at least one photo
  2. Click the Share button (gradient orange button)
  3. Choose a template:
    • ◦ Story (1080×1920) — Instagram Stories, TikTok
    • ◦ Square (1080×1080) — Instagram feed, WhatsApp
    • ◦ Landscape (1200×630) — Facebook, Twitter/X
  4. Preview updates in real-time
  5. Click Download or use the Share button (on mobile, uses the native share sheet)

Card Design

Each card includes:

  • • Your photo as a full-bleed background with a dark gradient overlay
  • • The memory title in large, bold text
  • • Date and location
  • • Linked recipe name
  • • Subtle Zest branding (orange bar + "Zest" text)

11. Cookbooks

Cookbooks are curated collections of recipes — perfect for organizing by theme, sharing with friends, or creating gift-worthy PDF exports.

Creating a Cookbook

  1. Click Cookbooks in the sidebar
  2. Click + New Cookbook
  3. Add a name, description, and optionally an author's note
  4. Cover photos — Upload up to 2 cover images. Use drag-to-reposition to frame them perfectly.
  5. Add recipes — Select recipes from your collection to include
  6. Click Save

Managing Cookbooks

  • • Reorder recipes — Drag recipes within a cookbook to set the order
  • • Edit — Change name, description, covers, or recipe selection at any time
  • • Delete — Removes the cookbook but not the recipes themselves

Author's Note

Each cookbook has an optional personal note that appears at the top when shared or exported. Use it for dedications, context, or a personal message ("Mom, here are our family recipes I've been collecting...").

12. Sharing

Public Share Links

  1. Open a cookbook
  2. Click Share
  3. Zest generates a unique public link (e.g., http://yourserver/shared/abc123)
  4. Anyone with the link can view the cookbook and all its recipes — no account needed
  5. You can revoke the link at any time

What Recipients See

The shared view is a beautiful, read-only presentation of your cookbook with cover photos, recipe cards, and full recipe details (ingredients, steps, photos). Your author's note is displayed at the top.

13. PDF Export

Export cookbooks as professional PDFs suitable for printing or gifting.

How to Export

  1. Open a cookbook
  2. Click the PDF button
  3. Zest generates a PDF with:
    • ◦ Cover page with the cookbook name and date
    • ◦ Recipe cards with ingredients, steps, and metadata
    • ◦ Proper typography with DejaVu fonts (full Unicode support)
  4. The PDF downloads automatically

14. Settings & Profile

Access settings by clicking your avatar or the gear icon in the sidebar.

Profile

  • • Name — Your display name
  • • Email — Your login email
  • • Password — Change your password (requires current password)
  • • Avatar — Upload a profile photo

Categories & Tags

  • • View, rename, or delete categories
  • • View, rename, change color, or delete tags

15. Backups & Data

Automatic Backups

  1. Go to Settings → Backups
  2. Enable automatic backups
  3. Configure:
    • ◦ Frequency — Every 12 hours, 24 hours, or 7 days
    • ◦ Retention — How many backups to keep (default: 7)
    • ◦ Include images — Whether to include uploaded photos in backups

Backups are stored in the ./data/backups/ directory on your host machine.

Manual Export

  • • Full backup (ZIP) — Exports the complete database + all images. Use this for disaster recovery or migrating to a new server.
  • • JSON export — Exports recipes in a portable JSON format for interoperability.

Import

  • • Database import — Upload a full backup ZIP to restore your entire instance. Warning: this replaces the current database completely.
  • • JSON import — Upload a JSON file to add recipes to your existing collection. Duplicates are detected and skipped.

Migration Between Servers

  1. Export a full backup from the old server
  2. Set up a fresh Zest instance on the new server
  3. Import the backup
  4. Done — all recipes, memories, cookbooks, and images are restored

16. Dark Mode

Click the moon/sun icon in the sidebar header to toggle between light and dark themes. Your preference is saved locally and persists across sessions.

17. Keyboard Shortcuts

Shortcut Action
Esc Close any open modal or overlay

18. Troubleshooting

"Port 8000 is already in use"

Change the port in docker-compose.yml: 

ports:
  - "9000:8000"

On Windows, ports 7681–8782 may be blocked by Hyper-V. Use port 9000 or higher.

Photos won't upload

  • • Check that the ./app/static/uploads directory exists and is writable
  • • Maximum file size depends on your reverse proxy configuration. Add client_max_body_size 20M; to your Nginx config.

Database migration errors

Run the migration script manually: 

docker exec zest_backend python migrate.py

The script is idempotent (safe to run multiple times) and creates a backup before making changes.

HEIC photos not working

HEIC support requires the pillow-heif package, which is included in the default Docker image. If you're running Zest outside Docker, install it separately: 

pip install pillow-heif

Forgot your password

If you're locked out, you can reset via the database: 

docker exec -it zest_backend python -c "
import bcrypt
from app.database import SessionLocal
from app.models import User
db = SessionLocal()
user = db.query(User).filter(User.email == 'your@email.com').first()
user.password_hash = bcrypt.hashpw(b'newpassword', bcrypt.gensalt()).decode()
db.commit()
print('Password reset successfully')
"

Health Check

Verify your instance is running: 

curl http://localhost:8000/api/health
# {"status": "healthy", "recipes": 42, "users": 1}

Use this endpoint with Uptime Kuma, Healthchecks.io, or any monitoring tool.

Need Help?

Open an issue on GitHub — we're happy to help.

🍊 Zest — Because recipes deserve memories.