Welcome to Merran

Merran brings your household’s recipes, meal plan, shopping list, and pantry together. Run it on your own server and use it from a phone, tablet, or desktop. An AI assistant is optional; the core works without a provider key.

Merran is currently alpha. Keep backups and expect changes between releases. This initial documentation follows the implementation in this repository; check the release notes for the image you run.

Start with a working kitchen

1. Install Merran with Docker Compose or Docker.
2. Set up your account and household.
3. Plan, shop, and cook your first week.

Use Merran every day

Follow the everyday workflow: Recipes → Planning → Shopping and pantry → Cooking. Each guide includes prerequisites, steps, expected results, limits, and troubleshooting.

Connect your kitchen

Install the browser extension or set up phone sharing. For store carts, follow Kroger or experimental Walmart. Optional modules covers nutrition, video imports, generated photos, and server voices.

Operate your server

For optional AI, start with provider setup and costs, then read privacy and data flow and assistant proposals and approvals.

Configuration explains the server, household, and personal settings. Read updating and backups before changing your installation.

Administrators can use household roles and permissions, the generated settings reference, and troubleshooting for day-to-day operations and recovery.

For deployment, follow HTTPS and remote access, Postgres, and the backup/restore walkthrough. The release verification record distinguishes tested release behavior from remaining checks.

Build an integration

Make your first API request, browse the generated endpoint reference, or download the OpenAPI specification.

Continue with a working recipe-index script and live events to build an integration.

Support

For a reproducible bug, open an issue. Include your Merran version, installation method, and relevant logs with secrets removed. To work on Merran, start with the contributor guide.