Mealie with Docker: a self-hosted recipe manager and meal planner (Linux, Windows, Mac)

What you get in one minute#

Mealie is a free, self-hosted recipe manager: paste the address of a recipe page and it saves the ingredients and steps in your own database, then helps you plan meals and build shopping lists for the whole family.

Logo: the official Mealie project (github.com/mealie-recipes/mealie, frontend/public/icon.png at the v3.30.0 tag)

Your recipes stop living in bookmarks, ad-filled pages and screenshots. They sit on a server you control. The project is active and has not been archived or renamed: v3.30.0 came out on 31 October 2026. Everything runs in one container, with SQLite as the default database.

At a glance:

• What it does: imports recipes from a URL, keeps cookbooks, plans meals, and makes shopping lists sorted by supermarket section.
• Default login: [email protected] with password MyPassword. Change it in Step 3, before anything else.
• BASE_URL: set it to the address your family really uses. It feeds notifications and the OIDC login callback.
• AI is optional and off until you set a provider. You configure it inside the app, not with environment variables. A later section lists what each feature sends out.
• Backups: built into the app as zip files, plus a plain copy of one data folder. You must keep a copy off the server.
• Database: SQLite is fine for 1 to 20 users. Postgres is for many concurrent users, and never put SQLite on network storage.

How it fits together#

Your devices talk to one container; the data folder holds everything. Imports fetch pages from the web, and only the optional AI step talks to an AI provider.

Drawn for this guide from the official docs. The HTTPS front door and the AI provider (dashed) are optional.

Before you start#

You need Docker with Compose on the machine that will run Mealie, plus a browser.

Check Docker on each system (curl.exe ships with Windows 10 and 11):

docker --version
docker compose version

Checklist:

• [ ] Docker and Compose answer both commands above
• [ ] Port 9925 is free (or choose another host port in Step 2)
• [ ] You know your own user and group ID on Linux or Mac (id -u and id -g)
• [ ] You have a place for off-server backups: another disk, a NAS share for the zip files, or a cloud folder
• [ ] For the HTTPS section only: a domain with a DNS record for the server, and ports 80 and 443 free

Tested by DIY Lab Hub: not yet. Every command comes from the official docs, Dockerfile and release files read in November 2026. We did not run them.

Step 1: Create the data folder#

Mealie keeps its database, images and backups under /app/data in the container. We map that to ~/docker_volumes/mealie/data.

Linux#

mkdir -p ~/docker_volumes/mealie/{data,backups}
cd ~/docker_volumes/mealie

Windows (PowerShell)#

New-Item -ItemType Directory -Force "$HOME\docker_volumes\mealie\data","$HOME\docker_volumes\mealie\backups" | Out-Null
Set-Location "$HOME\docker_volumes\mealie"

Mac (Terminal)#

Same commands as Linux:

mkdir -p ~/docker_volumes/mealie/{data,backups}
cd ~/docker_volumes/mealie

Check it worked. The folder exists: ls ~/docker_volumes/mealie (Linux, Mac) or Get-ChildItem "$HOME\docker_volumes\mealie" (Windows) lists data and backups.

Tip: The official docs use a Docker named volume (mealie-data:/app/data/). We use a folder so one tar or zip copies everything. If a Windows or Mac bind mount ever gives database is locked, switch to the docs' named volume. The docs do not cover that case; it is our caution.

Step 2: Write the Compose file and start Mealie#

This is the official SQLite file with four changes: the image is pinned to v3.30.0, data lives in ./data, the restart policy is unless-stopped, and the timezone is yours to set. Set PUID and PGID to the numbers from id -u and id -g (the docs use 1000). The container starts as root, switches to that user, and fixes the ownership of /app itself.

Linux#

cd ~/docker_volumes/mealie
cat > docker-compose.yml << 'EOF'
services:
  mealie:
    image: ghcr.io/mealie-recipes/mealie:v3.30.0
    container_name: mealie
    restart: unless-stopped
    ports:
      - "9925:9000"
    deploy:
      resources:
        limits:
          memory: 1000M
    volumes:
      - ./data:/app/data
    environment:
      ALLOW_SIGNUP: "false"
      PUID: 1000
      PGID: 1000
      TZ: Etc/UTC
      BASE_URL: http://localhost:9925
