Backend Configuration

API Environment Variables

General

* Starting in v1.4.0 this was changed to default to false as part of a security review of the application.

Listening address

API_HOST defaults to an empty string, which is automatic wildcard binding. Mealie opens one dual-stack IPv6 socket so the same API_PORT accepts IPv4 and IPv6 connections. When the host cannot provide that socket, Mealie listens on IPv4 0.0.0.0 instead. The IPv4 listener is only a fallback for missing IPv6 dual-stack support. A port that is already in use, or a bind the process is not allowed to perform, stops startup with that error.

Set API_HOST to choose an exact address: 0.0.0.0 (IPv4 on every interface), 127.0.0.1 (IPv4 loopback only), :: (IPv6 wildcard), or ::1 (IPv6 loopback only). Explicit values stay on the address you set.

HOST_IP lists reverse proxies trusted to send forwarded headers. The listening address is API_HOST.

Docker delivers IPv6 to a container when the Docker network has IPv6 enabled and the published port is reachable over IPv6. A dual-stack listener on an IPv4-only Docker network is reachable over IPv4 alone.

Security

Reverse proxy headers

HOST_IP controls which connecting proxy IP addresses or CIDR ranges Uvicorn trusts for X-Forwarded-For and X-Forwarded-Proto. Set a comma-separated list matching your reverse proxy or Kubernetes ingress, for example HOST_IP=127.0.0.1,10.42.1.0/24. Depending on your container environment and network, the container's default gateway may not be the address of the proxy.

The default is * for compatibility, which trusts forwarding headers from every connecting source. Use that setting only when access to the application is limited to trusted proxies!

Set HOST_IP to an empty string to trust no forwarding proxies.

Application security

Database

Email

Webworker

Changing the webworker settings may cause unforeseen memory leak issues with Mealie. It's best to leave these at the defaults unless you begin to experience issues with multiple users. Exercise caution when changing these settings

TLS

Use this only when mealie is run without a webserver or reverse proxy.

LDAP

Reverse Proxy Auth

Mealie can trust a username forwarded by a reverse proxy that has already authenticated the user (e.g. Authelia, Authentik, oauth2-proxy, Tailscale Serve). When enabled, visiting the login page will automatically sign in as the user named in the configured header, with no extra Mealie login step. Password, LDAP, and OIDC login remain available and are not affected by this setting.

OpenID Connect (OIDC)

v1.4.0

For usage, see Usage - OpenID Connect

AI

v1.7.0

Mealie supports various integrations using AI. For more information, check out our AI Providers documentation.

Recipe import can also transcribe a video's audio with AI (e.g. to import a recipe from a cooking video). This uses yt-dlp to download the video, which you can configure with the env variables below:

Recipe Scraper

When you import a recipe from a URL, Mealie fetches the page (and its image) before parsing it. Many sites sit behind bot-protection (e.g. Cloudflare) that can block these requests. Out of the box Mealie mitigates this by impersonating real browsers' TLS fingerprints and rotating between several of them, which is enough for most sites and requires no configuration. If you still run into sites that block imports, the opt-in settings below add two further layers.

How Mealie fetches a page

For each import Mealie escalates only as far as it needs to, stopping at the first step that succeeds:

1. Direct fetch with rotating browser TLS impersonations — always on, no configuration.
2. Proxy — if SCRAPER_PROXY_URL is set (see modes below).
3. FlareSolverr — if SCRAPER_FLARESOLVERR_URL is set, and only when the page is still blocked.

Steps 2 and 3 are opt-in, so a default install uses only step 1. Genuine "not found" responses (e.g. 404) are treated as real errors and are never retried through the later steps.

Proxy

Most IP-based blocks trigger on the very first request, so always mode (the default when a proxy is set) is recommended — it routes every request through the proxy from the start. Use fallback mode if you're on a metered proxy and want to avoid paying for requests that would have succeeded directly; Mealie will then only route through the proxy after a direct attempt is blocked. The proxy applies to both the recipe page and its image download.

