How to Self-Host KitchenOwl with Docker Compose

What Is KitchenOwl?

KitchenOwl is a self-hosted grocery list manager, recipe organizer, and meal planner with native mobile apps for Android and iOS. Unlike recipe-first tools, KitchenOwl treats the grocery list as a first-class feature — items are categorized with icons, quantities sync in real time across household members, and the app learns your shopping patterns to suggest items automatically. It also includes household expense tracking with cost splitting. KitchenOwl replaces apps like AnyList, OurGroceries, and Bring! while giving you full control over your data.

Prerequisites

• A Linux server (Ubuntu 22.04+ recommended)
• Docker and Docker Compose installed (guide)
• 256 MB of free RAM
• 500 MB of free disk space
• A domain name (optional, for remote access and mobile app connectivity)

Docker Compose Configuration

KitchenOwl offers a single all-in-one container that bundles the frontend and backend. This is the easiest setup.

Create a docker-compose.yml file:

services:
  kitchenowl:
    image: tombursch/kitchenowl:v0.7.6
    container_name: kitchenowl
    restart: unless-stopped
    ports:
      - "8080:8080"
    environment:
      - JWT_SECRET_KEY=${JWT_SECRET_KEY}
      - OPEN_REGISTRATION=true
      - FRONT_URL=${FRONT_URL:-}
    volumes:
      - kitchenowl_data:/data

volumes:
  kitchenowl_data:

Create a .env file:

# Generate a random secret key — required for authentication
# Run: openssl rand -hex 32
JWT_SECRET_KEY=CHANGE_ME_TO_A_RANDOM_STRING

# Your domain URL (for CORS headers and mobile app connectivity)
# Leave empty for local-only access
FRONT_URL=https://kitchen.yourdomain.com

Start the stack:

docker compose up -d

Initial Setup

1. Open http://your-server-ip:8080 in your browser
2. Create your first account — the first user becomes the household owner
3. Set up your household name and invite family members
4. Disable open registration after all users are created by setting OPEN_REGISTRATION=false and restarting

Mobile Apps

KitchenOwl has native apps — not just a responsive website:

Platform	Source
Android	Google Play or F-Droid
iOS	App Store

Point the app at your server URL (e.g., https://kitchen.yourdomain.com) and log in. The app works offline and syncs when connectivity returns.

Configuration

PostgreSQL for Multi-User Households

For households with 3+ active users, PostgreSQL handles concurrent access better than SQLite:

services:
  kitchenowl:
    image: tombursch/kitchenowl:v0.7.6
    container_name: kitchenowl
    restart: unless-stopped
    ports:
      - "8080:8080"
    environment:
      - JWT_SECRET_KEY=${JWT_SECRET_KEY}
      - DB_DRIVER=postgresql
      - DB_HOST=kitchenowl-db
      - DB_NAME=kitchenowl
      - DB_USER=kitchenowl
      - DB_PASSWORD=${DB_PASSWORD}
    volumes:
      - kitchenowl_data:/data
    depends_on:
      kitchenowl-db:
        condition: service_healthy

  kitchenowl-db:
    image: postgres:16-alpine
    container_name: kitchenowl-db
    restart: unless-stopped
    environment:
      POSTGRES_DB: kitchenowl
      POSTGRES_USER: kitchenowl
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    volumes:
      - kitchenowl_db:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U kitchenowl"]
      interval: 30s
      timeout: 10s
      retries: 5

volumes:
  kitchenowl_data:
  kitchenowl_db:

Key Environment Variables

Variable	Default	Description
JWT_SECRET_KEY	super-secret	Required — change this. Signs authentication tokens
DB_DRIVER	sqlite	Database backend: sqlite or postgresql
OPEN_REGISTRATION	false	Allow public account creation
FRONT_URL	—	Your server URL (enables CORS for mobile apps)
COLLECT_METRICS	false	Enable Prometheus metrics at /metrics/
STORAGE_PATH	/data	Container path for persistent data
EMAIL_MANDATORY	false	Require email during signup

OIDC Authentication

KitchenOwl supports OpenID Connect for single sign-on with providers like Authentik, Keycloak, or Authelia:

OIDC_CLIENT_ID=kitchenowl
OIDC_CLIENT_SECRET=your-client-secret
OIDC_ISSUER=https://auth.yourdomain.com/realms/your-realm

Google and Apple OAuth are also supported with their own GOOGLE_CLIENT_ID/APPLE_CLIENT_ID environment variables.

Reverse Proxy

For remote access and mobile app connectivity, serve KitchenOwl behind a reverse proxy with HTTPS. Set FRONT_URL to your domain.

Nginx Proxy Manager config:

• Scheme: http
• Forward Hostname: kitchenowl
• Forward Port: 8080
• Enable WebSocket support (required for real-time list sync)
• Enable SSL with Let’s Encrypt

See Reverse Proxy Setup for full configuration.

Backup

Back up the kitchenowl_data volume — it contains the SQLite database (at /data/database.db) and uploaded recipe images (at /data/upload/).

If using PostgreSQL, also back up the kitchenowl_db volume:

docker exec kitchenowl-db pg_dump -U kitchenowl kitchenowl > kitchenowl_backup.sql

See Backup Strategy for automated backup workflows.

Troubleshooting

Mobile app cannot connect to server

Symptom: The mobile app shows “connection failed” or times out. Fix: Ensure FRONT_URL is set to your full server URL (with https://). Your reverse proxy must support WebSocket connections — enable the WebSocket toggle in Nginx Proxy Manager. Verify your domain resolves correctly and the SSL certificate is valid.

Grocery list items not syncing between users

Symptom: One user adds an item, but it does not appear for others. Fix: Real-time sync requires WebSocket support. Check that your reverse proxy forwards WebSocket connections. If using SQLite with many concurrent users, consider switching to PostgreSQL.

Recipe import fails from certain sites

Symptom: Importing a recipe from a URL returns empty or incomplete data. Fix: KitchenOwl scrapes recipe structured data from websites. Sites without schema.org Recipe markup may not import correctly. Try pasting the recipe URL from a different source, or add the recipe manually.

Cannot create first account

Symptom: Registration page shows “registration disabled.” Fix: Set OPEN_REGISTRATION=true in your environment and restart. After creating your account, set it back to false.

Resource Requirements

• RAM: ~100 MB idle, ~200 MB under load
• CPU: Low — grocery and recipe operations are lightweight
• Disk: ~300 MB for the application, plus storage for recipe images

Verdict

KitchenOwl fills a different niche than most recipe managers. If your primary problem is managing grocery lists across a household — who needs to buy what, tracking expenses, and keeping lists synced across phones — KitchenOwl does this better than anything else in the self-hosted space. The native mobile apps with offline support are a genuine advantage over web-only alternatives. The recipe and meal planning features are solid but less deep than Tandoor, which offers more powerful search and recipe organization. For users who mainly want recipe management, Mealie or Tandoor are stronger choices. For grocery-list-first households, KitchenOwl is the clear winner.

Related

• Mealie vs KitchenOwl: Which Should You Self-Host?
• Tandoor vs KitchenOwl: Which Should You Self-Host?
• How to Self-Host Mealie — recipe manager with grocery lists
• How to Self-Host Tandoor Recipes — advanced recipe management
• Mealie vs Tandoor — recipe manager comparison
• Best Self-Hosted Recipe Managers — full category roundup
• Docker Compose Basics — prerequisite guide
• Reverse Proxy Setup — remote access configuration
• Backup Strategy — protect your data