EOF
docker compose up -d
docker compose ps

Change TZ to your timezone name (for example Europe/London). The memory limit is the docs' own advice: Python can reserve more memory than it needs, and a limit keeps idle use down. BASE_URL is a placeholder for local testing; Step 4 changes it.

Windows (PowerShell)#

Set-Location "$HOME\docker_volumes\mealie"
@'
services:
  mealie:
    image: ghcr.io/mealie-recipes/mealie:v3.30.0
    container_name: mealie
    restart: unless-stopped
    ports:
      - "9925:9000"
    deploy:
      resources:
        limits:
          memory: 1000M
    volumes:
      - ./data:/app/data
    environment:
      ALLOW_SIGNUP: "false"
      PUID: 1000
      PGID: 1000
      TZ: Etc/UTC
      BASE_URL: http://localhost:9925
'@ | Set-Content -Encoding ascii docker-compose.yml
docker compose up -d
docker compose ps

Mac (Terminal)#

Same commands as Linux. Use your own IDs from id -u and id -g (macOS usually gives 501 and 20).

Check it worked. docker compose ps shows mealie running; the image's own health check calls /api/app/about and the status turns healthy after a short wait. This prints 200:

curl -fsS -o /dev/null -w "%{http_code}\n" http://localhost:9925/api/app/about

On Windows run the same line with curl.exe. The docs show no sample output, so read docker compose logs --tail=50 mealie for errors.

Tip: Keep the tag v3.30.0. The docs say a latest tag exists, but the team advises a specific version so you update when you have read the release notes.

Step 3: Log in and replace the default account#

Open Mealie in a browser. From another computer use the server's address and port 9925.

Linux#

xdg-open http://localhost:9925

Windows (PowerShell)#

Start-Process http://localhost:9925

Mac (Terminal)#

open http://localhost:9925

The docs give the default credentials: username [email protected], password MyPassword.

1. Log in and go to /admin/site-settings. The docs say this page summarises your configuration and warns about anything wrong.
2. Open your user profile and use the Change Password button (the docs FAQ names it).
3. Open /admin/manage/users (the docs: administrators manage users and permissions there) to add accounts for your family.

The docs do not describe renaming the default email. If you want your own address as the admin, create your own user there and make it an administrator, but test that on a fresh install before you delete the default user. We have not tested it.

Check it worked. You are logged in, the site-settings page shows no errors, and the old password no longer works in a private browser window.

Tip: The default password is in the public docs, so anyone who finds your port can use it. Do this step before you open the site to anyone else.

Step 4: Set BASE_URL and add your first recipe#

