Deploying KitchenOwl

Introduction

KitchenOwl is a modern, self-hosted solution for managing grocery lists, recipes, meal planning, and household expenses. Built with a Flask backend and Flutter frontend, it offers a beautiful, responsive interface that works seamlessly across web browsers, iOS, and Android devices.

The application helps households coordinate shopping, plan meals for the week, store favorite recipes, and even track kitchen-related expenses. With multi-user support and real-time synchronization, everyone in your household stays on the same page.

Key highlights of KitchenOwl:

• Smart Grocery Lists: Add items quickly with autocomplete and categories
• Recipe Management: Store, organize, and search your favorite recipes
• Meal Planning: Plan your meals for the week with calendar integration
• Expense Tracking: Track kitchen and grocery expenses
• Multi-User Support: Share lists with household members
• Real-Time Sync: Changes sync instantly across all devices
• Native Mobile Apps: iOS and Android apps for on-the-go access
• Recipe Import: Import recipes from popular cooking websites
• Shopping Mode: Optimized view for checking off items while shopping
• Offline Support: Access your lists even without internet

This guide walks through deploying KitchenOwl on Klutch.sh using Docker, configuring persistent storage, and setting up for household use.

Why Deploy KitchenOwl on Klutch.sh

Deploying KitchenOwl on Klutch.sh provides several advantages:

Simplified Deployment: Klutch.sh automatically builds KitchenOwl from your Dockerfile without complex configuration.

Persistent Storage: Attach volumes for database and recipe images that survive container restarts.

HTTPS by Default: Secure access for all family members with automatic SSL certificates.

Remote Access: Access your grocery lists and recipes from anywhere, not just your home network.

Always Available: Your shopping lists are ready whenever inspiration strikes or you’re at the store.

Prerequisites

Before deploying KitchenOwl on Klutch.sh, ensure you have:

• A Klutch.sh account
• A GitHub account with a repository for your configuration
• Basic familiarity with Docker

Preparing Your Repository

To deploy KitchenOwl on Klutch.sh, create a GitHub repository containing your Dockerfile.

Repository Structure

kitchenowl-deploy/
├── Dockerfile
└── .dockerignore

Creating the Dockerfile

KitchenOwl provides separate frontend and backend images. For a simplified deployment, use the combined approach:

FROM tombursch/kitchenowl:latest

# Environment variables
ENV JWT_SECRET_KEY=${JWT_SECRET_KEY}
ENV FRONT_URL=${FRONT_URL}

# Volume: /data for SQLite database and uploads

EXPOSE 8080

Environment Variables Reference

Variable	Required	Description
JWT_SECRET_KEY	Yes	Secret key for JWT token signing
FRONT_URL	No	Frontend URL for email links
SMTP_HOST	No	SMTP server for email notifications
SMTP_PORT	No	SMTP port (default: 587)
SMTP_USER	No	SMTP username
SMTP_PASSWORD	No	SMTP password
SMTP_FROM	No	From address for emails

Creating the .dockerignore File

.git
.github
*.md
LICENSE
.gitignore
*.log
.DS_Store
.env

Deploying KitchenOwl on Klutch.sh

Generate JWT Secret

openssl rand -base64 32

Save this for environment variables.

Push Your Repository to GitHub

git init
git add Dockerfile .dockerignore
git commit -m "Initial KitchenOwl deployment configuration"
git remote add origin https://github.com/yourusername/kitchenowl-deploy.git
git push -u origin main

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project. Give it a descriptive name like “kitchenowl” or “kitchen”.

Create a New App

Within your project, create a new app. Connect your GitHub account and select your KitchenOwl repository.

Configure HTTP Traffic

In the deployment settings:

• Select HTTP as the traffic type
• Set the internal port to 8080

Set Environment Variables

Variable	Value
JWT_SECRET_KEY	Your generated secret
FRONT_URL	https://your-app-name.klutch.sh

Attach Persistent Volumes

Mount Path	Recommended Size	Purpose
/data	2 GB	SQLite database and uploaded images

Deploy Your Application

Click Deploy to start the build process.

Access KitchenOwl

Once deployment completes, access KitchenOwl at https://your-app-name.klutch.sh.

Initial Setup

Creating Your Account

On first access:

1. Click Register to create your account
2. Set up your username, email, and password
3. Log in to access the dashboard

Creating a Household

Set up your shared space:

1. Navigate to Settings > Household
2. Create a new household with a name
3. Invite family members by username or email

Setting Up Categories

Organize your grocery items:

1. Go to Settings > Categories
2. Add categories like “Produce,” “Dairy,” “Meat”
3. Assign colors for visual organization
4. Items will auto-categorize based on history

Using KitchenOwl

Adding Grocery Items

Quick ways to add items:

1. Type in the quick-add field
2. Use autocomplete suggestions
3. Tap recently used items
4. Add from recipes

Managing Recipes

Build your recipe collection:

1. Navigate to Recipes
2. Click Add Recipe
3. Enter ingredients and instructions
4. Optionally import from a URL
5. Add to meal plan or shopping list

Meal Planning

Plan your week:

1. Go to Planner
2. Drag recipes to calendar days
3. View the week’s meal plan
4. Add all ingredients to shopping list

Shopping Mode

At the store:

1. Open your shopping list
2. Enable Shopping Mode
3. Check off items as you shop
4. Items sort by category for efficient shopping

Mobile Apps

Installing Apps

Download the official apps:

• iOS: Available on the App Store
• Android: Available on Google Play

Connecting to Your Server

1. Open the app
2. Enter your server URL: https://your-app-name.klutch.sh
3. Log in with your account
4. Your lists sync automatically

Multi-User Setup

Inviting Household Members

1. Go to Settings > Household
2. Click Invite Member
3. Share the invite link or code
4. New members register and join

Permission Levels

• Owner: Full control over household settings
• Member: Can manage lists, recipes, and plans
• Viewer: Read-only access to lists

Production Best Practices

Data Protection

• Regular Backups: Back up the /data volume
• Strong JWT Secret: Use a cryptographically secure secret
• Secure Passwords: Encourage strong user passwords

Email Configuration

For password resets and notifications:

SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your-email@gmail.com
SMTP_PASSWORD=your-app-password
SMTP_FROM=noreply@your-domain.com

Troubleshooting Common Issues

Login Issues

Solutions:

• Verify JWT_SECRET_KEY is properly set
• Check that cookies are enabled in your browser
• Clear browser cache and try again

Sync Not Working

Solutions:

• Check network connectivity
• Verify the server is accessible
• Force a manual refresh in the app

Recipe Import Failing

Solutions:

• Not all websites are supported
• Try a different URL or add manually
• Check if the website blocks scraping

Additional Resources

• KitchenOwl Website
• KitchenOwl Documentation
• KitchenOwl GitHub Repository
• Klutch.sh Persistent Volumes

Conclusion

Deploying KitchenOwl on Klutch.sh gives you a beautiful, self-hosted kitchen management system accessible from anywhere. The combination of KitchenOwl’s intuitive interface and Klutch.sh’s deployment simplicity means your household can coordinate grocery shopping, meal planning, and recipe management without the complexity of running your own server.

With native mobile apps and real-time sync, KitchenOwl on Klutch.sh ensures everyone in your household stays coordinated, whether they’re at home planning meals or at the grocery store checking off items.