Docker/mealie
Docker/mealie
1
0
Fork 0
mirror of https://github.com/mealie-recipes/mealie.git synced 2025-08-04 04:55:21 +02:00
Code Issues Releases Activity

docs/update outline (#471)

Browse source 
* docs update

* reorganize

* plausible analytics

Co-authored-by: hay-kot <hay-kot@pm.me>
This commit is contained in:
Hayden 2021-06-07 15:04:30 -08:00 • committed by GitHub
parent 95b6ab86d0
commit a75de6d1cf
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
29 changed files with 104 additions and 78 deletions
Download patch file Download diff file Expand all files Collapse all files

131
docs/docs/documentation/admin/backups-and-exports.md Normal file
View file

@ -0,0 +1,131 @@
# Backup and Imports
All recipe data can be imported and exported as necessary from the UI. Under the admin page you'll find the section for using Backups and Exports.
!!! danger
As this is still a **BETA** It is recommended that you backup your data often and store in more than one place. Ad-hear to backup best practices with the [3-2-1 Backup Rule](https://en.wikipedia.org/wiki/Backup). Prior to upgrading you **should** perform a backup to limit any data loss.
!!! tip "Mealie data that is saved on backups"
- [x] Recipe Data
- [ ] Meal Plan
- [x] Site Settings
- [x] Custom Pages
- [x] User Data
- [x] Group Data
To create an export simply add the tag and the markdown template and click "Create" and your backup will be created on the server. The backup is a standard zipfile containing all the images, json files, and rendered jinaj2 templates for each recipe. To view the available variables, open a recipe in the json editor.
To import a backup it must be in your backups folder. If it is in the backup folder it will automatically show up as a source to restore from. Selected the desired backup and import the backup file. Backups can be uploaded from the UI as well as added on the file system
## Demo
![](../../assets/gifs/backup-demo-v1.gif)
## API Examples
You can use the API to create and retrieve backups remotely from any server that can access the Mealie instance. This is useful for easily managing off-site backups via cron-job or other scheduled tasks. You can find interactive documentation for your API at https://your-mealie-instance.com/docs
### curl Example
Create a backup with curl
```bash
curl -X 'POST' \
'http://localhost:9000/api/backups/export/database' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"tag": "July 23rd 2021",
"options": {
"recipes": true,
"settings": true,
"themes": true
},
"templates": [
"recipes.md"
]
}'
```
### wget Example
First request a file token with curl:
```bash
curl -X 'GET' \
'http://localhost:9000/api/backups/{file_name}/download' \
-H 'accept: application/json' \
-H 'Content-Type: application/json'
```
Then download the file with wget:
```bash
wget http://localhost:9000/api/utils/download?token={fileToken}
```
## Jinja2 Templating
On export you can select a template to use to render files using the jinja2 syntax. This can be done to export recipes in other formats besides regular .json.Look at this example for rendering a markdown recipe using the jinja2 syntax.
### Input
```jinja2
![Recipe Image](../images/{{ recipe.image }})
# {{ recipe.name }}
{{ recipe.description }}
## Ingredients
{% for ingredient in recipe.recipeIngredient %}
- [ ] {{ ingredient }}
{% endfor %}
## Instructions
{% for step in recipe.recipeInstructions %}
- [ ] {{ step.text }}
{% endfor %}
{% for note in recipe.notes %}
**{{ note.title }}:** {{ note.text }}
{% endfor %}
---
Tags: {{ recipe.tags }}
Categories: {{ recipe.categories }}
Original URL: {{ recipe.orgURL }}
```
### Output
```markdown
![Recipe Image](../images/five-spice-popcorn-chicken.jpg)
# Five Spice Popcorn Chicken
It’s easy to rely on take-out for some of our favorite Chinese dishes. However, with the right pantry staples, dishes like this Five Spice Popcorn Chicken can become part of your go-to arsenal of recipes. This crispy chicken is coated in a creamy, tangy sauce, made zesty with The Spice Hunter Chinese Five Spice, a blend of star anise, cloves, cinnamon, fennel, and black pepper.
## Ingredients
- [ ] 1 tablespoon soy sauce
- [ ] 1 tablespoon sugar
- [ ] 1 teaspoon The Spice Hunter® Chinese Five Spice Blend, plus more for serving
- [ ] 1 clove garlic, finely grated
- [ ] 1 1/2 pounds boneless skinless chicken thighs, cut into roughly 1-inch chunks
- [ ] ⅓ cup cornstarch
- [ ] 1 large egg, beaten
- [ ] ¾ cup all-purpose flour
- [ ] Canola or vegetable oil, for frying
- [ ] Flaky sea salt
- [ ] Scallion, thinly sliced, for serving
- [ ] Sriracha mayonnaise, for serving, optional
## Instructions
- [ ] In a medium bowl, whisk the soy sauce with the sugar, Chinese Five Spice, and garlic. Add the chicken and toss to coat. Let marinate 15 minutes.
- [ ] Drain any excess marinade off of the chicken and toss the chicken with the cornstarch to coat. Once fully coated, add the beaten egg and toss to coat.
- [ ] In a large heavy bottomed pot, heat 1-inch of oil to 350.
- [ ] Place the flour in a large ziploc bag. Working in batches, transfer a few chicken pieces into the bag with the flour and toss to coat, then remove, leaving excess flour in the bag.
- [ ] Carefully place the breaded chicken in the hot oil and fry, turning occasionally, until golden and cooked through about 3 to 4 minutes.
- [ ] Using a slotted spoon or spider, transfer the cooked chicken to a paper towel lined plate. Season with salt and additional Chinese Five Spice seasoning. Repeat the flouring and frying with remaining chicken.
- [ ] Serve with scallions, more Chinese Five Spice Blend, and optional sriracha mayonnaise.
---
Tags: []
Categories: []
Original URL: https://www.bonappetit.com/recipe/five-spice-popcorn-chicken#intcid=_bon-appetit-recipe-bottom-recirc_3cad5ce9-734a-46f8-b503-78c33d2e7279_similar2-3
```
If you decide you don't like mealie. This is a good way to export into a format that can be imported into another.

11
docs/docs/documentation/admin/building-pages.md Normal file
View file

@ -0,0 +1,11 @@
# Building Pages
!!! warning
The page building is still experimental and may change. You can provide feedback on any changes you'd like to see on [github](https://github.com/hay-kot/mealie/discussions/229)
Custom pages can be created to organize multiple categories into a single page. Links to your custom pages are displayed on the home page sidebar and accessible by all users, however only Administrators can create or update pages.
To create a new page. Navigate to the settings page at `/admin/settings` and scroll down to the custom pages section. Here you can create, view, and edit your custom pages. To reorder how they are displayed on the sidebar you can drag and drop the pages into the preferred order.
!!! tip
To save the order of pages you must click the save button displayed on the bottom of the Custom Page section. This is not necessary for updating individual page data.

13
docs/docs/documentation/admin/dashboard.md Normal file
View file

@ -0,0 +1,13 @@
#Dashboard
The dashboard gives you a quick overview of how your Mealie is doing. There is a 'Recipes' card, an overview of the users and groups, an 'Events' card and a 'Backups' card.
![dashboard](../../assets/img/dashboard.webp)
##Recipes
'Recipes' shows how many recipes you have in your catalogue but also checks if you have any untagged or uncategorized ones. If you click on one of these, you are redirected to the Toolbox where you can further organize these recipes.
##Backups
Here you can choose to import an older backup from a previous instance. You could also create a custom backup with your own tag where you can choose for a full backup or only some parts like recipes, users,...
If you click 'create', an automatic backup is generated.

24
docs/docs/documentation/admin/migration-imports.md Normal file
View file

@ -0,0 +1,24 @@
# Migration
## Chowdown
To migrate recipes from a Chowdown
1. Download the code repository as a .zip file
2. Upload the .zip file in the Chowdown section in Mealie
3. Select import on the newly available migration.
## Nextcloud Recipes
Nextcloud recipes can be imported from a zip file the contains the data stored in Nextcloud. The zip file can be uploaded from the frontend or placed in the data/migrations/nextcloud directory. See the example folder structure below to ensure your recipes are able to be imported.
```
nextcloud_recipes.zip
├── recipe_1
│ ├── recipe.json
│ ├── full.jpg
│ └── thumb.jpg
├── recipe_2
│ ├── recipe.json
│ └── full.jpg
└── recipe_3
└── recipe.json
```

19
docs/docs/documentation/admin/site-settings.md Normal file
View file

@ -0,0 +1,19 @@
# Site Settings
Your sites settings panel can only be accessed by administrators. This where you can customize your site for all users.
## Home Page Settings
| Option | Description |
| ------------------ | -------------------------------------------------------------- |
| Show Recent | To display the recent recipes section on the home page |
| Card Per Section | The amount of cards displayed in each section on the home page |
| Home Page Sections | Category sections to include on the home page |
| Language | The default site language |
| First day of the week | The default start day of the week used in Meal Plans |
| Custom Pages | Create a custom page which appears in the sidebar with the categories you chose |
![Site Settings Image](../../assets/img/site-settings.webp)

86
docs/docs/documentation/admin/user-management.md Normal file
View file

@ -0,0 +1,86 @@
# User Managemenet
As of version v0.4.0 users have limited functionality, but they will offer more permissions and structure as time goes on. To understand the different systems, see each section below. Note, that by default all users will be assigned the default group. If you're only managing one household you won't need to do anything to set up a new group.
!!! summary "Users and Groups"
=== ":fontawesome-solid-user-cog: Admins"
Mealie admins are super users that have access to all user data (excluding passwords). All admins can perform administrative tasks like adding users, resetting user passwords, backing up the database, migrating data, and managing site settings.
**Admins Can**
- All User Actions
- Adjust Site Settings
- Create and Update Users
- Create and Update Groups
- Generate User Sign-up Links
- Migrate Data from other Services
- Backup Site Data
=== ":fontawesome-solid-user: Users"
A single user created by an Admin that has basic privileges to edit their profile, create and edit recipes.
**Users Can**
- Manage Their Profile
- Create, Edit, and Update Recipes
- Create, Edit, and Update Mealplans *(By Group)*
- Set Mealplan Categories
- Create and Schedule Webhooks *(By Group)*
=== ":fontawesome-solid-users: Groups"
User groups are a collection of users that are associated together. Typically used for separate households sharing a single instance.
**Groups Share**
- Mealplans
- Mealplan Settings
- Webhooks
!!! warning
As of v0.4.0 any authenticated user is able to perform any action on the backend server through the API. To limit a standard users scope, the pages on the frontend are limited. Proper support for permission structures on the backend API will come in a later version.
## Startup
On the first startup you'll need to login to Mealie using the default username and password `changeme@email.com` and `MyPassword` or the default set through the env variable. On first login you'll be required to reset your password. After resetting your password you should also change your email address as appropriate. This will be used for logins on all future requests.
!!! tip
Your default password environmental variable will be the default password for all new users that are created. This is stored in plain text and should not be used **any where** else.
## Creating and Editing Users
There are two ways to create users in Mealie.
### Manually Creating a User
In the Manage Users section you are able to create a user by providing the necessary information in the pop-up dialog.
![Create User Image](../../assets/img/add-user.webp){: align=right style="height:50%;width:50%"}
- User Name
- Email
- User Group
- If they are an Admin
When creating users manually, their password will be set from the default assigned by the ENV variable.
### Sign Up Links
You can generate sign-up links in the Manage Users section. Select the "create link" button and provide the name of the link and if the user will be an administrator. Once a link is created it will populate in the table where you'll be able to see all active links, delete a link, and copy the link as needed.
![Sign Up Links Image](../../assets/img/sign-up-links.webp)
!!! tip
When a link is used it is automatically removed from the database.
## Creating Groups
You can easily create and manage groups via the frontend in the admin panel under "Manage Users". Navigate to the groups tab and you'll find a "create group" button as well as a list of all groups in your database. To create a group, select the "create group" button and provide a name for the new group. Once created you can now assign users to the new group.
![Group Management Panel](../../assets/img/group-manager.png)
!!! tip
User Groups can only be deleted if no users are apart of the group. If you want to delete a group, you must assign the users to another group before removing.
## Password Reset
If a user forgets their password an administrator is able to reset their password through the user management page. In the user table, select edit. In the popup windows click the "Reset Password" to reset a users password to the default. This is either 'MyPassword' or set through an environment variable. See the [Installation Page](/mealie/getting-started/install/) for more details on environmental variables

2
docs/docs/documentation/community-guide/.header.md Normal file
View file

@ -0,0 +1,2 @@
!!! info
This guide was submitted by a community member. Find something wrong? Submit a PR to get it fixed!

93
docs/docs/documentation/community-guide/bulk-url-import.md Normal file
View file

@ -0,0 +1,93 @@
!!! info
This guide was submitted by a community member. Find something wrong? Submit a PR to get it fixed!
Recipes can be imported in bulk from a file containing a list of URLs. This can be done using the following bash or python scripts with the `list` file containing one URL per line.
#### Bash
```bash
#!/bin/bash
function authentification () {
auth=$(curl -X 'POST' \
"$3/api/auth/token" \
-H 'accept: application/json' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'grant_type=&username='$1'&password='$2'&scope=&client_id=&client_secret=')
echo $auth | sed -e 's/.*token":"\(.*\)",.*/\1/'
}
function import_from_file () {
while IFS= read -r line
do
echo $line
curl -X 'POST' \
"$3/api/recipes/create-url" \
-H "Authorization: Bearer $2" \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '{"url": "'$line'" }'
echo
done < "$1"
}
input="list"
mail="changeme@email.com"
password="MyPassword"
mealie_url=http://localhost:9000
token=$(authentification $mail $password $mealie_url)
import_from_file $input $token $mealie_url
```
#### Python
```python
import requests
import re
def authentification(mail, password, mealie_url):
headers = {
'accept': 'application/json',
'Content-Type': 'application/x-www-form-urlencoded',
}
data = {
'grant_type': '',
'username': mail,
'password': password,
'scope': '',
'client_id': '',
'client_secret': ''
}
auth = requests.post(mealie_url + "/api/auth/token", headers=headers, data=data)
token = re.sub(r'.*token":"(.*)",.*', r'\1', auth.text)
return token
def import_from_file(input_file, token, mealie_url):
with open(input_file) as fp:
for l in fp:
line = re.sub(r'(.*)\n', r'\1', l)
print(line)
headers = {
'Authorization': "Bearer " + token,
'accept': 'application/json',
'Content-Type': 'application/json'
}
data = {
'url': line
}
response = requests.post(mealie_url + "/api/recipes/create-url", headers=headers, json=data)
print(response.text)
input_file="list"
mail="changeme@email.com"
password="MyPassword"
mealie_url="http://localhost:9000"
token = authentification(mail, password, mealie_url)
import_from_file(input_file, token, mealie_url)
```

34
docs/docs/documentation/community-guide/home-assistant.md Normal file
View file

@ -0,0 +1,34 @@
!!! info
This guide was submitted by a community member. Find something wrong? Submit a PR to get it fixed!
In a lot of ways, Home Assistant is why this project exists! Since it Mealie has a robust API it makes it a great fit for interacting with Home Assistant and pulling information into your dashboard.
### Get Todays Meal in Lovelace
Starting in v0.4.1 you are now able to use the uri `/api​/meal-plans​/today​/image?group_name=Home` to directly access the image to todays meal. This makes it incredible easy to include the image into your Home Assistant Dashboard using the picture entity.
Here's an example where `sensor.mealie_todays_meal` is pulling in the meal-plan name and I'm using the url to get the image.
![api-extras-gif](../../assets/img/home-assistant-card.png)
```yaml
type: picture-entity
entity: sensor.mealie_todays_meal
name: Dinner Tonight
show_state: true
show_name: true
image: 'http://localhost:9000/api/meal-plans/today/image?group_name=Home'
style:
.: |
ha-card {
max-height: 300px !important;
overflow: hidden;
display: flex;
align-items: center;
justify-content: center;
}
```
!!! tip
Due to how Home Assistant works with images, I had to include the additional styling to get the images to not appear distorted. This includes and [additional installation](https://github.com/thomasloven/lovelace-card-mod) from HACS.

40
docs/docs/documentation/community-guide/ios.md Normal file
View file

@ -0,0 +1,40 @@
# Using iOS Shortcuts with Mealie
!!! info
This guide was submitted by a community member. Find something wrong? Submit a PR to get it fixed!
![](../../assets/img/iphone-image.png){: align=right style="height:400px;width:400px"}
User [brasilikum](https://github.com/brasilikum) opened an issue on the main repo about how they had created an [iOS shortcut](https://github.com/hay-kot/mealie/issues/103) for interested users. This is a useful utility for iOS users who browse for recipes in their web browser from their devices.
Don't know what an iOS shortcut is? Neither did I! Experienced iOS users may already be familiar with this utility but for the uninitiated, here is the official Apple explanation:
> A shortcut is a quick way to get one or more tasks done with your apps. The Shortcuts app lets you create your own shortcuts with multiple steps. For example, build a “Surf Time” shortcut that grabs the surf report, gives an ETA to the beach, and launches your surf music playlist.
Basically it is a visual scripting language that lets a user build an automation in a guided fashion. The automation can be [shared with anyone](https://www.icloud.com/shortcuts/6ae356d5fc644cfa8983a3c90f242fbb) but if it is a user creation, you'll have to jump through a few hoops to make an untrusted automation work on your device. In brasilikum's shortcut, you need to make changes for it to work. Recent updates to the project have changed some of the syntax and folder structure since its original creation.
![screenshot](../../assets/img/ios-shortcut-image.jpg){: align=right style="height:500;width:400px"}
!!! tip
You may need to change the url depending on which version you're using. Recipe is now plural and there is no trailing "/" at the end of the string.
```
api/recipe/create-url/
```
to
```
api/recipes/create-url
```
Having made those changes, you should now be able to share a website to the shortcut and have mealie grab all the necessary information!

92
docs/docs/documentation/community-guide/swag.md Normal file
View file

@ -0,0 +1,92 @@
# Using SWAG as Reverse Proxy
!!! info
This guide was submitted by a community member. Find something wrong? Submit a PR to get it fixed!
To make the setup of a Reverse Proxy much easier, Linuxserver.io developed [SWAG](https://github.com/linuxserver/docker-swag)
SWAG - Secure Web Application Gateway (formerly known as letsencrypt, no relation to Let's Encrypt™) sets up an Nginx web server and reverse proxy with PHP support and a built-in certbot client that automates free SSL server certificate generation and renewal processes (Let's Encrypt and ZeroSSL). It also contains fail2ban for intrusion prevention.
## Step 1: Get a domain
The first step is to grab a dynamic DNS if you don't have your own subdomain already. You can get this from for example [DuckDNS](https://www.duckdns.org).
## Step 2: Set-up SWAG
Then you will need to set up SWAG, the variables of the docker-compose are explained on the Github page of [SWAG](https://github.com/linuxserver/docker-swag).
This is an example of how to set it up using duckdns and docker-compose.
!!! example "docker-compose.yml"
```yaml
version: "2.1"
services:
swag:
image: ghcr.io/linuxserver/swag
container_name: swag
cap_add:
- NET_ADMIN
environment:
- PUID=1000
- PGID=1000
- TZ=Europe/Brussels
- URL=<mydomain.duckdns>
- SUBDOMAINS=wildcard
- VALIDATION=duckdns
- CERTPROVIDER= #optional
- DNSPLUGIN= #optional
- DUCKDNSTOKEN=<duckdnstoken>
- EMAIL=<e-mail> #optional
- ONLY_SUBDOMAINS=false #optional
- EXTRA_DOMAINS=<extradomains> #optional
- STAGING=false #optional
volumes:
- /etc/config/swag:/config
ports:
- 443:443
restart: unless-stopped
```
Don't forget to change the <code>mydomain.duckns</code> into your personal domain and the <code>duckdnstoken</code> into your token and remove the brackets.
## Step 3: Change the config files
Navigate to the config folder of SWAG and head to <code>proxy-confs</code>. If you used the example above, you should navigate to: <code>/etc/config/swag/nginx/proxy-confs/</code>.
There are a lot of preconfigured files to use for different apps such as radarr,sonarr,overseerr,...
To use the bundled configuration file, simply rename <code>mealie.subdomain.conf.sample</code> in the proxy-confs folder to <code>mealie.subdomain.conf</code>.
Alternatively, you can create a new file <code>mealie.subdomain.conf</code> in proxy-confs with the following configuration:
!!! example "mealie.subdomain.conf"
```yaml
server {
listen 443 ssl http2;
listen [::]:443 ssl http2;
server_name mealie.*;
include /config/nginx/ssl.conf;
client_max_body_size 0;
location / {
include /config/nginx/proxy.conf;
include /config/nginx/resolver.conf;
set $upstream_app mealie;
set $upstream_port 80;
set $upstream_proto http;
proxy_pass $upstream_proto://$upstream_app:$upstream_port;
}
}
```
## Step 4: Port-forward port 443
Since SWAG allows you to set up a secure connection, you will need to open port 443 on your router for encrypted traffic. This is way more secure than port 80 for http.
## Step 5: Restart SWAG
When you change anything in the config of Nginx, you will need to restart the container using <code>docker restart swag</code>.
If everything went well, you can now access mealie on the subdomain you configured: mealie.mydomain.duckdns.org

39
docs/docs/documentation/getting-started/api-usage.md Normal file
View file

@ -0,0 +1,39 @@
# Usage
## Getting a Token
Mealie supports long-live api tokens in the user frontend. In you profile section you can use the
### Curl
```bash
curl -X 'POST' \
'https://mealie-demo.hay-kot.dev/api/auth/token' \
-H 'accept: application/json' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'grant_type=&username=changeme%40email.com&password=demo&scope=&client_id=&client_secret='
```
#### Response
```json
{
"snackbar": {
"text": "User Successfully Logged In",
"type": "success"
},
"access_token": "your-long-token-string",
"token_type": "bearer"
}
```
## Key Components
### Exploring Your Local API
On your local installation you can access interactive API documentation that provides `curl` examples and expected results. This allows you to easily test and interact with your API to identify places to include your own functionality. You can visit the documentation at `http://mealie.yourdomain.com/docs or see the example at the [Demo Site](https://mealie-demo.hay-kot.dev/docs)
### Recipe Extras
Recipes extras are a key feature of the Mealie API. They allow you to create custom json key/value pairs within a recipe to reference from 3rd part applications. You can use these keys to contain information to trigger automation or custom messages to relay to your desired device.
For example you could add `{"message": "Remember to thaw the chicken"}` to a recipe and use the webhooks built into mealie to send that message payload to a destination to be processed.
![api-extras-gif](../../assets/gifs/api-extras.gif)

167
docs/docs/documentation/getting-started/install.md Normal file
View file

@ -0,0 +1,167 @@
# Installation
To deploy mealie on your local network it is highly recommended to use docker to deploy the image straight from dockerhub. Using the docker-compose below you should be able to get a stack up and running easily by changing a few default values and deploying. You can deploy with either SQLite (default) or Postgres. SQLite is sufficient for most use cases. Additionally, with mealies automated backup and restore functionality, you can easily move between SQLite and Postgres as you wish.
[Get Docker](https://docs.docker.com/get-docker/)
[Mealie on Dockerhub](https://hub.docker.com/r/hkotel/mealie)
- linux/amd64
- linux/arm64
## Quick Start - Docker CLI
Deployment with the Docker CLI can be done with `docker run` and specify the database type, in this case `sqlite`, setting the exposed port `9925`, mounting the current directory, and pull the latest image. After the image is up an running you can navigate to http://your.ip.addres:9925 and you'll should see mealie up and running!
```shell
docker run \
-p 9925:80 \
-v `pwd`:'/app/data/' \
hkotel/mealie:latest
```
!!! tip "Default Credentials"
**Username:** changeme@email.com
**Password:** MyPassword
## Docker Compose with SQLite
Deployment with docker-compose is the recommended method for deployment. The example below will create an instance of mealie available on port `9925` with the data volume mounted from the local directory. To use, create a docker-compose.yml file, paste the contents below and save. In the terminal run `docker-compose up -d` to start the container.
```yaml
version: "3.1"
services:
mealie:
container_name: mealie
image: hkotel/mealie:latest
restart: always
ports:
- 9925:80
environment:
TZ: America/Anchorage
volumes:
- ./mealie/data/:/app/data
```
## Docker Compose with Postgres *(BETA)*
Postgres support was introduced in v0.5.0. At this point it should be used with caution and frequent backups.
```yaml
version: "3.1"
services:
mealie:
container_name: mealie
image: hkotel/mealie:latest
restart: always
ports:
- 9090:80
environment:
DB_ENGINE: postgres # Optional: 'sqlite', 'postgres'
POSTGRES_USER: mealie
POSTGRES_PASSWORD: mealie
POSTGRES_SERVER: postgres
POSTGRES_PORT: 5432
POSTGRES_DB: mealie
postgres:
container_name: postgres
image: postgres
restart: always
environment:
POSTGRES_PASSWORD: mealie
POSTGRES_USER: mealie
```
## Env Variables
| Variables | Default | Description |
| ----------------- | --------------------- | ----------------------------------------------------------------------------------- |
| DEFAULT_GROUP | Home | The default group for users |
| DEFAULT_EMAIL | changeme@email.com | The default username for the superuser |
| BASE_URL | http://localhost:8080 | Used for Notifications |
| DB_ENGINE | sqlite | Optional: 'sqlite', 'postgres' |
| POSTGRES_USER | mealie | Postgres database user |
| POSTGRES_PASSWORD | mealie | Postgres database password |
| POSTGRES_SERVER | postgres | Postgres database server address |
| POSTGRES_PORT | 5432 | Postgres database port |
| POSTGRES_DB | mealie | Postgres database name |
| TOKEN_TIME | 2 | The time in hours that a login/auth token is valid |
| API_PORT | 9000 | The port exposed by backend API. **do not change this if you're running in docker** |
| API_DOCS | True | Turns on/off access to the API documentation locally. |
| TZ | UTC | Must be set to get correct date/time on the server |
!!! tip "Fatal Python error: init_interp_main: can't initialize time"
Some users experience an problem with running the linux/arm/v7 container on Raspberry Pi 4. This is not a problem with the Mealie container, but with a bug in the hosts Docker installation.
Update the host RP4 using [instructions](linuxserver/docker-papermerge#4 (comment)), summarized here:
```shell
wget http://ftp.us.debian.org/debian/pool/main/libs/libseccomp/libseccomp2_2.5.1-1_armhf.deb
sudo dpkg -i libseccomp2_2.5.1-1_armhf.deb
```
## Advanced
!!! warning "Not Required"
The items below are completely optional and are not required to manage or install your Mealie instance.
### Custom Caddy File
The Docker image provided by Mealie contains both the API and the html bundle in one convenient image. This is done by using a proxy server to serve different parts of the application depending on the URL/URI. Requests sent to `/api/*` or `/docs` will be directed to the API, anything else will be served the static web files. Below is the default Caddyfile that is used to proxy requests. You can override this file by mounting an alternative Caddyfile to `/app/Caddyfile`.
```
{
auto_https off
admin off
}
:80 {
@proxied path /api/* /docs /openapi.json
root * /app/dist
encode gzip
uri strip_suffix /
handle_path /api/recipes/image/* {
root * /app/data/img/
file_server
}
handle @proxied {
reverse_proxy http://127.0.0.1:9000
}
handle {
try_files {path}.html {path} /
file_server
}
}
```
## Deployed without Docker
!!! error "Unsupported Deployment"
If you are experiencing a problem with manual deployment, please do not submit a github issue unless it is related to an aspect of the application. For deployment help, the [discord server](https://discord.gg/QuStdQGSGK) is a better place to find support.
Alternatively, this project is built on Python and SQLite so you may run it as a python application on your server. This is not a supported options for deployment and is only here as a reference for those who would like to do this on their own. To get started you can clone this repository into a directory of your choice and use the instructions below as a reference for how to get started.
There are three parts to the Mealie application
- Frontend/Static Files
- Backend API
- Proxy Server
### Frontend/ Static Files
The frontend static files are generated with `npm run build`. This is done during the build process with docker. If you choose to deploy this as a system application you must do this process yourself. In the project directory run `cd frontend` to change directories into the frontend directory and run `npm install` and then `npm run build`. This will generate the static files in a `dist` folder in the frontend directory.
### Backend API
The backend API is build with Python, FastAPI, and SQLite and requires Python 3.9, and Poetry. Once the requirements are installed, in the project directory you can run the command `poetry install` to create a python virtual environment and install the python dependencies.
Once the dependencies are installed you should be ready to run the server. To initialize that database you need to first run `python mealie/db/init_db.py`. Then to start The web server, you run the command `uvicorn mealie.app:app --host 0.0.0.0 --port 9000`
### Proxy Server
You must use a proxy server to server up the static files created with `npm run build` and proxy requests to the API. In the docker build this is done with Caddy. You can use the CaddyFile in the section above as a reference. One important thing to keep in mind is that you should drop any trailing `/` in the url. Not doing this may result in failed API requests.

71
docs/docs/documentation/getting-started/introduction.md Normal file
View file

@ -0,0 +1,71 @@
# About The Project
Mealie is a self hosted recipe manager and meal planner with a RestAPI backend and a reactive frontend application built in Vue for a pleasant user experience for the whole family. Easily add recipes into your database by providing the url and Mealie will automatically import the relevant data or add a family recipe with the UI editor. Mealie also provides an API for interactions from 3rd party applications.
[Remember to join the Discord](https://discord.gg/QuStdQGSGK)!
!!! note
In some of the demo gifs the styling may be different than the finale application. demos were done during development prior to finale styling.
!!! warning
This is a **BETA** release and that means things may break and or change down the line. I'll do my best to make sure that any API changes are thoughtful and necessary in order not to break things. Additionally, I'll do my best to provide a migration path if the database schema ever changes. Do not use programs like watchtower to auto update your container. You **WILL** run into issues if you do this,
## Key Features
- 🔍 Fuzzy search
- 🏷️ Tag recipes with categories or tags to flexible sorting
- 🕸 Import recipes from around the web by URL
- 📱 Progressive Web App
- 📆 Create Meal Plans
- 🛒 Generate shopping lists
- 🐳 Easy setup with Docker
- 🎨 Customize your interface with color themes layouts
- 💾 Export all your data in any format with Jinja2 Templates, with easy data restoration from the user interface.
- 🌍 localized in many languages
- ➕ Plus tons more!
- Flexible API
- Custom key/value pairs for recipes
- Webhook support
- Interactive API Documentation thanks to [FastAPI](https://fastapi.tiangolo.com/) and [Swagger](https://petstore.swagger.io/)
- Raw JSON Recipe Editor
- Migration from other platforms
- Chowdown
- Nextcloud Cookbook
- Random meal plan generation
## FAQ
### Why An API?
An API allows integration into applications like [Home Assistant](https://www.home-assistant.io/) that can act as notification engines to provide custom notifications based of Meal Plan data to remind you to defrost the chicken, marinade the steak, or start the CrockPot. Additionally, you can access nearly any backend service via the API giving you total control to extend the application. To explore the API spin up your server and navigate to http://yourserver.com/docs for interactive API documentation.
### Why a Database?
Some users of static-site generator applications like ChowDown have expressed concerns about their data being stuck in a database. Considering this is a new project it is a valid concern to be worried about your data. Mealie specifically addresses this concern by provided automatic daily backups that export your data in json, plain-text markdown files, and/or custom Jinja2 templates. **This puts you in controls of how your data is represented** when exported from Mealie, which means you can easily migrate to any other service provided Mealie doesn't work for you.
As to why we need a database?
- **Developer Experience:** Without a database a lot of the work to maintain your data is taken on by the developer instead of a battle tested platform for storing data.
- **Multi User Support:** With a solid database as backend storage for your data Mealie can better support multi-user sites and avoid read/write access errors when multiple actions are taken at the same time.
## Built With
* [Vue.js](https://vuejs.org/)
* [Vuetify](https://vuetifyjs.com/en/)
* [FastAPI](https://fastapi.tiangolo.com/)
* [Docker](https://www.docker.com/)
<!-- ROADMAP -->
## Road Map
[See Roadmap](/roadmap)
<!-- CONTRIBUTING -->
## Contributing
Contributions are what make the open source community such an amazing place to be learn, develop, and create. Any contributions you make are **greatly appreciated**. See the [Contributors Guide](https://hay-kot.github.io/mealie/contributors/developers-guide/code-contributions/) for help getting started.
If you are not a coder, you can still contribute financially. financial contributions help me prioritize working on this project over others and helps me know that there is a real demand for project development.
<a href="https://www.buymeacoffee.com/haykot" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/v2/default-green.png" alt="Buy Me A Coffee" style="height: 60px !important;width: 217px !important;" ></a>

21
docs/docs/documentation/getting-started/updating.md Normal file
View file

@ -0,0 +1,21 @@
# Updating Mealie
!!! warning "Read The Release Notes"
You MUST read the release notes prior to upgrading your container. Currently Mealie provides no database migrations as doing such would slow down development and hinder major changes that may need to happen prior to v1.0.0. Mealie has a robust backup and restore system for managing your data.
### Before Upgrading
- Read The Release Notes
- Identify Breaking Changes
- Create a Backup and Download from the UI
- Upgrade
## Backing Up Your Data
[See Backups and Restore Section](/mealie/site-administration/backups-and-exports/) for details on backing up your data
## Docker
For all setups using Docker the updating process look something like this
- Stop the container using docker-compose down
- Pull the latest image using docker-compose pull
- Start the container again using docker-compose up -d

23
docs/docs/documentation/recipes/organizing-recipes.md Normal file
View file

@ -0,0 +1,23 @@
# Organizing Recipes
Below are some general guidelines that were considered when creating the organization structure for recipes.
## From The Community
> My categories are mostly based on the 'course' they belong to. Appetizers, Starters, Main course, but also sauces or beverages. When I'm looking for an idea for an every day dinner, I just browse "main course".
>
> My tags are for picking the exact type of meal I'm looking for, based on my mood or my guests' diet, like gluten-free, vegetarian, sweet-sour or casserole. They can also act as sub-categories, like "alcohol" for beverages or "hot meal" for a main course.
>
> User: [sephrat](https://github.com/sephrat)
## Structure
!!! tip
Below is a suggestion of guidelines my wife and I use for organizing our recipes within Mealie. Mealie is fairly flexible, so feel free to utilize how you'd like! 👍
In the diagram below you will see what we came up with using the new custom pages feature. The large circles indicate pages, and the rectangles indicate categories. We've grouped several 'like' categories with each other as a way to quickly find similar items.
![Mealie Diagram](../../assets/img/mealie-diagram.webp)

90
docs/docs/documentation/recipes/recipes.md Normal file
View file

@ -0,0 +1,90 @@
# Recipes
## URL Import
Adding a recipe can be as easy as copying the recipe URL into mealie and letting the web scrapper try to pull down the information. Currently this scraper is implemented with [scrape-schema-recipe package](https://pypi.org/project/scrape-schema-recipe/). You may have mixed results on some websites, especially with blogs or non specific recipe websites. See the bulk import Option below for another a convenient way to add blog style recipes into Mealie.
## Recipe Editor
Recipes can be edited and created via the UI. This is done with both a form based approach where you have a UI to work with as well as with a in browser JSON Editor. The JSON editor allows you to easily copy and paste data from other sources.
You can also add a custom recipe with the UI editor built into the web view.
## Bulk Import
Mealie also supports bulk import of recipe instructions and ingredients. Select "Bulk Add" in the editor and paste in your plain text data to be parsed. Each line is treated as one entry and will be appended to the existing ingredients or instructions if they exist. Empty lines will be stripped from the text.
![](../assets/gifs/bulk-add-demo.gif)
## Schema
Recipes are stored in the json-like format in mongoDB and then sent and edited in json format on the frontend. Each recipes uses [Recipe Schema](https://schema.org/Recipe) as a general guide with some additional properties specific to Mealie.
### Example
```json
{
_id: ObjectId('5fcdc3d715f131e8b191f642'),
name: 'Oat and Pecan Brittle Cookies',
description: 'A gorgeously textured cookie with crispy-edges, a chewy center, toasty pecans, and tiny crispy pecan brittle bits throughout.',
image: 'oat-and-pecan-brittle-cookies.jpg',
recipeYield: 'Makes about 18',
recipeIngredient: [
'1¼ cups (142 g) coarsely chopped pecans',
'¾ cup (150 g) granulated sugar',
'4 Tbsp. (½ stick) unsalted butter',
'½ tsp. baking soda',
'½ tsp. Diamond Crystal or ¼ tsp. Morton kosher salt',
'1 cup (2 sticks) unsalted butter, cut into 16 pieces, divided',
'1⅓ cups (173 g) all-purpose flour',
'2 tsp. Diamond Crystal or 1 tsp. Morton kosher salt',
'1 tsp. baking soda',
'2 cups (200 g) old-fashioned oats, divided',
'¾ cup (packed; 150 g) dark brown sugar',
'½ cup (100 g) granulated sugar',
'2 large eggs',
'1 Tbsp. vanilla extract'
],
recipeInstructions: [
{
'@type': 'HowToStep',
text: 'Place a rack in middle of oven; preheat to 350°. Toast pecans on a small rimmed baking sheet, tossing halfway through, until slightly darkened and fragrant, 8–10 minutes. Let cool.'
},
{
'@type': 'HowToStep',
text: 'Line another small rimmed baking sheet with a Silpat baking mat. Cook granulated sugar, butter, and 2 Tbsp. water in a small saucepan over medium-low heat, stirring gently with a heatproof rubber spatula, until sugar is dissolved. Increase heat to medium and bring syrup to a rapid simmer. Cook, without stirring, swirling pan often, until syrup turns a deep amber color, 8–10 minutes. Immediately remove saucepan from heat and stir in pecans. Once pecans are well coated, add baking soda and salt and stir to incorporate (mixture will foam and sputter as baking soda aerates caramel). Working quickly (it will harden fast), scrape mixture onto prepared baking sheet and spread into a thin layer. Let cool completely, 5–10 minutes. Chop into pea-size pieces; set aside.'
},
{
'@type': 'HowToStep',
text: 'Place half of butter (½ cup) in the bowl of a stand mixer. Bring remaining butter to a boil in a small saucepan over medium-low heat, stirring often with a heatproof rubber spatula. Cook, scraping bottom and sides of pan constantly, until butter sputters, foams, and, eventually, you see browned bits floating on the surface, 5–7 minutes. Pour brown butter over butter in stand mixer bowl, making sure to scrape in all the browned bits. Let sit until butter begins to resolidify, about 30 minutes.'
},
{
'@type': 'HowToStep',
text: 'Pulse flour, salt, and baking soda in a food processor to combine. Add half of reserved pecan brittle and 1 cup oats; process in long pulses until oats and brittle are finely ground.'
},
{
'@type': 'HowToStep',
text: 'Add brown sugar and granulated sugar to butter and beat with paddle attachment on medium speed until light and smooth but not fluffy, about 2 minutes. Scrape down sides of bowl and add eggs and vanilla. Beat until very light and satiny, about 1 minute. Scrape down sides of bowl and add flour mixture; beat on low speed until no dry spots remain and you have a soft, evenly mixed dough. Add remaining half of brittle and remaining 1 cup oats; mix on low speed just to distribute. Fold batter several times with a spatula to ensure everything is evenly mixed.'
},
{
'@type': 'HowToStep',
text: 'Using a 2-oz. scoop or ¼-cup measuring cup, scoop level portions of dough to make 18 cookies. Place on a parchment-lined baking sheet, spacing as close together as possible (you’ll space them out before baking). Cover tightly with plastic wrap and chill at least 12 hours and up to 2 days. (If you’re pressed for time, a couple hours will do; cookies just won’t be as chewy.)'
},
{
'@type': 'HowToStep',
text: 'When ready to bake, place racks in upper and lower thirds of oven; preheat to 350°. Line 2 large rimmed baking sheets with parchment paper. Arrange 6 cookies on each prepared baking sheet, spacing at least 3" apart.'
},
{
'@type': 'HowToStep',
text: 'Bake cookies, rotating baking sheets top to bottom and front to back after 12 minutes, until dark golden brown around the edges, 16–20 minutes. Let cookies cool 5 minutes on baking sheets, then transfer cookies to a wire rack with a spatula and let cool completely.'
},
{
'@type': 'HowToStep',
text: 'Carefully move a rack to middle of oven. Arrange remaining dough on one of the baking sheets (it’s okay if it’s still warm). Bake as before (this batch might go a bit faster).\nDo ahead: Dough can be formed 2 months ahead; chill dough balls at least 2 hours before transferring to freezer. Once frozen solid, store in resealable plastic freezer bags and keep frozen. No need to thaw before baking, but you may need to add a minute or two to the baking time. Cookies can be baked 5 days ahead; store airtight at room temperature.'
}
],
slug: 'oat-and-pecan-brittle-cookies',
tags: [],
categories: [],
dateAdded: ISODate('2020-12-07T05:55:35.434Z'),
notes: [],
orgURL: 'https://www.bonappetit.com/recipe/oat-and-pecan-brittle-cookies',
rating: 3
}
```

4
docs/docs/documentation/toolbox/bulk-organize.md Normal file
View file

@ -0,0 +1,4 @@
# Bulk Organize
The 'Organize' tab can be used to show all of the items that do not have any category or tag assigned.
![Toolbox-Organize](../../assets/img/Toolbox-Organize.webp)

5
docs/docs/documentation/toolbox/category-tag-editor.md Normal file
View file

@ -0,0 +1,5 @@
# Category and Tag Editor
The 'Categories' and 'Tags' tab give you the option to bulk assign categories and tags to multiple recipes. You could also remove the unused ones or title case them all.
![Toolbox-Categories](../../assets/img/Toolbox-Categories.webp)

59
docs/docs/documentation/toolbox/notifications.md Normal file
View file

@ -0,0 +1,59 @@
# Getting External Notifications
## Apprise
Using the [Apprise](https://github.com/caronc/apprise/) library Mealie is able to provided notification services for nearly every popular service. Some of our favorites are...
- [Gotify](https://github.com/caronc/apprise/wiki/Notify_gotify)
- [Discord](https://github.com/caronc/apprise/wiki/Notify_discord)
- [Home Assistant](https://github.com/caronc/apprise/wiki/Notify_homeassistant)
- [Matrix](https://github.com/caronc/apprise/wiki/Notify_matrix)
- [Pushover](https://github.com/caronc/apprise/wiki/Notify_pushover)
But there are some many to choose from! Take a look at their wiki for information on how to create their URL formats and that you can use to create a notification integration in Mealie.
## Subscribe Events
There are several categories of events that mealie logs that can be broadcast with the notifications feature. You can also see a feed of your events in the Admin Dashboard
- General Events
- Application Startup
- Recipe Events
- Create Recipe
- Delete Recipe
- Database Events
- Export/Import
- Database Initialization
- Scheduled Events
- MealPlan Webhooks Sent
- Group Events
- Create/Delete Groups
- User Events
- User Creation
- User Sign-up
- Sign-up Token Creation
- Invalid login attempts
In most cases the events will also provide details on which user performed the action. Now you'll know when your grandma deletes your favorite recipe!
!!! info
This is a new feature and we are still working through all the possibilities of events. if you have an idea for an event let us know!
## Creating a New Notification
New events can be created and viewed in admin Toolbox `/admin/toolbox?tab=event-notifications`. Select the "+ Notification" button and you'll be provided with a dialog. Complete the form using the URL for the service you'd like to connect to. Before saving be sure to use the test feature.
!!! tip
The feedback provided from the test feature is only an indicated of if the URL you provided is valid, not if the message was successfully sent. Be sure to check the notification feed for the test message.
![Add Notification Image](../../assets/img/add-notification.webp)
## Examples
### Discord
![Discord](../../assets/img/discord-notification-example.webp)
### Gotify
![Gotify](../../assets/img/gotify-notification-example.webp)

13
docs/docs/documentation/users-groups/meal-planner.md Normal file
View file

@ -0,0 +1,13 @@
# Meal Planner
## Working with Meal Plans
In Mealie you can create a meal plan based off the calendar inputs on the meal planner page. There is no limit to how long or how short a meal plan is. You may also create duplicate meal plans for the same date range. After selecting your date range, click on the card for each day and search through recipes to find your choice. After selecting a recipe for all meals save the plan. You can also randomly generate meal plans.
To edit the meal in a meal plan simply select the edit button on the card in the timeline. Similarly, to delete a meal plan click the delete button on the card in the timeline. Currently there is no support to change the date range in a meal plan.
## Shopping Lists
For any meal plan created you can view a breakdown of all the ingredients and use an experimental sort function to sort similarly ingredients. This is a very new feature and results of the auto sort may vary.
![](../../assets/gifs/meal-plan-demo-v2.gif)

1
docs/docs/documentation/users-groups/shopping-lists.md Normal file
View file

@ -0,0 +1 @@
# Shopping Lists

25
docs/docs/documentation/users-groups/user-settings.md Normal file
View file

@ -0,0 +1,25 @@
# User Settings
A user will be able to access 3 sections in their admin panel. The user profile, themes, group/meal-plan settings section.
## Profile Settings
In as users profile they are able to
- Change Display Name
- Change Email
- Update Password
- View Their Group
- Upgrade Profile Picture (Experimental)
## Themes
Color themes can be created and set from the UI in the users settings page. You can select an existing color theme or create a new one. On creation of a new color theme, the default colors will be used, then you can select and save as you'd like. By default the "default" theme will be loaded for all new users visiting the site. All created color themes are available to all users of the site. Theme Colors will be set for both light and dark modes.
![](../../assets/gifs/theme-demo-v2.gif)
!!! tip
Theme data is stored in local storage in the browser. Calling "Save colors and apply theme will refresh the local storage with the selected theme as well save the theme to the database.
## Group & Meal Plan
In the meal planner section a user can select categories to be used as apart of the random recipe selector in the meal plan creator. If no categories are selected, all recipes will be used
Meal planner webhooks are post requests sent from Mealie to an external endpoint. The body of the message is the Recipe JSON of the scheduled meal. If no meal is schedule, no request is sent. The webhook functionality can be enabled or disabled as well as scheduled. Note that you must "Save" prior to any changes taking affect server side.