FlareSolverr

FlareSolverr runs a real headless browser to solve challenges that TLS impersonation alone can't. Mealie neither ships nor manages it — you host it yourself and point Mealie at it. Because it returns rendered HTML, it is only used for the recipe page; image downloads never use FlareSolverr and continue to rely on the direct/proxy path.

Run it as a sidecar container and set SCRAPER_FLARESOLVERR_URL to its address:

services:
  mealie:
    image: ghcr.io/mealie-recipes/mealie:latest
    environment:
      SCRAPER_FLARESOLVERR_URL: http://flaresolverr:8191
      # optional; default shown
      # SCRAPER_FLARESOLVERR_TIMEOUT: 60

  flaresolverr:
    image: ghcr.io/flaresolverr/flaresolverr:latest
    restart: unless-stopped
    # No ports need to be published — Mealie reaches it over the internal Docker network.

Because FlareSolverr drives a browser, requests through it are much slower (seconds) and far more resource-intensive than a direct fetch. That's why Mealie only falls back to it when a page is actually blocked, rather than using it for every import.

Theming

Setting the following environmental variables will change the theme of the frontend. Note that the themes are the same for all users. This is a break-change when migration from v0.x.x -> 1.x.x.

Theming Examples

The examples below provide copy-ready Docker Compose environment configurations for three different color palettes. Copy and paste the desired theme into your docker-compose.yml file's environment section.

environment:
  # Light mode colors
  THEME_LIGHT_PRIMARY: '#5E9BD1'
  THEME_LIGHT_ACCENT: '#A3C9E8'
  THEME_LIGHT_SECONDARY: '#4F89BA'
  THEME_LIGHT_SUCCESS: '#4CAF50'
  THEME_LIGHT_INFO: '#4A9ED8'
  THEME_LIGHT_WARNING: '#EAC46B'
  THEME_LIGHT_ERROR: '#E57373'
  # Dark mode colors
  THEME_DARK_PRIMARY: '#5A8FBF'
  THEME_DARK_ACCENT: '#90B8D9'
  THEME_DARK_SECONDARY: '#406D96'
  THEME_DARK_SUCCESS: '#81C784'
  THEME_DARK_INFO: '#78B2C0'
  THEME_DARK_WARNING: '#EBC86E'
  THEME_DARK_ERROR: '#E57373'

environment:
  # Light mode colors
  THEME_LIGHT_PRIMARY: '#75A86C'
  THEME_LIGHT_ACCENT: '#A8D0A6'
  THEME_LIGHT_SECONDARY: '#638E5E'
  THEME_LIGHT_SUCCESS: '#4CAF50'
  THEME_LIGHT_INFO: '#4A9ED8'
  THEME_LIGHT_WARNING: '#EAC46B'
  THEME_LIGHT_ERROR: '#E57373'
  # Dark mode colors
  THEME_DARK_PRIMARY: '#739B7A'
  THEME_DARK_ACCENT: '#9FBE9D'
  THEME_DARK_SECONDARY: '#56775E'
  THEME_DARK_SUCCESS: '#81C784'
  THEME_DARK_INFO: '#78B2C0'
  THEME_DARK_WARNING: '#EBC86E'
  THEME_DARK_ERROR: '#E57373'

environment:
  # Light mode colors
  THEME_LIGHT_PRIMARY: '#D97C96'
  THEME_LIGHT_ACCENT: '#E891A7'
  THEME_LIGHT_SECONDARY: '#C86C88'
  THEME_LIGHT_SUCCESS: '#4CAF50'
  THEME_LIGHT_INFO: '#2196F3'
  THEME_LIGHT_WARNING: '#FFC107'
  THEME_LIGHT_ERROR: '#E57373'
  # Dark mode colors
  THEME_DARK_PRIMARY: '#C2185B'
  THEME_DARK_ACCENT: '#FF80AB'
  THEME_DARK_SECONDARY: '#AD1457'
  THEME_DARK_SUCCESS: '#81C784'
  THEME_DARK_INFO: '#64B5F6'
  THEME_DARK_WARNING: '#FFD54F'
  THEME_DARK_ERROR: '#E57373'

