This tutorial was written with AI assistance from the project's official documentation. Verification status is stated at the end of the article.
What Mealie does and what it needs
Mealie is a self-hosted recipe manager, meal planner, and shopping list app with a REST API backend and a Vue frontend. You paste a recipe URL and it scrapes the ingredients, steps, and metadata into your database. From there you can plan meals for the week, generate a shopping list grouped by supermarket section, and organize recipes into cookbooks. The API is open, so third-party clients and automations can talk to it.
Under the hood Mealie is a Python (FastAPI) backend plus a static frontend, served on port 9000 inside the container. The official compose file maps that to host port 9091. Storage is a single data directory at /app/data/ that holds the SQLite database (default), uploaded images, and backups. You can switch to Postgres by setting DB_ENGINE=postgres and pointing it at a Postgres server.
The upstream project does not publish a minimum RAM figure. Practical memory use scales with your recipe library and image count: a small family instance with a few hundred recipes idles comfortably in a few hundred megabytes, while bulk URL imports and image processing spike CPU and memory temporarily. Plan for headroom on the import path, not the idle path.
Prerequisites, ports, and volume constraints
- Docker Engine 24+ and the Compose plugin (
docker compose version). - A hostname pointing at your VPS if you want HTTPS. A bare IP works for testing over an SSH tunnel.
- Port
9091on the host, bound to127.0.0.1in this guide so only the reverse proxy reaches it. - One named volume,
mealie-data, mounted at/app/data/. This is the only stateful path. Back it up before every upgrade. - If you use Postgres, a second volume for the database cluster. The compose below includes Postgres and a
mealie-dbvolume.
Mealie writes uploaded recipe images and its SQLite file under /app/data/. Do not mount a host directory over that path unless you understand the UID/GID the container runs as; a named volume avoids permission surprises. If you later switch from SQLite to Postgres, the old SQLite file stays in the volume and is ignored.
Production Docker Compose setup
Create the project directory and the compose file:
mkdir -p /opt/mealie && cd /opt/mealie cat <<'EOF' > compose.yml services: mealie: image: ghcr.io/mealie-recipes/mealie:latest container_name: mealie restart: unless-stopped depends_on: postgres: condition: service_healthy ports: - "127.0.0.1:9091:9000" volumes: - mealie-data:/app/data/ environment: ALLOW_SIGNUP: "false" LOG_LEVEL: "${LOG_LEVEL:-info}" TZ: "${TZ:-UTC}" DB_ENGINE: postgres POSTGRES_USER: "${POSTGRES_USER:-mealie}" POSTGRES_PASSWORD: "${POSTGRES_PASSWORD}" POSTGRES_SERVER: postgres POSTGRES_PORT: "5432" POSTGRES_DB: "${POSTGRES_DB:-mealie}" SMTP_HOST: "${SMTP_HOST:-}" SMTP_PORT: "${SMTP_PORT:-587}" SMTP_FROM_NAME: "${SMTP_FROM_NAME:-Mealie}" SMTP_AUTH_STRATEGY: "${SMTP_AUTH_STRATEGY:-TLS}" SMTP_FROM_EMAIL: "${SMTP_FROM_EMAIL:-}" SMTP_USER: "${SMTP_USER:-}" SMTP_PASSWORD: "${SMTP_PASSWORD:-}" postgres: image: postgres:16-alpine container_name: mealie-postgres restart: unless-stopped environment: POSTGRES_USER: "${POSTGRES_USER:-mealie}" POSTGRES_PASSWORD: "${POSTGRES_PASSWORD}" POSTGRES_DB: "${POSTGRES_DB:-mealie}" TZ: "${TZ:-UTC}" volumes: - mealie-db:/var/lib/postgresql/data healthcheck: test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"] interval: 10s timeout: 5s retries: 5 volumes: mealie-data: mealie-db: EOF Generate secrets and write the .env file. Never commit this file:
cat <<EOF > .env TZ=America/New_York LOG_LEVEL=info POSTGRES_USER=mealie POSTGRES_PASSWORD=$(openssl rand -hex 32) POSTGRES_DB=mealie SMTP_HOST= SMTP_PORT=587 SMTP_FROM_NAME=Mealie SMTP_AUTH_STRATEGY=TLS SMTP_FROM_EMAIL= SMTP_USER= SMTP_PASSWORD= EOF chmod 600 .env Start the stack and confirm both containers are healthy:
docker compose up -d docker compose ps docker compose logs -f mealie The app listens on 127.0.0.1:9091. To test without a domain, open an SSH tunnel from your laptop:
ssh -L 9091:127.0.0.1:9091 user@your-vps Then browse to http://localhost:9091. Do not change the port binding to 0.0.0.0 in production; the reverse proxy in the next section handles TLS.
Reverse proxy, HTTPS, and first-run hardening
Mealie is a single-page app that talks to its own API on the same origin. It does not need WebSocket upgrade headers for normal use, but it does need correct forwarded headers so generated links and API responses use your public scheme and host. Set X-Forwarded-Proto and X-Forwarded-For in the proxy.
Caddy example (/etc/caddy/Caddyfile):
recipes.example.com { encode gzip reverse_proxy 127.0.0.1:9091 { header_up X-Forwarded-Proto {scheme} header_up X-Forwarded-Host {host} } request_body { max_size 50MB } } Nginx equivalent:
server { listen 443 ssl http2; server_name recipes.example.com; client_max_body_size 50MB; location / { proxy_pass http://127.0.0.1:9091; 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; } } The client_max_body_size / max_size bump matters: recipe imports and image uploads can exceed the default 1 MB limit and will fail with a 413 if you leave it alone.
First-run hardening:
-
ALLOW_SIGNUPis set tofalsein the compose file. The first account you create through the setup screen becomes the admin. Create it immediately after the stack is up, before you announce the URL. - After the admin exists, keep signups disabled. Add family members from the admin UI instead of reopening public registration.
- If you expose Mealie to the internet, put it behind the proxy and consider an additional auth layer (basic auth or an identity-aware proxy) for the admin account.
- Configure SMTP in
.envif you want password reset and invite emails to work. Without it, account recovery is manual.
Updating, backups, and common pitfalls
Update the images and recreate containers:
docker compose pull docker compose up -d docker compose logs --tail=100 mealie Back up both volumes. The SQLite file (if you ever switch back) and uploaded images live in mealie-data; Postgres lives in mealie-db:
docker run --rm -v mealie-data:/data -v $(pwd):/backup alpine \ tar czf /backup/mealie-data-$(date +%F).tar.gz -C /data . docker exec mealie-postgres pg_dump -U mealie mealie | gzip > mealie-db-$(date +%F).sql.gz Restore by stopping the stack, extracting the tarball into a fresh mealie-data volume, and piping the SQL dump back into Postgres before starting Mealie again.
Two pitfalls worth knowing:
- Switching database engines after first boot. Mealie initializes its schema on first start. If you boot with SQLite and later set
DB_ENGINE=postgres, the Postgres database starts empty. Export your recipes from the old instance and re-import, or migrate the data before flipping the flag. - Recipe imports failing behind a proxy. The importer fetches the source URL server-side. If your VPS has restricted outbound traffic or the target site blocks datacenter IPs, imports fail with a scrape error even though the UI looks fine. Check
docker compose logs mealiefor the outbound request and test withcurlfrom inside the container.
Measured in our sandbox run: total memory 284.6 MB (sum of per-container peaks over a 30s idle window after startup) across 2 containers; largest container 248.1 MB; published port(s) 9091; HTTP probe returned 200. The run took 126.6s including the image download. Required secret(s) POSTGRES_PASSWORD were generated for the test run, as the tutorial instructs. Container breakdown: mealie 248.1 MB, postgres 36.5 MB.
Verification: we ran this docker-compose stack in a disposable Docker environment and recorded the measurements above. They describe that run, not a guarantee for your host.
Originally published with full interactive benchmark metrics and server sizing notes at https://vpsfolio.pages.dev/mealie-docker-self-hosted-recipe-manager/.