BASE_URL (default http://localhost:8080) is "used for notifications and the OIDC callback url". Set it to the exact address people type in the browser, including https:// and any port. If you reach Mealie as http://<your-server-address>:9925, edit the Compose file, then apply it.

Linux#

cd ~/docker_volumes/mealie
sed -i 's#^\(\s*BASE_URL:\).*#\1 http://<your-server-address>:9925#' docker-compose.yml
docker compose up -d

Windows (PowerShell)#

Set-Location "$HOME\docker_volumes\mealie"
notepad docker-compose.yml
docker compose up -d

Edit the BASE_URL line in Notepad, save, then run the last line.

Mac (Terminal)#

cd ~/docker_volumes/mealie
nano docker-compose.yml
docker compose up -d

Edit the BASE_URL line, save, then start again.

Now create a recipe: use the Create menu and import from a URL (the README lists "importing from a URL" as a key feature), or type one in by hand with the editor.

Check it worked. The recipe appears in the list with its ingredients and steps. If a site refuses the import, see the Troubleshooting table.

Tip: For scaling and shopping lists to work, seed your foods and units once (docs FAQ): open your name in the upper left, choose Manage Data, then Foods and Units and click Seed once each. Seeding twice creates duplicates.

Tip: Make your first backup now: open /admin/backups (Settings, Admin Settings, Backups), create one and download it. The Updates and backups section has the folder copy and a restore test.

Put it behind HTTPS (with or without Traefik)#

Plain HTTP is fine on a trusted home network. Add HTTPS when the site is reachable from outside, or when you want the "Keep Screen Alive" button, which the docs say needs HTTPS. Both routes need a DNS name such as mealie.<your-domain> and drop the host port, so only the proxy faces the network.

With Traefik#

On a server that already runs Traefik v3 with the Docker provider, add labels and remove the host port. This assumes an external Docker network called proxy and an entrypoint called https (use your own names). Create the network once:

docker network create proxy

Replace docker-compose.yml with this file, then run docker compose up -d:

services:
  mealie:
    image: ghcr.io/mealie-recipes/mealie:v3.30.0
    container_name: mealie
    restart: unless-stopped
    deploy:
      resources:
        limits:
          memory: 1000M
    volumes:
      - ./data:/app/data
    environment:
      ALLOW_SIGNUP: "false"
      PUID: 1000
      PGID: 1000
      TZ: Etc/UTC
      BASE_URL: https://mealie.<your-domain>
    networks:
      - proxy
    labels:
      - "traefik.enable=true"
      - "traefik.docker.network=proxy"
      - "traefik.http.routers.mealie.rule=Host(`mealie.<your-domain>`)"
      - "traefik.http.routers.mealie.entrypoints=https"
      - "traefik.http.routers.mealie.tls=true"
      - "traefik.http.services.mealie.loadbalancer.server.port=9000"

networks:
  proxy:
    external: true

Check it worked. curl -I https://mealie.<your-domain>/ returns an HTTP status line over HTTPS and the login page opens with a valid certificate.

Without Traefik: Caddy#

Choose this if you have no Traefik. Caddy gets and renews certificates for a public domain, or signs its own for a home-only name. Our Caddy guide covers it in depth. We mount the conf folder, not a single Caddyfile, because Caddy's Docker docs warn that editors which replace a single file break reloads.

docker network create proxy
mkdir -p ~/docker_volumes/caddy/{conf,data,config}
cd ~/docker_volumes/caddy
cat > docker-compose.yml << 'EOF'
services:
  caddy:
    image: caddy:2.11.8
    container_name: caddy
    restart: unless-stopped
    ports:
      - "80:80/tcp"
      - "443:443/tcp"
      - "443:443/udp"
    volumes:
      - ./conf:/etc/caddy
      - ./data:/data
      - ./config:/config
    networks:
      - proxy

networks:
  proxy:
    external: true
EOF

The image tag 2.11.8 is the newest Caddy tag on Docker Hub as of 5 November 2026; Caddy v2.11.9 was released the same day on GitHub but had no image tag yet when we checked. Save this as ~/docker_volumes/caddy/conf/Caddyfile for a public domain:

mealie.example.com {
    reverse_proxy mealie:9000
}

For a home-only name use tls internal, Caddy's own local certificate:

mealie.home.arpa {
    tls internal
    reverse_proxy mealie:9000
}

In ~/docker_volumes/mealie/docker-compose.yml use the file from the Traefik route without the labels: block (keep the proxy network), and set BASE_URL to the https:// address. Start both stacks:

cd ~/docker_volumes/caddy && docker compose up -d
cd ~/docker_volumes/mealie && docker compose up -d

For tls internal, each device must trust Caddy's root certificate. Copy it from the Caddy folder, then install it; the commands are explained in our Caddy guide:

cd ~/docker_volumes/caddy
docker compose cp caddy:/data/caddy/pki/authorities/local/root.crt ./caddy-root.crt

Windows (PowerShell, as administrator): certutil -addstore -f "ROOT" caddy-root.crt. Mac (Terminal): sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain caddy-root.crt. Linux: copy it to /usr/local/share/ca-certificates/ and run sudo update-ca-certificates.

Check it worked. curl -I https://mealie.example.com/ returns an HTTP status line over HTTPS. For a home-only name the browser shows a padlock only after the root is trusted on that device.

Tip: The name in BASE_URL, the DNS record and the Caddyfile or Traefik rule must all be the same name. A mismatch breaks certificates or login redirects.

Optional: AI features and what they send#

Mealie works fully without AI. Nothing leaves your server for AI until you add a provider: the docs say a default provider is required to enable AI at all.

Where to set it up. Open your group settings and add a provider there. The configuration page of the docs lists no OPENAI_* variables, and a maintainer in issue #7957 states that environment variables are ignored: use the in-app settings. Version 3.30.0 removed the old OPENAI_CUSTOM_PROMPT_DIR variable; prompts are now customised in the app and old files are imported automatically.

Mealie works with any OpenAI-compatible API. The docs say OpenAI's free tier is not capable enough and that a $5 deposit moves your account to Tier 1, which is enough.

What each feature sends to your provider (from the AI page of the docs):

The docs do not list the exact requests, so read each row as "the content you gave that feature". A hosted provider sees your recipes and photos; a local one does not.

Run it locally with Ollama. The docs say to set the base_url to http://localhost:11434/v1 (your Ollama address plus /v1) and that you must still enter an API key, which Ollama ignores. Issue #8503 confirms the key field is required. Our reasoning, not the docs: from inside the Mealie container localhost is the container itself, so use the Docker host's address instead. See our Ollama guide.

Tip: Give the provider a key that has a spending limit and delete it if you stop using AI. The key is stored in your Mealie settings, so treat the database and every backup as holding a secret.

Security and testing#

To limit HOST_IP, find the proxy network's range and add it to environment: (our suggestion; the docs only describe the variable):

docker network inspect proxy --format '{{(index .IPAM.Config 0).Subnet}}'

Quick tests:

cd ~/docker_volumes/mealie
docker compose ps
docker compose logs --tail=100 mealie
curl -fsS -o /dev/null -w "%{http_code}\n" http://localhost:9925/api/app/about

With HTTPS and no host port, run the curl against https://mealie.<your-domain>/api/app/about instead. Windows and Mac use the same commands (curl.exe in PowerShell). Logs also go to /app/data/mealie.log; LOG_LEVEL sets the detail.

Common mistakes#

These come from the official docs' warnings, the issue tracker, and common AI assistant answers.

Tip: Read the first 30 lines of docker compose logs mealie after every change. Mealie prints its settings at startup, and most mistakes (wrong BASE_URL, bad variable) show there.

Tip: The docs checklist mentions DEFAULT_EMAIL, but the configuration table in the same release lists only DEFAULT_GROUP and DEFAULT_HOUSEHOLD. This guide leaves DEFAULT_EMAIL out; do not trust a tutorial that sets it.

Tip: Never run docker compose up -d with a new image tag before taking a backup. Issue #7383 shows users who updated, hit a "500 Network error" with a custom domain, and found that going back to the older version gave errors and a container that exited.

Troubleshooting#

Known bugs (open, November 2026)#

• Issue #8946: public access redirects to the login page even with the household set to public.
• Issue #8551: audio transcription with some Gemini models fails; a fix is proposed in #8843.
• Issue #8797: with reverse proxy authentication and public access both on, the login button does not trigger proxy auth.

Updates and backups#

Update. The docs say you must read the release notes and back up first. Then change the tag in docker-compose.yml:

Linux#

cd ~/docker_volumes/mealie
docker compose down
docker compose pull
docker compose up -d
docker compose logs --tail=100 mealie

Windows (PowerShell)#

Set-Location "$HOME\docker_volumes\mealie"
docker compose down
docker compose pull
docker compose up -d
docker compose logs --tail=100 mealie

Mac (Terminal)#

Same commands as Linux.

Back up on a schedule. The docs say backups must be stored somewhere safe outside the server, so copy each archive to another machine. Save this as ~/docker_volumes/mealie/backup.sh, and run chmod 700 on it. Our restic guide shows an encrypted route:

#!/bin/bash
cd ~/docker_volumes/mealie || exit 1
docker compose down
tar -czf "backups/mealie-$(date +%F).tar.gz" data
chmod 600 backups/mealie-*.tar.gz
docker compose up -d

On Linux or Mac add a nightly 03:00 entry with crontab -e: 0 3 * * * $HOME/docker_volumes/mealie/backup.sh. The site is offline for a few seconds each night.

On Windows, save this as backup.ps1 and schedule it:

Set-Location "$HOME\docker_volumes\mealie"
docker compose down
Compress-Archive -Path data -DestinationPath "backups\mealie-$(Get-Date -Format yyyy-MM-dd).zip" -Force
docker compose up -d

schtasks /Create /SC DAILY /ST 03:00 /TN "Mealie backup" /TR "powershell.exe -NoProfile -File $HOME\docker_volumes\mealie\backup.ps1"

Restore test. Unpack one archive into a new folder and start a spare copy on another port, never over the live data (our test pattern):

mkdir -p /tmp/mealie-restore && tar -xzf backups/mealie-<date>.tar.gz -C /tmp/mealie-restore
docker run --rm -d --name mealie-restore -p 9926:9000 -e PUID=1000 -e PGID=1000 \
  -v /tmp/mealie-restore/data:/app/data ghcr.io/mealie-recipes/mealie:v3.30.0

Open http://localhost:9926, log in with your own account and check a recipe. Then docker stop mealie-restore. On Windows use a folder under $HOME in place of /tmp. The in-app restore from /admin/backups is the other route; the docs say it is destructive.

If you use Postgres, the docs say an in-app restore needs the Mealie database user to be a superuser temporarily, and that upgrading Postgres major versions needs manual steps.

Performance and resources#

The docs publish no idle RAM, CPU or disk figures, so this guide gives none. Measure your own machine:

• Resources: docker stats mealie shows live CPU and memory. Keep the 1000 MB limit unless you see out-of-memory kills.
• Users: SQLite suits 1 to 20 users; for many concurrent users or fuzzy search ("brocolli" finds broccoli) the docs say to use Postgres. The docs' Postgres example uses postgres:17.
• Workers: UVICORN_WORKERS defaults to 1. The docs warn that changing it may cause memory leaks; leave it alone.
• Old photos: since v3.7.0 new images are smaller; the docs give a reprocess_images.py script (same folder as above, option --workers 2) to convert older recipes.

FAQ#

Is Mealie free to use? Yes, under AGPL-3.0. If you change it and offer it to others over a network, the licence asks you to share your changes.

Is the project still maintained? Yes. It is the active mealie-recipes/mealie repository, with v3.30.0 released on 31 October 2026. It is not archived and we found no rename.

Can I run it on a Raspberry Pi? On a 64-bit operating system, yes (arm64). The docs say 32-bit ARM is not supported, so a Pi needs a 64-bit OS.

Does it send my data to the project? The docs list no analytics or telemetry setting. Recipe imports fetch the pages you ask for, and AI features send content to the provider you configure; nothing is sent to an AI provider until you add one.

SQLite or Postgres? Start with SQLite on a local disk. Move to Postgres for many concurrent users, fuzzy search, or if your data must live on network storage. The docs say backups let you move between them.

Sources#

• Mealie release v3.30.0, README, LICENSE, Dockerfile and entry.sh - read November 2026
• Docs at v3.30.0: installation checklist, SQLite, PostgreSQL, backend configuration, AI providers, security, backups and restoring, updating and FAQ, rendered at docs.mealie.io - read November 2026
• Mealie image on GitHub Container Registry (tag v3.30.0 checked) - November 2026
• Caddy release v2.11.9 and Caddy Docker image (tag 2.11.8 checked) - November 2026
• GitHub issues #4663, #5296, #5944, #6045, #7219, #7383, #7435, #7565, #7957, #8503, #8551, #8797, #8915 and #8946 - read November 2026

Checked against the official docs on 2026-11-05.