Branding

Setting the following environment variables lets you replace Mealie's name and logo in the UI. Any variable left unset falls back to the default Mealie branding, so you can override just the pieces you care about.

This only covers the app name (top navigation bar, browser tab title, installed PWA name) and the logo (top navigation bar, login/setup pages, favicon). It does not change every other place "Mealie" appears — translation strings, outgoing emails, and links to the project's own site/docs are unaffected.

volumes:
  - ./branding/logo.svg:/app/branding/logo.svg:ro
environment:
  BRANDING_NAME: "My Recipes"
  BRANDING_LOGO_PATH: "/app/branding/logo.svg"

Docker Secrets

† Starting in version 2.4.2, any environment variable in the preceding lists with a dagger symbol next to them support the Docker Compose secrets pattern, below. Docker Compose secrets can be used to secure sensitive information regarding the Mealie implementation by managing control of each secret independently from the single .env file. This is helpful for users that may need different levels of access for various, sensitive environment variables, such as differentiating between hardening operations (e.g., server endpoints and ports) and user access control (e.g., usernames, passwords, and API keys).

To convert any of these environment variables to a Docker Compose secret, append _FILE to the environment variable and connect it with a Docker Compose secret, per the Docker documentation.

If both the base environment variable and the secret pattern of the environment variable are set, the secret will always take precedence.

Each configured _FILE path must point to a readable regular file. Startup stops with an error message if the file is missing, is not a regular file, or cannot be read, even when the base environment variable is also set. Trailing newlines are removed from the file contents. If the resulting value is empty, startup logs a warning and continues with an empty value, overriding any base environment variable.

The file must be readable by the application user after the container drops privileges (UID/GID 911 by default, or your configured runtime user). Kubernetes Secret volume symlinks are supported when their target is a readable regular file. Omit the _FILE variable when an optional setting is unused.

For example, a user that wishes to harden their operations by only giving some access to their database URL, but who wish to place additional security around their user access control, may have a Docker Compose configuration similar to:

services:
  mealie:
    secrets:
      # These secrets will be loaded by Docker into the `/run/secrets` folder within the container.
      - postgres-host
      - postgres-port
      - postgres-db-name
      - postgres-user
      - postgres-password

    environment:
      DB_ENGINE: postgres
      POSTGRES_SERVER: duplicate.entry.tld # This will be ignored, due to the secret defined, below.
      POSTGRES_SERVER_FILE: /run/secrets/postgres-host
      POSTGRES_PORT_FILE: /run/secrets/postgres-port
      POSTGRES_DB_FILE: /run/secrets/postgres-db-name
      POSTGRES_USER_FILE: /run/secrets/postgres-user
      POSTGRES_PASSWORD_FILE: /run/secrets/postgres-password

# Each of these secrets are loaded via these local files. Different patterns are available. See the Docker Compose
# documentation for more information.
secrets:
  postgres-host:
    file: ./secrets/postgres-host.txt
  postgres-port:
    file: ./secrets/postgres-port.txt
  postgres-db-name:
    file: ./secrets/sensitive/postgres-db-name.txt
  postgres-user:
    file: ./secrets/sensitive/postgres-user.txt
  postgres-password:
    file: ./secrets/sensitive/postgres-password.txt

.
├── docker-compose.yml
└── secrets                     # Access restricted to anyone that can manage secrets
    ├── postgres-host.txt
    ├── postgres-port.txt
    └── sensitive               # Access further-restricted to anyone managing service accounts
        ├── postgres-db-name.txt
        ├── postgres-password.txt
        └── postgres-user.txt

How you organize your secrets is ultimately up to you. At minimum, it's highly recommended to use secret patterns for at least these sensitive environment variables when working within shared environments:

• POSTGRES_PASSWORD
• SMTP_PASSWORD
• LDAP_QUERY_PASSWORD