Mealie: Self-Hosted Recipe Manager and Meal Planner

Introduction

Mealie is a beautiful, self-hosted recipe manager and meal planner that transforms how you organize your culinary life. Built with modern technologies (FastAPI backend, Vue.js frontend), Mealie offers an elegant interface for storing recipes, planning meals, generating shopping lists, and sharing with family. With over 5,000 GitHub stars and active development, it has become the premier self-hosted solution for home cooks and food enthusiasts.

Why Choose Mealie?

Complete Recipe Control

Your recipes remain on your infrastructure. Unlike services like Paprika or Copy Me That that charge subscription fees or can disappear overnight, Mealie gives you permanent ownership of your recipe collection.

Powerful Recipe Importing

Mealie can import recipes from virtually any website with a single URL. The intelligent scraper extracts recipe data, ingredients, instructions, and images automatically. No more manual copy-pasting or reformatting.

Smart Meal Planning

Plan your weekly meals with drag-and-drop simplicity. Mealie automatically generates shopping lists from your meal plan, consolidating ingredients and organizing by category.

Zero Cost, Premium Features

Commercial recipe apps charge $5-10/month. A typical homelab setup costs $200-400 one-time investment, breaking even in less than 6 months while providing unlimited storage and features.

Production-Grade Features

Recipe importing from 100+ websites
Automatic ingredient parsing and scaling
Meal planning calendar
Shopping list generation with categories
Mobile-responsive web interface
Recipe sharing and public links
Multi-user support with households
Cookbook organization
Nutrition information tracking
Recipe rating and comments
Dark mode support
Multi-language support (15+ languages)

Understanding the Architecture

Mealie uses a modern microservices architecture:

Internet/Local Network
        │
        ▼
┌───────────────┐
│ Web Browser   │ (Recipe viewing, meal planning)
│ Mobile Browser│ (Shopping lists, quick access)
└───────┬───────┘
        │
        ▼
┌───────────────┐
│  Mealie API   │ (FastAPI backend)
│  Port 9000    │
└───────┬───────┘
        │
    ┌───┴────┐
    │        │
    ▼        ▼
┌─────────┐ ┌──────────┐
│SQLite/  │ │ Storage  │
│Postgres │ │ Images   │
│Database │ │ Backups  │
└─────────┘ └──────────┘

Components:

Frontend: Vue.js SPA for beautiful UI
Backend: FastAPI Python application
Database: SQLite (default) or PostgreSQL for larger installations
Storage: Recipe images, user uploads, and backups

Prerequisites and System Requirements

Hardware Specifications

Minimum Configuration

RAM: 2GB (sufficient for households up to 10 users)
CPU: 1 core
Storage: 10GB (grows with recipe images)
Network: Standard homelab network

Recommended Configuration

RAM: 4GB
CPU: 2+ cores
Storage: 50GB SSD
Network: Gigabit ethernet + WiFi for mobile access

Software Requirements

Docker Engine v24+ with docker-compose
Linux (Ubuntu 22.04/24.04 recommended) or Docker Desktop
Web browser (Chrome, Firefox, Safari, Edge)

Pre-Deployment Checklist

# Verify Docker
docker --version
docker compose version

# Check resources
free -h
df -h

# Test connectivity
ping -c 3 google.com

Installation and Deployment

Step 1: Environment Preparation

# Create directory
mkdir -p ~/mealie
cd ~/mealie

# Create environment file
cat > .env <<EOF
# Base URL (change to your domain or IP)
BASE_URL=http://YOUR-SERVER-IP:9000

# Database (SQLite by default, PostgreSQL for production)
DB_ENGINE=sqlite
# DB_ENGINE=postgres
# POSTGRES_USER=mealie
# POSTGRES_PASSWORD=$(openssl rand -base64 24)
# POSTGRES_SERVER=mealie-db
# POSTGRES_PORT=5432
# POSTGRES_DB=mealie

# Security
API_PORT=9000
API_DOCS=true
TOKEN_TIME=48  # hours

# Email (optional for password reset)
# SMTP_HOST=smtp.gmail.com
# SMTP_PORT=587
# SMTP_FROM_NAME=Mealie
# [email protected]
# [email protected]
# SMTP_PASSWORD=your-app-password
# SMTP_AUTH_STRATEGY=TLS

