Skip to content

Installation

Installation

Docker set up is dead simple. Single container, portable SQLite database.

Docker

  1. In your project directory, create the .env and docker-compose.yml files using the respective .template files in the repo root:
curl -o .env https://raw.githubusercontent.com/jt196/vanilla-cookbook/main/.env.template
curl -o docker-compose.yml https://raw.githubusercontent.com/jt196/vanilla-cookbook/main/docker-compose.yml.template
  1. In the .env file
  2. Change the ORIGIN to the URL it's going to be hosted on. If you get any login CORS messages, this not being set correctly will be the reason. The default ORIGIN=http://localhost:3000 should work with the default docker-compose.yml file unless you have anything else on that port.
  3. Create db and uploads folders for persistence in your docker folder, make sure the share paths are correct in the docker-compose file: mkdir -p ./db ./uploads
  4. Use :latest tags for bleedin' edge, :stable for stable release.
  5. Run docker-compose up -d
  6. On first run, you'll be prompted to enter Admin user details.
  7. Optional: set PUID and PGID (in your shell or .env) if you want container file ownership to match a specific host user. Defaults are 1000:1000.

Quick video run through of Docker setup:

Upgrade

  1. Grab the latest image: docker pull jt196/vanilla-cookbook
  2. Check the .env.template and docker-compose.yml.template files haven't been modified. Add any additional fields. The .env is the most likely to change.
  3. If upgrading from an older image that wrote files as root, run the migration guide below before restarting.
  4. From the project directory, run docker-compose up -d or docker compose up -d depending on how you have it installed on your system.

Docker Non-Root Migration Guide

Vanilla Cookbook now runs the app process as a non-root user in the container. Existing installs may need a one-time ownership fix on mounted volumes.

  1. Stop the container:
  2. docker compose down
  3. Back up your DB folder:
  4. cp -r ./db ./db-backup-$(date +%Y%m%d-%H%M%S)
  5. Start the updated container:
  6. docker compose up -d
  7. Validate:
  8. docker compose logs -f app and confirm no writable-permission errors
  9. create/edit a recipe
  10. upload an image
  11. Only if permission errors remain, run a manual ownership fix:
  12. PUID=${PUID:-1000} PGID=${PGID:-1000} sudo chown -R "${PUID}:${PGID}" ./db ./uploads
  13. then restart: docker compose up -d
  14. Optional: set PUID/PGID if you want a specific host-user mapping:
  15. export PUID=$(id -u)
  16. export PGID=$(id -g)

Local Docker Testing (No Docker Hub Push Required)

Use this before testing on a remote host.

  1. In docker-compose.yml, switch from image: to:
build:
  context: .
  1. Build locally:
  2. docker compose build --no-cache
  3. Run:
  4. docker compose up -d
  5. Optional user-mapping test:
  6. PUID=$(id -u) PGID=$(id -g) docker compose up -d
  7. Verify the runtime user and permissions:
  8. docker compose exec app id
  9. docker compose exec app sh -lc 'touch /app/uploads/images/perm-test && rm /app/uploads/images/perm-test'
  10. Validate upgrade path locally:
  11. temporarily create root-owned files in ./db or ./uploads
  12. start the container and check logs for permission warnings
  13. run the migration guide chown step and confirm the warnings are gone

Reverse Proxy Configuration

If you're running Vanilla Cookbook behind a reverse proxy (nginx, Nginx Proxy Manager, Traefik, etc.), you may need to adjust some settings.

For Nginx / Nginx Proxy Manager, add these settings:

# Required for saving recipes with images (default 1MB is too small)
client_max_body_size 10M;

# Required to prevent 502 errors (SvelteKit sends many preload headers)
proxy_buffer_size 128k;
proxy_buffers 4 256k;
proxy_busy_buffers_size 256k;

Common issues these settings fix:

  • Recipes fail to save (spinner never stops, no error): client_max_body_size too small
  • 502 Bad Gateway on recipe pages: Proxy buffer settings too small

In Nginx Proxy Manager: Edit your proxy host → Advanced → Custom Nginx Configuration, and add the lines above.

In standard Nginx: Add these to your location block or server block for the Vanilla Cookbook site.

Local Dev

Prerequisites: You'll need build tools installed for native module compilation (better-sqlite3)

  • macOS: Xcode Command Line Tools (xcode-select --install)
  • Linux: build-essential package (Ubuntu/Debian: sudo apt-get install build-essential)
  • Windows: Visual Studio Build Tools or windows-build-tools npm package

Setup

  1. Clone the repo and the recipe-ingredient-parser submodule: git clone --recursive https://github.com/jt196/vanilla-cookbook.git
  2. At the root of the project, create the .env file: cp .env.template .env
  3. In the .env file
  4. Set ORIGIN to http://localhost:5173 (dev).
  5. Run it
  6. pnpm i (node packages install)
  7. pnpm dev:setup (prisma client gen, migration)
  8. pnpm dev
  9. You'll be prompted for admin user details on accessing root

Mobile

Most folks know how to do this but I'll chuck some instructions up anyway. It's pretty close to to an Android app experience. Install from Chrome (I've found Firefox doesn't offer the install option) with > settings > add to home screen > install:

PWA Install 1

PWA Install 2

PWA Install 3