Skip to content
Klutch.sh Docs

Deploying a Mealie App

Introduction

Mealie is an open-source recipe manager and meal-planning application built on FastAPI and a modern web UI. Deploying Mealie with a Dockerfile on Klutch.sh delivers reproducible builds, managed secrets, and persistent storage for recipes, media, and backups—all configured from klutch.sh/app. This guide covers installation, repository prep, a production-ready Dockerfile, deployment steps, Nixpacks overrides, sample API usage, and production best practices.

Prerequisites

  • A Klutch.sh account (sign up)
  • A GitHub repository containing your Mealie code and Dockerfile (GitHub is the only supported git source)
  • Database credentials if you run Mealie with PostgreSQL (recommended) instead of SQLite
  • Optional object storage for large media exports

For onboarding, see the Quick Start.

Architecture and ports

  • Mealie serves HTTP on internal port 9000; choose HTTP traffic.
  • If you deploy PostgreSQL separately, run it as a Klutch.sh TCP app exposed on port 8000 and connect on 5432.
  • Persistent storage is required for application data, media, and backups.

Repository layout

mealie/
├── Dockerfile              # Must be at repo root for auto-detection
├── pyproject.toml / requirements.txt
├── package.json            # if front-end is included
├── .env.example            # Template only; no secrets
├── data/                   # App data/media (persist)
├── backups/                # Optional backups (persist)
└── README.md

Keep secrets out of Git; store them in Klutch.sh environment variables.

Installation (local) and starter commands

Validate locally before pushing to GitHub:

Terminal window
docker build -t mealie-local .
docker run -p 9000:9000 --env-file .env mealie-local

Dockerfile for Mealie (production-ready)

Place this Dockerfile at the repo root; Klutch.sh auto-detects it (no Docker selection in the UI):

FROM ghcr.io/mealie-recipes/mealie:latest


ENV PORT=9000
EXPOSE 9000


# Ensure data paths exist and are writable
RUN mkdir -p /app/data /app/backups && \
    chown -R root:root /app/data /app/backups


CMD ["./start.sh"]

Notes:

  • The upstream image bundles FastAPI, worker processes, and the web UI. Adjust the tag to a pinned version for stability.
  • Keep /app/data and /app/backups writable and mount them as volumes.

Environment variables (Klutch.sh)

Set these in Klutch.sh before deploying:

  • PORT=9000
  • BASE_URL=https://example-app.klutch.sh
  • ALLOW_SIGNUP=false (optional)
  • DB_ENGINE=postgres (or sqlite)
  • POSTGRES_USER=<user> / POSTGRES_PASSWORD=<password> / POSTGRES_SERVER=<host> / POSTGRES_PORT=5432 / POSTGRES_DB=<db> if using Postgres
  • OPENAI_API_KEY, SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASSWORD (optional, if enabled)
  • Timezone and locale: TZ=UTC
  • Any provider-specific keys your plugins require

If you deploy without the Dockerfile and need Nixpacks overrides (FastAPI/Python):

  • NIXPACKS_PYTHON_VERSION=3.11
  • NIXPACKS_BUILD_CMD=pip install -r requirements.txt
  • NIXPACKS_START_CMD=uvicorn mealie.app:app --host 0.0.0.0 --port 9000

Attach persistent volumes

In Klutch.sh storage settings, add mount paths and sizes (no names required):

  • /app/data — core application data, recipes, media, and config.
  • /app/backups — optional backup exports.

Ensure these directories are writable.

Deploy Mealie on Klutch.sh (Dockerfile workflow)

  1. Push your repository—with the Dockerfile at the root—to GitHub.
  2. Open klutch.sh/app, create a project, and add an app.
  3. Select HTTP traffic and set the internal port to 9000.
  4. Add the environment variables above, including database credentials and optional SMTP/OpenAI keys.
  5. Attach persistent volumes for /app/data and /app/backups with sizes that match your storage and retention needs.
  6. Deploy. Your Mealie instance will be reachable at https://example-app.klutch.sh; attach a custom domain if desired.

Sample API usage

Fetch recipes (example endpoint):

Terminal window
curl -X GET "https://example-app.klutch.sh/api/recipes" \
  -H "Authorization: Bearer <token>"

Health checks and production tips

  • Add an HTTP probe to /api/app/about or a lightweight health endpoint.
  • Enforce HTTPS at the edge; forward internally to port 9000.
  • Pin image versions for stability and test upgrades in staging first.
  • Monitor database connections and volume usage; resize before storage fills.
  • Store secrets only in Klutch.sh and rotate them regularly.
  • Schedule backups to /app/backups and sync them off-site if needed.

Mealie on Klutch.sh combines reproducible Docker builds with managed secrets, persistent storage, and flexible HTTP/TCP routing. With the Dockerfile at the repo root, port 9000 configured, and your database connected, you can deliver a reliable recipe and meal-planning experience without extra YAML or workflow overhead.