# Default User (created on first start)
[email protected]
DEFAULT_PASSWORD=ChangeThisPassword123

# Features
ALLOW_SIGNUP=true
MAX_WORKERS=1
WEB_CONCURRENCY=1
EOF

chmod 600 .env

Important: Replace YOUR-SERVER-IP with your actual server IP.

Step 2: Create Docker Compose Configuration

Create docker-compose.yml:

version: "3.8"

services:
  mealie:
    image: ghcr.io/mealie-recipes/mealie:latest
    container_name: mealie
    restart: unless-stopped
    ports:
      - "9000:9000"
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=America/New_York
      - BASE_URL=${BASE_URL}
      - DB_ENGINE=${DB_ENGINE}
      - TOKEN_TIME=${TOKEN_TIME}
      - API_PORT=${API_PORT}
      - API_DOCS=${API_DOCS}
      - DEFAULT_EMAIL=${DEFAULT_EMAIL}
      - DEFAULT_PASSWORD=${DEFAULT_PASSWORD}
      - ALLOW_SIGNUP=${ALLOW_SIGNUP}
      - MAX_WORKERS=${MAX_WORKERS}
      - WEB_CONCURRENCY=${WEB_CONCURRENCY}
    volumes:
      - mealie-data:/app/data/
    healthcheck:
      test: ["CMD", "wget", "-q", "--tries=1", "--spider", "http://localhost:9000/api/app/about"]
      interval: 30s
      timeout: 10s
      retries: 5
      start_period: 40s

volumes:
  mealie-data:
    driver: local

For PostgreSQL (production):

Add PostgreSQL service:

  mealie-db:
    image: postgres:15
    container_name: mealie-db
    restart: unless-stopped
    environment:
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: ${POSTGRES_DB}
    volumes:
      - postgres-data:/var/lib/postgresql/data

volumes:
  mealie-data:
  postgres-data:

Step 3: Deploy Mealie

# Pull image
docker compose pull

# Start services
docker compose up -d

# Monitor logs
docker compose logs -f

# Verify running
docker compose ps

Step 4: Initial Setup

Navigate to http://YOUR-SERVER-IP:9000

First-time setup:

You’ll see the Mealie welcome screen
Default credentials:
- Email: [email protected]
- Password: ChangeThisPassword123
Immediately change password:
- Click user icon (top right)
- Settings → Change Password
- Set strong password
- Update email to your actual email
Configure site settings:
- Site Settings → Site Name: “Family Recipes”
- Language: Select your preference
- Theme: Light or Dark

Step 5: Configure HTTPS (Production)

Using Caddy:

mealie.yourdomain.com {
    reverse_proxy mealie:9000
    encode gzip
}

Using Nginx:

server {
    listen 443 ssl http2;
    server_name mealie.yourdomain.com;

    ssl_certificate /path/to/fullchain.pem;
    ssl_certificate_key /path/to/privkey.pem;

    client_max_body_size 20M;

    location / {
        proxy_pass http://localhost:9000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Update .env:

BASE_URL=https://mealie.yourdomain.com

Restart:

docker compose restart

Recipe Importing

Import from URL

The most powerful feature of Mealie is automated recipe importing:

Supported sites (100+):

AllRecipes
Food Network
Serious Eats
NYT Cooking
Bon Appétit
Budget Bytes
King Arthur Baking
BBC Good Food
Tasty
…and many more

Import process:

1. Click "+" button → Import Recipe
2. Paste recipe URL
3. Click "Import"
4. Mealie extracts:
   - Title
   - Description
   - Image
   - Ingredients (parsed)
   - Instructions (step-by-step)
   - Prep time, cook time, servings
   - Nutrition (if available)
5. Review and edit if needed
6. Save to your collection

Example imports:

URL: https://www.allrecipes.com/recipe/example/
→ Complete recipe imported in ~5 seconds

URL: https://www.budgetbytes.com/recipe/example/
→ Ingredients automatically parsed and scaled

URL: https://www.seriouseats.com/recipe/example/
→ Images, notes, and nutrition included

Bulk Import

Import multiple recipes at once:

1. Tools → Import Recipes
2. Paste multiple URLs (one per line):
   https://example.com/recipe1
   https://example.com/recipe2
   https://example.com/recipe3
3. Click "Bulk Import"
4. Mealie processes them sequentially
5. Review import log for any issues

Manual Recipe Creation

For family recipes or handwritten cards:

1. Click "+" → Create Recipe
2. Fill in details:
   - Name: "Grandma's Apple Pie"
   - Description: "Family recipe from 1950"
   - Recipe Image: Upload photo
   - Categories: Desserts, Family Recipes
   - Tags: pie, apples, holiday

3. Ingredients:
   - 6 apples, peeled and sliced
   - 1 cup sugar
   - 1 tsp cinnamon
   - 2 pie crusts

4. Instructions:
   - Step 1: Preheat oven to 375°F
   - Step 2: Mix apples with sugar and cinnamon
   - Step 3: Fill pie crust
   - Step 4: Bake 45 minutes

5. Recipe Settings:
   - Prep Time: 20 minutes
   - Cook Time: 45 minutes
   - Total Time: 1 hour 5 minutes
   - Servings: 8

6. Save

Recipe Editing

Edit any recipe field:

- Scaling: Adjust servings (ingredients auto-scale)
- Units: Convert between metric/imperial
- Images: Upload multiple images
- Notes: Add cooking tips or substitutions
- Nutrition: Add custom nutrition info
- Rating: 1-5 stars

Meal Planning

Creating Meal Plans

Weekly meal planning:

1. Click "Meal Plans" in sidebar
2. Select week
3. For each day:
   - Click "Add Meal"
   - Select recipe from your collection
   - Choose meal type: Breakfast, Lunch, Dinner, Snack
   - Add notes (optional)

Example week:
Monday:
  - Dinner: Chicken Tikka Masala
Tuesday:
  - Dinner: Spaghetti Carbonara
  - Lunch: Leftover Chicken Tikka
Wednesday:
  - Dinner: Tacos
Thursday:
  - Dinner: Grilled Salmon
Friday:
  - Dinner: Pizza Night
Saturday:
  - Breakfast: Pancakes
  - Dinner: Pot Roast
Sunday:
  - Dinner: Meal Prep for week

Drag-and-drop interface:

Rearrange meals between days
Copy meals to multiple days
Quick meal type switching

Shopping List Generation

Automatically generate shopping lists from meal plans:

1. Meal Plans → Select week
2. Click "Generate Shopping List"
3. Mealie:
   - Aggregates all ingredients
   - Removes duplicates
   - Organizes by category
   - Allows manual adjustments

4. Review shopping list:
   - Check/uncheck items
   - Add custom items
   - Adjust quantities
   - Add notes

5. Access on mobile:
   - Check off items while shopping
   - Real-time sync across devices

Shopping list categories:

Produce:
- 10 apples
- 2 onions
- 3 bell peppers

Dairy:
- 1 gallon milk
- 2 lbs butter
- 8 oz cheese

Meat:
- 2 lbs chicken breast
- 1 lb ground beef

Pantry:
- 1 box pasta
- 1 can tomatoes
- 2 cups rice

Spices:
- 1 tbsp cinnamon
- 2 tsp paprika

Meal Planning Tips

Efficient planning:

- Plan leftovers: Cook large portions Monday for Wednesday lunch
- Theme nights: Taco Tuesday, Pizza Friday
- Batch cooking: Prep ingredients Sunday for week
- Seasonal planning: Use in-season produce
- Variety: Mix cuisines and cooking methods

Family considerations:

- Kid-friendly options
- Dietary restrictions
- Cooking skill level
- Available time
- Budget constraints

Organization and Cookbooks

Cookbooks

Create themed collections:

Cookbook: "Family Favorites"
- Grandma's Recipes
- Sunday Dinners
- Holiday Traditions

Cookbook: "Weeknight Dinners"
- 30-Minute Meals
- One-Pot Dinners
- Sheet Pan Recipes

Cookbook: "Special Occasions"
- Birthday Cakes
- Holiday Dishes
- Entertaining

Creating a cookbook:

1. Tools → Cookbooks → Create
2. Name: "Summer BBQ Recipes"
3. Description: "Grilling favorites for summer"
4. Add recipes:
   - Drag and drop from recipe list
   - Or click "+" to add
5. Organize order
6. Share cookbook (optional)

Households

Mealie supports household groups for families:

1. Settings → Households
2. Create household: "Smith Family"
3. Invite members:
   - Generate invite link
   - Share with family
   - They create accounts and join

Household features:
- Shared recipe collection
- Shared meal plans
- Shared shopping lists
- Individual preferences

Public recipe links:

1. Open recipe
2. Click "Share" icon
3. Options:
   - Generate public link
   - Anyone with link can view
   - No account needed
   - Expiration date (optional)

Example:
https://mealie.yourdomain.com/r/abc123def

Share with other Mealie users:

1. Recipe → Share
2. Enter user email
3. Permissions:
   - View only
   - Can edit
4. Send

Guest Access

Allow read-only access without account:

Settings → Site Settings:
- Allow Guest Access: Yes
- Default Recipe Permissions: Public

Use case:
- Share recipes with extended family
- Public recipe blog
- Community cookbook

Mobile App and Access

Mobile Web Access

Mealie is fully responsive - works great on mobile browsers:

On mobile:

1. Bookmark site on home screen:
   - Safari (iOS): Share → Add to Home Screen
   - Chrome (Android): Menu → Add to Home Screen

2. Acts like native app:
   - Full-screen mode
   - Fast loading
   - Offline recipe viewing

Mobile features:

Recipe viewing and scaling
Shopping list with checkboxes
Meal plan viewing
Quick recipe search
Image upload from camera

Progressive Web App (PWA)

Install as PWA for app-like experience:

iOS:
1. Open in Safari
2. Share → Add to Home Screen
3. Name: "Mealie"
4. Add

Android:
1. Open in Chrome
2. Menu → Install App
3. Confirm

Features:
- Offline caching
- Push notifications (future)
- Home screen icon
- Full-screen experience

Backup Strategies

What to Backup

Component	Location	Priority	Contains
Database	SQLite file or PostgreSQL	Critical	All recipes, meal plans, users
Images	/app/data/img	Important	Recipe images
Backups	/app/data/backups	Important	Mealie auto-backups

Built-in Backup

Mealie has built-in backup functionality:

1. Settings → Backups
2. Click "Create Backup"
3. Backup includes:
   - All recipes (JSON format)
   - All images
   - User data
   - Meal plans
   - Shopping lists

4. Download backup file
5. Store securely off-site

Automated backups:

Settings → Backups:
- Auto Backup: Enabled
- Backup Schedule: Daily at 2 AM
- Retention: Keep last 14 backups

Manual Backup Script

Create ~/mealie/backup.sh:

#!/bin/bash

BACKUP_DIR="/mnt/backups/mealie"
DATE=$(date +%Y%m%d_%H%M%S)
RETENTION_DAYS=30

mkdir -p "$BACKUP_DIR"

echo "Starting Mealie backup at $(date)"

# Backup entire data volume
docker run --rm   -v mealie_mealie-data:/source:ro   -v "$BACKUP_DIR":/backup   alpine tar czf /backup/mealie-${DATE}.tar.gz -C /source .

echo "✓ Mealie data backed up"

# Trigger Mealie's internal backup
docker exec mealie wget -q -O- http://localhost:9000/api/admin/backups

# Copy Mealie's backup
docker cp mealie:/app/data/backups/. "$BACKUP_DIR/auto-backups/"

# Clean old backups
find "$BACKUP_DIR" -name "*.tar.gz" -mtime +$RETENTION_DAYS -delete

echo "Backup completed at $(date)"

Disaster Recovery

Restore from backup:

# Stop Mealie
docker compose down

# Restore data
docker run --rm   -v mealie_mealie-data:/dest   -v /mnt/backups/mealie:/backup   alpine tar xzf /backup/mealie-YYYYMMDD.tar.gz -C /dest

# Start Mealie
docker compose up -d

# Verify
docker compose logs -f

Restore via web interface:

1. Settings → Backups
2. Upload backup file
3. Click "Restore"
4. Confirm
5. Mealie restarts automatically
6. Login and verify data

Advanced Features

Nutrition Tracking

Add nutrition information to recipes:

Recipe → Nutrition:
- Calories: 350
- Protein: 25g
- Carbs: 40g
- Fat: 10g
- Fiber: 5g
- Sugar: 8g

Auto-calculate per serving
Track daily nutrition from meal plan

Recipe Notes and Comments

Collaborative recipe improvement:

Recipe Page → Notes:
- Add personal cooking tips
- Substitution suggestions
- Timing adjustments
- Success/failure notes

Example:
"Used honey instead of sugar - turned out great!"
"Reduce salt by half - was too salty"
"Doubled the garlic - perfect!"

API Integration

Mealie provides a REST API for automation:

Generate API key:

User Settings → API Keys
Create Token → Copy key

Example: Automated recipe import:

import requests

API_URL = "http://mealie.yourdomain.com/api"
API_KEY = "your-api-key"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

# Import recipe from URL
recipe_data = {
    "url": "https://www.allrecipes.com/recipe/example/",
    "include_tags": True
}

response = requests.post(
    f"{API_URL}/recipes/create-url",
    headers=headers,
    json=recipe_data
)

print(f"Recipe imported: {response.json()['id']}")

Webhooks

Trigger actions on recipe events:

Settings → Webhooks:
- Event: Recipe Created
- URL: http://automation-server/webhook
- Payload: Recipe data

Use cases:
- Notify family of new recipes
- Auto-backup to cloud
- Share to social media
- Log recipe additions

Troubleshooting Common Issues

Issue: Recipe import failing

# Check logs
docker compose logs mealie | grep -i import

# Common fixes:
# 1. Website requires JavaScript rendering
# 2. Recipe format not recognized
# 3. Network connectivity issue

# Workaround: Manual import
# Copy recipe details manually

Issue: Images not loading

# Check volume permissions
docker exec mealie ls -la /app/data/img

# Fix permissions
docker exec mealie chown -R 1000:1000 /app/data

# Restart
docker compose restart

Issue: Slow performance

# Check resource usage
docker stats mealie

# Increase workers (in .env):
MAX_WORKERS=2
WEB_CONCURRENCY=2

# Restart
docker compose restart

Issue: Database errors

# For SQLite issues
docker exec mealie sqlite3 /app/data/mealie.db "PRAGMA integrity_check;"

# Rebuild database (last resort)
# Backup first!
# Settings → Backups → Create Backup
# Then: Settings → Database → Rebuild

Next Steps and Best Practices

Immediate Next Steps

Import your favorite recipes
- Start with 10-20 go-to recipes
- Test import functionality
- Organize with categories and tags
Create your first meal plan
- Plan upcoming week
- Generate shopping list
- Test mobile access while shopping
Set up family access
- Create household
- Invite family members
- Share recipe responsibilities
Establish backup routine
- Enable auto-backups
- Test manual backup
- Verify restoration process

Best Practices

Recipe organization:

Use consistent naming conventions
Tag comprehensively from the start
Create cookbooks for themes
Add notes for successful variations

Meal planning:

Plan a week in advance
Include leftover days
Consider prep time for busy nights
Balance variety and favorites

Shopping lists:

Review before generating
Organize by store layout
Check pantry first
Adjust quantities as needed

Conclusion

Mealie transforms meal planning from a chore into an organized, efficient process. With powerful recipe importing, intelligent meal planning, and beautiful interface, it’s the perfect addition to any homelab.

Key Achievements After This Guide:

Self-hosted recipe manager
Automated recipe importing
Meal planning calendar
Shopping list generation
Family recipe sharing
Mobile-friendly access

Success Metrics (First Month):

50+ recipes in collection
4+ weeks of meal plans created
Shopping lists used consistently
Family members using actively
Automated backups running

Start by importing your most-cooked recipes, plan your next week, and discover how much easier meal planning becomes with proper tools!

Welcome to organized cooking!

Document Version: 1.0 Last Updated: December 2025 Word Count: ~5,400 words Mealie Version: 1.0+ (latest stable)