ClipCookBook

A self-hosted web application to extract, save, and organize recipes from social media using AI.
Turn Instagram Reels, TikToks, and other social media posts into structured cooking instructions instantly.

Report Bug · Request Feature

---

Table of Contents

1. About The Project
   • Built With
2. Key Features
3. iOS Apple Shortcut
4. Getting Started
   • Prerequisites
   • Installation (Docker)
5. AI Integration
6. License
7. Contact

---

About The Project

ClipCookBook is your personal, self-hosted database for all those delicious recipes you find while scrolling through social media. Instead of saving a post and never looking at it again, ClipCookBook uses AI (like Google Gemini) to extract ingredients, portions, and step-by-step instructions directly from the post URL.

It's designed to be fast, private, and fully under your control.

Built With

• Next.js
• React
• TypeScript
• Prisma (SQLite)
• Google Gemini AI
• Docker

(back to top)

---

Key Features

• 📱 Social Media Extraction — Paste an Instagram, TikTok, or YouTube link and let AI do the work.
• 🤖 AI-Powered — Automatically identifies ingredients, amounts, units, and cooking steps (PROCESS_METHOD=ai).
• 🔍 Deep Search — Analyze video audio/visuals when captions are empty or incomplete.
• 🍪 Instagram cookies helper — Optional session cookies for video download (/cookies + local Playwright tool).
• 🎥 Media Gallery — Keeps the original video and thumbnails alongside the recipe.
• 📅 Automated Backups — Optional automatic backups; one-shot admin alerts on failure.
• 📧 Email Integration — Recipes via SMTP + ops alerts (SMTP_ALERT_TO).
• 🔒 Self-Hosted — You own your data. Simple SQLite database with easy Docker deployment.

(back to top)

---

iOS Apple Shortcut

Save recipes effortlessly directly from your iPhone or iPad! We have created an Apple Shortcut that integrates ClipCookBook seamlessly into your iOS Share Sheet.

When you find a recipe on apps like Instagram or TikTok, simply share the post to this shortcut. It will automatically open your self-hosted ClipCookBook page and pre-fill the link. All you have to do is click "Generate Recipe".

Installation Steps

1. Download the shortcut file here: Save recipe.shortcut
2. Open the downloaded file in your iOS Files app.
3. Tap Set Up Shortcut (Configureer opdracht).
4. Enter the URL where your ClipCookBook instance is hosted (for example: https://recipes.yourdomain.com or your ip:port, like http://192.168.1.10:9416).
5. Tap Add Shortcut (Voeg opdracht toe).

💡 Pro Tip: Once installed, you can edit your iOS Share Sheet actions to pin this shortcut to the top for even faster access!

(back to top)

---

Getting Started

The recommended way to install ClipCookBook is via Docker.

Prerequisites

• Docker and Docker Compose installed on your server.
• (Optional) A Google Gemini API Key (Free tier is supported!).

Installation (Docker)

1. Create a directory for the project and navigate into it.
2. Create a file named docker-compose.yml.
3. Paste the following configuration:

services:
  clipcookbook:
    image: ghcr.io/minemap-nl/clipcookbook:latest
    container_name: ClipCookBook
    restart: always
    stop_grace_period: 5s
    ports:
      - "9416:3000"
    volumes:
      - ./db:/app/data
      - ./thumbnails:/app/public/thumbnails
      - ./videos:/app/public/videos
      - ./backups:/app/backups
    environment:
      - DATABASE_URL=file:/app/data/dev.db
      - LANGUAGE=en # UI Language ('en' or 'nl')
      - PROCESS_METHOD=ai # Set to 'manual' to disable AI features
      - GEMINI_API_KEY=your-gemini-api-key
      - GEMINI_MODEL=gemini-3.5-flash
      - APP_NAME=ClipCookBook
      - APP_URL=https://clipcookbook.yourdomain.com
      - SITE_PASSWORD=your-secret-password
      - JWT_SECRET=your-random-jwt-secret
      - AUTO_BACKUP=true
      - SMTP_ALERT_TO=your-alert-email@example.com
      - SMTP_HOST=your-smtp-host
      - SMTP_PORT=587
      - SMTP_USER=your-email
      - SMTP_PASS=your-password
      - YT_DLP_AUTO_UPDATE=true
      - YT_DLP_AUTO_UPDATE_ON_STARTUP=false
      - YT_DLP_AUTO_UPDATE_NIGHTLY=true
      - YT_DLP_UPDATE_HOUR=3

4. Ensure folders are writable by the container user (uid 1001), then start:

mkdir -p db thumbnails videos backups
# Linux example:
sudo chown -R 1001:1001 db thumbnails videos backups
docker compose up -d

Optional Instagram video downloads: place a Netscape cookies.txt in ./db/cookies.txt (or use /cookies + tools/instagram-cookies). See tools/instagram-cookies/README.md.

(back to top)

---

AI Integration

ClipCookBook currently leverages Google Gemini AI to transform unstructured social media data into structured recipes.

• Free Tier Supported: You can use a free tier API key from Google AI Studio.
• Default model: gemini-3.5-flash (override with GEMINI_MODEL). Older gemini-2.5-flash is capacity-limited and scheduled for retirement.
• Strict AI mode: With PROCESS_METHOD=ai, imports use Gemini only (no silent fallback to the heuristic parser). Failures surface as clear import errors.
• Deep Search: When enabled on import, video audio/visuals are analyzed (useful for reels without a recipe caption).
• Manual mode: Without AI (PROCESS_METHOD=manual), a built-in algorithm tries to parse descriptions; photo extraction requires AI.
• Future Updates: Support for additional AI providers (like OpenAI or local LLMs) is planned for future releases.

(back to top)

---

License

Source Available – MIT with Commons Clause

This project is licensed under the MIT License with the Commons Clause condition.

• ✅ You may use, copy, modify, and distribute this software for personal or internal business use.
• ✅ You may use this software to share files with clients or partners as part of normal business operations.
• ❌ You may not sell this software or offer it as a commercial SaaS product where the primary value comes from the software itself.

See the LICENSE file for details.

(back to top)

---

Contact

Minemap / Famretera
Website: https://clipcookbook.famretera.nl

Project Repository: https://github.com/minemap-nl/ClipCookBook

(back to top)

---