Mealie Deployment and Usage Guide

1. Prerequisites

Before installing Mealie, ensure you have the following:

Required Software:

Docker (recommended) - For containerized deployment
Docker Compose (optional) - For multi-container setup
Python 3.8+ (if running without Docker)
PostgreSQL 12+ or SQLite (for development)

Optional Tools:

Git - For cloning the repository
VSCode with Dev Containers - For development contributions
Node.js 16+ - For frontend development

Accounts (Optional):

Docker Hub account for pulling images
GitHub Container Registry access for alternative image source

2. Installation

Docker Installation (Recommended)

Pull the Docker image:

docker pull hkotel/mealie:latest

Or from GitHub Container Registry:

docker pull ghcr.io/mealie-recipes/mealie:latest

Create a directory for persistent data:
```
mkdir -p /path/to/mealie/data
```

Source Installation (Development)

Clone the repository:

git clone https://github.com/mealie-recipes/mealie.git
cd mealie

Set up Python environment:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -e .

Install frontend dependencies:
```
cd frontend
npm install
```

3. Configuration

Environment Variables

Create a .env file or set these environment variables:

Required:

# Database Configuration
DATABASE_URL=postgresql://user:password@localhost:5432/mealie
# or for SQLite (development only):
DATABASE_URL=sqlite:///mealie.db

# Application Settings
APP_TITLE=Mealie
SECRET=your-secret-key-here  # Generate with: openssl rand -hex 32

Optional:

# API and Security
API_PORT=9000
BASE_URL=http://localhost:9000
CORS_ORIGINS=["http://localhost:8080"]

# Features
ENABLE_OPENAI=false
OPENAI_API_KEY=your-openai-api-key
ENABLE_WEBHOOKS=false

# Email (for password resets)
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your-email@gmail.com
SMTP_PASSWORD=your-app-password
SMTP_FROM=mealie@yourdomain.com

Database Migration

Mealie uses Alembic for database migrations. The initial schema is defined in mealie/alembic/versions/2022-02-21-19.56.24_6b0f5f32d602_initial_tables.py. To initialize or migrate the database:

# With Docker:
docker run --rm hkotel/mealie:latest mealie db:migrate

# From source:
mealie db:migrate

4. Build & Run

Docker Compose (Production)

Create a docker-compose.yml file:

version: "3.8"

services:
  mealie:
    image: hkotel/mealie:latest
    container_name: mealie
    restart: unless-stopped
    ports:
      - "9000:9000"
    environment:
      DATABASE_URL: postgresql://mealie:password@db:5432/mealie
      SECRET: ${SECRET:-change-me}
    volumes:
      - ./data:/app/data
    depends_on:
      - db

  db:
    image: postgres:15-alpine
    container_name: mealie-db
    restart: unless-stopped
    environment:
      POSTGRES_USER: mealie
      POSTGRES_PASSWORD: password
      POSTGRES_DB: mealie
    volumes:
      - ./postgres-data:/var/lib/postgresql/data

Start the services:

docker-compose up -d

Development Server

Start the backend:

cd mealie
uvicorn mealie.app:app --reload --port 9000

Start the frontend:
```
cd frontend
npm run serve
```
Access the application:
- Backend API: http://localhost:9000
- Frontend: http://localhost:8080
- API Documentation: http://localhost:9000/docs

Build from Source

Build the Docker image:
```
docker build -t mealie:local .
```

Run custom build:

docker run -p 9000:9000 -v ./data:/app/data mealie:local

5. Deployment

Platform Recommendations

Self-Hosted Options:

Docker on Linux Server - Most common deployment
Kubernetes - For scalable deployments
Proxmox/LXC - Lightweight container deployment
Unraid - Via Community Applications

Cloud Platforms:

DigitalOcean - Docker droplet with one-click deployment
AWS ECS/EKS - For AWS users
Google Cloud Run - Serverless container deployment
Azure Container Instances - Simple Azure deployment

NAS Solutions:

Synology DSM - Via Docker package
QNAP - Container Station
TrueNAS Scale - Native Kubernetes support

Production Deployment Checklist

Use a reverse proxy (nginx, Traefik, Caddy) for SSL termination
Set up proper backups for database and recipe data
Configure monitoring (health checks, logs)
Use environment variables for secrets (never hardcode)
Enable automatic updates or establish update procedures

Example Nginx Configuration

server {
    listen 80;
    server_name mealie.yourdomain.com;
    return 301 https://$server_name$request_uri;
}

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

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    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;
    }
}

6. Troubleshooting

Common Issues

1. Database Connection Errors

# Check if database is accessible
psql "postgresql://user:password@localhost:5432/mealie"

# Reset database (development only):
rm mealie.db
mealie db:migrate

2. Migration Issues If you encounter migration errors from pre-Alembic versions, the migration script includes a check for existing tables (table_exists("users")). Ensure you have backups before proceeding.

3. Recipe Import Failures

Check network connectivity from container
Verify the recipe URL is accessible
Check logs for specific error messages:
```
docker logs mealie
```

4. Permission Issues with Volumes

# Fix Docker volume permissions
sudo chown -R 1000:1000 /path/to/mealie/data

5. Shopping List Merge Issues The shopping list service uses fuzzy matching (DEFAULT_FOOD_FUZZY_MATCH_THRESHOLD = 80). If items aren't merging correctly, check food names for inconsistencies.

6. API Rate Limiting If using OpenAI features, ensure your API key has sufficient quota and monitor usage in the OpenAI dashboard.

Logs and Debugging

View Docker logs:

docker logs mealie --tail 50 --follow

Enable debug mode:

# Set in environment
LOG_LEVEL=DEBUG

Check database state:

# For PostgreSQL
docker exec -it mealie-db psql -U mealie -d mealie -c "\dt"

# For SQLite
sqlite3 data/mealie.db ".tables"

Getting Help

Check the documentation: https://docs.mealie.io/
Join the Discord community: https://discord.gg/QuStdQGSGK
Review GitHub issues: https://github.com/mealie-recipes/mealie/issues
View the demo: https://demo.mealie.io/

Backup and Recovery

Manual backup:

# Database backup
docker exec mealie-db pg_dump -U mealie mealie > backup_$(date +%Y%m%d).sql

# Recipe data backup
tar -czf mealie_data_$(date +%Y%m%d).tar.gz /path/to/mealie/data

Restore from backup:

# Database restore
cat backup.sql | docker exec -i mealie-db psql -U mealie mealie

# Recipe data restore
tar -xzf mealie_data.tar.gz -C /path/to/restore

How to Deploy & Use mealie