initial commit

2026-07-12 10:17:17 -04:00
commit dab5a4ebc6
1424 changed files with 330463 additions and 0 deletions
@@ -0,0 +1,99 @@
+---
+name: mealie-setup
+description: Deploy and configure Mealie (self-hosted meal planner/recipe manager) — Docker deployment, nginx reverse proxy, batch recipe import, mobile app setup, and common pitfalls.
+version: 1.0.0
+author: Hermes Agent
+license: MIT
+platforms: [linux]
+metadata:
+  hermes:
+    tags: [mealie, meal-planner, recipes, docker, self-hosting, nginx]
+---
+
+# Mealie Setup
+
+Mealie is a self-hosted recipe manager and meal planner. Web-based with PWA support for mobile, plus third-party Android/iOS apps (Ghee, Mealient, MealieSwift).
+
+## Quick Deploy
+
+```bash
+docker run -d \
+  --name mealie \
+  --restart unless-stopped \
+  -p 127.0.0.1:9925:9000 \
+  -v /path/to/data:/app/data \
+  ghcr.io/mealie-recipes/mealie:latest
+```
+
+**⚠️ PORT PITFALL:** Mealie listens on **port 9000** internally, not 9925. The `-p` mapping must be `host:9000`, not `host:9925`. If you map `9925:9925`, the container starts but the proxy returns empty responses.
+
+## BASE_URL (critical for invite links)
+
+Without `BASE_URL`, Mealie generates invite links, password reset URLs, and notification links using `http://localhost:8080` — they'll always fail. Set it to the external URL including the port:
+
+```bash
+docker run -d \
+  --name mealie \
+  ...
+  -e BASE_URL=https://your.domain:3449 \
+  ghcr.io/mealie-recipes/mealie:latest
+```
+
+If invite links show "refused to connect", you forgot `BASE_URL`. Re-create the container with it set — data survives in the volume.
+
+## Nginx Reverse Proxy
+
+Mealie needs to be at the root path — subpath proxying (`/mealie/`) is not supported (JS framework limitation).
+
+```nginx
+server {
+    listen PORT ssl;
+    server_name your.domain;
+
+    ssl_certificate /etc/letsencrypt/live/your.domain/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/your.domain/privkey.pem;
+
+    client_max_body_size 50M;
+
+    location / {
+        proxy_pass http://127.0.0.1:9925;
+        proxy_http_version 1.1;
+        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;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "upgrade";
+        proxy_read_timeout 86400;
+    }
+}
+```
+
+## First Visit & Setup
+
+- First visitor creates the admin account (no default credentials).
+- Seed **Foods** and **Units** databases: User menu → Manage Data → ensure orange button shows "Foods" → click Seed → do the same for Units. This enables smart ingredient parsing and shopping list generation.
+
+## Mobile Access
+
+- **PWA** (recommended, free): Open Mealie in Chrome Android → ⋮ → "Add to Home Screen". Full-screen with offline caching. All features (meal planner, shopping lists, cook mode) are free — unlike third-party apps.
+- **Ghee** (Play Store): **⚠️ Meal planner is a paid feature.** Recipe browsing and shopping lists work for free, but the meal calendar requires an in-app purchase. If "server unreachable" with SSL URL, try `http://192.168.50.X:9925` first — hairpin NAT or Android cleartext policies often block HTTPS on non-standard ports from apps.
+- **Mealient** (open source): GitHub release APK. Free, no paywalls.
+
+## Batch Importing Recipes
+
+Recipes are imported by URL via the scraper API. See `references/batch-import.md` for a curl/Python script.
+
+**Scraper compatibility:** see `references/scraper-sites.md` for which recipe sites work reliably and workarounds for blocked sites.
+
+**Recipe management (list, filter, delete):** see `references/recipe-management.md` for bulk CRUD via API — useful when you need to remove recipes by keyword (e.g., all pork/bacon recipes) or inspect what's in the library.
+
+## Managing Recipes
+
+Search, filter, and delete recipes in bulk via the API — useful for dietary cleanup, duplicate removal, and post-import curation. See `references/recipe-management.md` for the full API workflow (list, keyword-search, inspect ingredients, delete).
+
+## Data Location
+
+- Container data: `/app/data` (bind-mount to persistent storage)
+- Database: SQLite inside the data directory
+- Backups: copy the data directory