Installation & Setup

This guide walks you through setting up ClipCookBook on your own system.

Prerequisites

Before you begin, make sure you have the following installed:
- Bun: The JavaScript runtime and package manager used exclusively for this project.
- Docker & Docker Compose: (Optional, but recommended for the best experience).
- FFmpeg: Required for processing videos. Note: this is already included when using Docker.
- A Google Gemini API Key: Required for the AI extraction features.

Local Development (Without Docker)

If you want to develop without Docker:

Clone the repository
Install dependencies
bash bun install
Environment variables (.env)
Create a .env file in the root directory of the project and configure the application. Below is a list of available environment variables:

Variable	Description	Default	Required?
`DATABASE_URL`	The SQLite database connection string.	`file:./dev.db`	Yes
`PROCESS_METHOD`	`ai` for Gemini extraction, or `manual` to disable AI. In `ai` mode, failures are reported clearly (no silent heuristic fallback).	`ai`	No
`GEMINI_API_KEY`	Your Google Gemini API key for AI extraction.		Yes (if `ai`)
`GEMINI_MODEL`	Gemini model to use.	`gemini-3.5-flash`	No
`APP_NAME`	The display name of the application.	`ClipCookBook`	No
`NEXT_PUBLIC_LANGUAGE`	The UI language. Use `en` or `nl`.	`en`	No
`APP_URL`	The public URL where you host the application.		No
`SITE_PASSWORD`	Global password required to access the application.		No
`JWT_SECRET`	Cryptographic secret for signing auth tokens.		Yes (if password used)
`AUTO_BACKUP`	Set to `true` to enable daily database backups.	`false`	No
`SMTP_HOST`	SMTP server for share emails and operational alerts.		No
`SMTP_PORT`	SMTP server port.	`587`	No
`SMTP_USER`	SMTP username or email address.		No
`SMTP_PASS`	SMTP password.		No
`SMTP_ALERT_TO`	Inbox for alerts (backup failures, missing media, expired Instagram cookies).		No
`YT_DLP_COOKIES`	Path to a Netscape cookie file for Instagram downloads.	`data/cookies.txt`	No
`YT_DLP_AUTO_UPDATE`	Master switch for automatic `yt-dlp` updates.	`true`	No
`YT_DLP_AUTO_UPDATE_ON_STARTUP`	Update `yt-dlp` when the app/container starts.	`false`	No
`YT_DLP_AUTO_UPDATE_NIGHTLY`	Schedule a nightly `yt-dlp` update.	`true`	No
`YT_DLP_UPDATE_HOUR`	Hour (0–23, local time) for the nightly update.	`3`	No

For Instagram video downloads you typically need cookies. See Instagram & Cookies.
4. Initialize the database
bash bunx prisma db push
5. Start the development server
bash bun run dev
On Windows, dev uses Webpack by default (Turbopack workaround). Use bun run dev:turbo if you prefer Turbopack.

The application is now running locally at http://localhost:3000.

Running with Docker Compose

The simplest and most robust way to run this application is via Docker Compose, as it also includes all the tooling for video downloading and processing (yt-dlp and ffmpeg).

Make sure the .env configuration is present (see above). For production, set at least PROCESS_METHOD, GEMINI_API_KEY, and preferably SMTP_ALERT_TO plus cookie-related settings if you import Instagram videos.
Start the container:
bash docker-compose up -d --build

The application will now be available on port 3000 of the host machine.

Volumes & permissions

Mount (or create) persistent directories for the database, videos, thumbnails, and backups. The container user expects write access; if backups or media writes fail with EACCES, fix ownership on the host, for example:

sudo chown -R 1001:1001 ./backups ./db ./videos ./thumbnails
sudo chmod -R u+rwX ./backups ./db ./videos ./thumbnails
docker restart Social-Recipe-Saver

(Adjust paths and container name to match your compose file.)

Troubleshooting

FFmpeg Not Found: Check that FFmpeg is successfully added to your PATH if you are running locally (without Docker).
Database errors: Run bunx prisma generate followed by bunx prisma db push.
Instagram download / login errors: Refresh cookies via /cookies or the helper tool — see Instagram & Cookies.
AI extraction fails: Confirm GEMINI_API_KEY and optionally set GEMINI_MODEL. With PROCESS_METHOD=ai, the import fails openly instead of falling back to a heuristic parser.