diff --git a/docs/docs/changelog/v1.0.0beta-5.md b/docs/docs/changelog/v1.0.0beta-5.md index c167ac1a878d..2f25e08bf2b4 100644 --- a/docs/docs/changelog/v1.0.0beta-5.md +++ b/docs/docs/changelog/v1.0.0beta-5.md @@ -1,3 +1,3 @@ -## NOTICE: +### NOTICE: Release changelogs are now published on github releases. This file is kept for historical purposes. diff --git a/docs/docs/contributors/developers-guide/code-contributions.md b/docs/docs/contributors/developers-guide/code-contributions.md index 13a84850a5ea..8ac41aaa700a 100644 --- a/docs/docs/contributors/developers-guide/code-contributions.md +++ b/docs/docs/contributors/developers-guide/code-contributions.md @@ -6,15 +6,16 @@ We use github to host code, to track issues and feature requests, as well as accept pull requests. ## We Use [Github Flow](https://guides.github.com/introduction/flow/index.html), So All Code Changes Happen Through Pull Requests -Pull requests are the best way to propose changes to the codebase (we use [Github Flow](https://guides.github.com/introduction/flow/index.html)). We actively welcome your pull requests: +Pull requests are the best way to propose changes to the codebase (we use [Github Flow](https://guides.github.com/introduction/flow/index.html)). We actively welcome your pull requests: -1. Fork the repo and create your branch from `dev`. +1. Fork the repo and create your branch from `mealie-next`. 2. Checkout the Discord, the PRs page, or the Projects page to get an idea of what's already being worked on. -3. If you're interested on working on major changes please get in touch on discord and coordinate with other developers. No sense in doubling up on work if someones already on it. +3. If you're interested on working on major changes please get in touch on discord and coordinate with other developers. No sense in doubling up on work if someones already on it. 4. Once you've got an idea of what changes you want to make, create a draft PR as soon as you can to let us know what you're working on and how we can help! 5. If you've changed APIs, update the documentation. -6. Issue that pull request! -7. If you make changes to the dev branch reflect those changes in the active changelog to keep track of changes. Don't forget to add your name/handle/identifier! +6. Run tests, including `make backend-all`. Note that the tests do not clean up after themselves and leave things in the database. So be sure to also run `make clean-data` and/or `make backend-clean` inbetween major testing rounds to be sure that you aren't testing on old data. +6. Issue that pull request! First make a draft PR, make sure that the automated github tests all pass, then mark as ready for review. +7. Be sure to add release notes to the pull request. ## Any contributions you make will be under the AGPL Software License In short, when you submit code changes, your submissions are understood to be under the same [AGPL License](https://choosealicense.com/licenses/agpl-3.0/) that covers the project. Feel free to contact the maintainers if that's a concern. diff --git a/docs/docs/contributors/developers-guide/starting-dev-server.md b/docs/docs/contributors/developers-guide/starting-dev-server.md index d809f4c0d922..6a20f2976e93 100644 --- a/docs/docs/contributors/developers-guide/starting-dev-server.md +++ b/docs/docs/contributors/developers-guide/starting-dev-server.md @@ -15,7 +15,7 @@ Prerequisites First ensure that docker is running. Then when you clone the repo and open with VS Code you should see a popup asking you to reopen the project inside a development container. Click yes and it will build the development container and run the setup required to run both the backend API and the frontend webserver. This also pre-configures pre-commit hooks to ensure that the code is up to date before committing. -Checkout the makefile for all of the available commands. +[Checkout the makefile reference](#make-file-reference) for all of the available commands. !!! tip For slow terminal checkout the solution in this [GitHub Issue](https://github.com/microsoft/vscode/issues/133215) @@ -62,9 +62,13 @@ Once the prerequisites are installed you can cd into the project base directory Before you start the server you MUST copy the `template.env` and `frontend/template.env` files to their respective locations with the name `.env` and `frontend/.env` respectively. The application will-not run without these files. -### Starting The Server +## Postgres +- Whether using a container or manual install, you need to set up your own postgres dev server. The database, username, password, etc should match the `POSTGRES_*` options located in the `.env` file. +- Install psycog2 with `poetry install -E pgsql` (in the main `mealie` directory, *not* `frontend`) -Once that is complete you're ready to start the servers. You'll need two shells open, One for the server and one for the frontend. +## Starting The Server + +Now you're ready to start the servers. You'll need two shells open, One for the server and one for the frontend. === "Linux / macOS" diff --git a/docs/docs/documentation/community-guide/ios.md b/docs/docs/documentation/community-guide/ios.md index 4f21943e07b7..8acaa2e025ff 100644 --- a/docs/docs/documentation/community-guide/ios.md +++ b/docs/docs/documentation/community-guide/ios.md @@ -5,7 +5,7 @@ ![Image from apple site](https://help.apple.com/assets/5E8CEA35094622DF10489984/5E8CEA42094622DF1048998D/en_US/ed1f9c157cdefc13e0161e0f70015455.png) -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. +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 original method broke after the transition to version 1.X and an issue was raised on [Github](https://github.com/hay-kot/mealie/issues/2092) GitHub user [Zippyy](https://github.com/zippyy) has helped to create a working shortcut for version 1.X. This is a useful utility for iOS users who browse for recipes in their web browser from their devices. @@ -21,20 +21,19 @@ This guide assumes that you already know how to [generate API tokens](https://ha First, click the [link](https://www.icloud.com/shortcuts/cc568d1615bc4f998789f85d1ef74846) and begin the setup of the shortcut. -![screenshot](/docs/docs/assets/img/sc1half.png) - +![screenshot](../../assets/img/sc1half.png) Next, you need to replace `url` and `port` with the information for your mealie instance. If you have a TLD that you use, put that here with no port. If you just run local, Then, you need to put in your mealie instance IP and the port of `9926`. -![screenshot](/docs/docs/assets/img/sc2half.png) +![screenshot](../../assets/img/sc2half.png) Finally, you need to replace the word `keyhere` with your API token. Keep the word `Bearer`!!! -![screenshot](/docs/docs/assets/img/sc3half.png) +![screenshot](../../assets/img/sc3half.png) You should now be able to share a website to the shortcut and have mealie grab all the necessary information! diff --git a/docs/docs/documentation/getting-started/api-usage.md b/docs/docs/documentation/getting-started/api-usage.md index 0930d33bcafb..c12464afd4f0 100644 --- a/docs/docs/documentation/getting-started/api-usage.md +++ b/docs/docs/documentation/getting-started/api-usage.md @@ -7,7 +7,7 @@ Mealie supports long-live api tokens in the user frontend. These can be created ## 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://demo.mealie.io/docs). +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:///docs` or see the example at the [Demo Site](https://demo.mealie.io/docs). ### Extras #### Recipe Extras diff --git a/docs/docs/documentation/getting-started/faq.md b/docs/docs/documentation/getting-started/faq.md index 0a34463251f0..7b1bf96a1178 100644 --- a/docs/docs/documentation/getting-started/faq.md +++ b/docs/docs/documentation/getting-started/faq.md @@ -1,35 +1,62 @@ # Frequently Asked Questions +## How do I enable "smart" ingredient handling? + +You might have noticed that scaling up a recipe or making a shopping list doesn't by default handle the ingredients in a way you might expect. Depending on your settings, scaling up might yield things like `2 1 cup broth` instead of `2 cup broth`. And making shopping lists from reciepes that have shared ingredients can yield multiple lines of the same ingredient. **But** mealie has a mechanism to intelligently handle ingredients and make your day better. How? +### Set up your Foods and Units +Do the following just **once**. Doing this applies to your whole group, so be careful. + +1. Click on your name in the upper left corner to get to your settings +2. In the bottom right, select `Manage Data` +3. In the Management page, make sure that a little orange button says `Foods` +4. If your Foods database is empty, click `Seed` and choose your language. You should end up with a list of foods. (Wait bit for seeding to happen, and try not to seed more than once or you will have duplicates) +5. Click the little orange `Foods` button and now choose `Units`. +6. Click `Seed` and choose your language. You should end up with a list of units (e.g. `tablespoon`) + +Initial seeding of Units is pretty complete, but there are many Foods in the world. You'll probably find that you need to add Foods to the database during parsing for the first several recipes. Once you have a well-populated Food database, there is are API routes to parse ingredients automatically in bulk. But this is not a good idea without a very complete set of Foods. + +### Set up Recipes to use Foods and Units +Do the following for each recipe you want to intelligently handle ingredients. + +1. Go to a recipe +2. Click the Edit button/icon +3. Click the Recipe Settings gear and deselect `Disable Ingredient Amounts` +4. Save +5. The ingredients should now look a little weird (`1 1 cup broth` and so on) +6. Click the Edit button/icon again +7. Scroll to the ingredients and you should see new fields for Amount, Unit, Food, and Note. The Note in particular will contain the original text of the Recipe. +8. Click `Parse` and you will be taken to the ingredient parsing page. +9. Choose your parser. the `Natural Language Parser` works very well, but you can also use the `Brute Parser`. +10. Click `Parse All` and your ingredients should be separated out into Units and Foods based on your seeding in Step 1 above. +11. For ingredients where the Unit or Food were not found, you can click a button to accept an automatically suggested Food to add to the database. Or manually enter the Unit/Food and hit `Enter` (or click `Create`) to add it to the database +12. When done, click `Save All` and you will be taken back to the recipe. Now the Unit and Food fields of the recipe should be filled out. + +Scaling up this recipe or adding it to a Shopping List will now smartly take care of ingredient amounts and duplicate combinations. + ## Is it Safe to Upgrade Mealie? Yes. If you are using the v1 branches (including beta), you can upgrade to the latest version of Mealie without performing a site Export/Restore. This process was required in previous versions of Mealie, however we've automated the database migration process to make it easier to upgrade. Not that if you were using the v0.5.x version, you CANNOT upgrade to the latest version automatically. You must follow the migration instructions in the documentation. -Links - - [Migration From v0.5.x](./migrating-to-mealie-v1.md) ## How can I change the theme? You can change the theme by settings the environment variables on the frontend container. -Links: - -- [Frontend Theme](./installation/frontend-config#themeing) +- [Frontend Theme](../installation/frontend-config#themeing) ## How can I change the language? Languages need to be set on the frontend and backend containers as ENV variables. -Links - -- [Frontend Config](./installation/frontend-config/) -- [Backend Config](./installation/backend-config/) +- [Frontend Config](../installation/frontend-config/) +- [Backend Config](../installation/backend-config/) ## How can I change the Login Session Timeout? Login session can be configured by setting the `TOKEN_TIME` variable on the backend container. -- [Backend Config](./installation/backend-config/) +- [Backend Config](../installation/backend-config/) ## Can I serve Mealie on a subpath? @@ -39,7 +66,7 @@ No. Due to limitations from the Javascript Framework, mealie doesn't support ser Yes, you can install Mealie on your local machine. HOWEVER, it is recommended that you don't. Managing non-system versions of python, node, and npm is a pain. Moreover updating and upgrading your system with this configuration is unsupported and will likely require manual interventions. If you insist on installing Mealie on your local machine, you can use the links below to help guide your path. -- [Advanced Installation](./installation/advanced/) +- [Advanced Installation](../installation/advanced/) ## How i can attach an image or video to a Recipe? @@ -97,3 +124,14 @@ stateDiagram-v2 p3 --> s1: Yes p3 --> n1: No ``` + +## 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. diff --git a/docs/docs/documentation/getting-started/features.md b/docs/docs/documentation/getting-started/features.md index f2174d3d295e..e2c98ae5b537 100644 --- a/docs/docs/documentation/getting-started/features.md +++ b/docs/docs/documentation/getting-started/features.md @@ -8,7 +8,7 @@ Mealie offers two main ways to create recipes. You can use the integrated recipe-scraper to create recipes from hundreds of websites, or you can create recipes manually using the recipe editor. -[Demo](https://demo.mealie.io/recipe/create/url){ .md-button .md-button--primary .align-right } +[Creation Demo](https://demo.mealie.io/recipe/create/url){ .md-button .md-button--primary .align-right } ### Importing Recipes @@ -22,7 +22,7 @@ Mealie supports importing recipes from a few other sources besides websites. Cur You can access these options on your installation at the `/group/migrations` page on your installation. If you'd like to see another source added, feel free to request so on Github. -[Demo](https://demo.mealie.io/group/data/foods){ .md-button .md-button--primary } +[Import Demo](https://demo.mealie.io/group/migrations){ .md-button .md-button--primary } ### Organizing Recipes @@ -34,13 +34,13 @@ Mealie has a robust and flexible recipe organization system with a few different Categories are the overarching organizer for recipes. You can assign as many categories as you'd like to a recipe, but we recommend that you try to limit the categories you assign to a recipe to one or two. This helps keep categories as focused as possible while still allowing you to find recipes that are related to each other. For example, you might assign a recipe to the category **Breakfast**, **Lunch**, **Dinner**, or **Side**. -[Demo](https://demo.mealie.io/recipes/categories){ .md-button .md-button--primary } +[Categories Demo](https://demo.mealie.io/recipes/categories){ .md-button .md-button--primary } #### Tags Tags, are nearly identical to categories in function but play a secondary role in some cases. As such, we recommend that you use tags freely to help you organize your recipes by more specific topics. For example, if a recipe can be frozen or is a great left-over meal, you could assign the tags **frozen** and **left-over** and easily filter for those at a later time. -[Demo](https://demo.mealie.io/recipes/tags){ .md-button .md-button--primary } +[Tags Demo](https://demo.mealie.io/recipes/tags){ .md-button .md-button--primary } #### Tools @@ -48,7 +48,7 @@ Tools, are another way that some users like to organize their recipes. If a reci Each of the above organizers can be filtered in searches, and have their own pages where you can view all the recipes that are associated with those organizers. -[Demo](https://demo.mealie.io/recipes/tools){ .md-button .md-button--primary } +[Tools Demo](https://demo.mealie.io/recipes/tools){ .md-button .md-button--primary } #### Cookbooks @@ -60,7 +60,7 @@ Mealie also has the concept of cookbooks. These can be created inside of a group - Pasta Sides: Recipes that have both the **Side** category and the **Pasta** tag - Dessert Breads: Recipes that have both the **Bread** category and the **Dessert** tag -[Demo](https://demo.mealie.io/group/cookbooks){ .md-button .md-button--primary } +[Cookbooks Demo](https://demo.mealie.io/group/cookbooks){ .md-button .md-button--primary } ## Meal Planning @@ -69,13 +69,13 @@ Mealie uses a calendar like view to help you plan your meals. It shows you the p !!! tip You can also add a "Note" type entry to your meal-plan when you want to include something that might not have a specific recipes. This is great for leftovers, or for ordering out. -[Demo](https://demo.mealie.io/group/mealplan/planner){ .md-button .md-button--primary } +[Mealplanner Demo](https://demo.mealie.io/group/mealplan/planner){ .md-button .md-button--primary } ### Planner Rules The meal planner has the concept of plan rules. These offer a flexible way to use your organizers to customize how a random recipe is inserted into your meal plan. You can set rules to restrict the pool of recipes based on the Tags and/or Categories of a recipe. Additionally, since meal plans have a Breakfast, Lunch, Dinner, and Snack labels you can specifically set a rule to be active for a **specific meal type** or even a **specific day of the week.** -[Demo](https://demo.mealie.io/group/mealplan/settings){ .md-button .md-button--primary } +[Planner Settings Demo](https://demo.mealie.io/group/mealplan/settings){ .md-button .md-button--primary } ## Shopping Lists @@ -85,7 +85,7 @@ The shopping lists feature is a great way to keep track of what you need to buy At this time there isn't a tight integration between meal-plans and shopping lists, however it's something we have planned for the future. -[Demo](https://demo.mealie.io/shopping-lists){ .md-button .md-button--primary } +[Shopping List Demo](https://demo.mealie.io/shopping-lists){ .md-button .md-button--primary } ## Data Management @@ -107,7 +107,7 @@ Managing a robust collection of recipes inevitable requires a lot of data. Meali - Merge Units into a single unit entry - Export as JSON -[Demo](https://demo.mealie.io/group/data/foods){ .md-button .md-button--primary } +[Data Management Demo](https://demo.mealie.io/group/data/foods){ .md-button .md-button--primary } ## Server Administration @@ -115,20 +115,20 @@ Managing a robust collection of recipes inevitable requires a lot of data. Meali The site settings page contains general information about your installation like the application version, some configuration details, and some utilities to help you confirm your installation is working as expected. For example, you can use the Email Configuration section to validate that your email credentials are setup correctly and that the email service is working as expected. Additionally, there is a docker-volume utility that will confirm your volumes are configured and shared correctly between the front and backend of the application. -[Demo](https://demo.mealie.io/admin/site-settings){ .md-button .md-button--primary } +[Settings Demo](https://demo.mealie.io/admin/site-settings){ .md-button .md-button--primary } ### Users and Group There is a small management area for users and groups that allows you to create, edit, and delete users and groups. -[Demo](https://demo.mealie.io/admin/manage/users){ .md-button .md-button--primary } +[Users Demo](https://demo.mealie.io/admin/manage/users){ .md-button .md-button--primary } ### Backups The backups page provides a full system backup of your installation including all assets and images related to recipes. These are archived into a zip file and stored on the server but can also be downloaded through the UI. Due to some issues in the past Mealie no longer performs automatic backups, **it is advised that during setup you also setup a backup strategy to ensure your data is not lost.** -[Demo](https://demo.mealie.io/admin/backups){ .md-button .md-button--primary } +[Backups Demo](https://demo.mealie.io/admin/backups){ .md-button .md-button--primary } !!! note diff --git a/docs/docs/documentation/getting-started/installation/installation-checklist.md b/docs/docs/documentation/getting-started/installation/installation-checklist.md index 9898b1b4f5d9..99e81baae2fd 100644 --- a/docs/docs/documentation/getting-started/installation/installation-checklist.md +++ b/docs/docs/documentation/getting-started/installation/installation-checklist.md @@ -7,6 +7,7 @@ To install Mealie on your server there are a few steps for proper configuration. - [SQLite docker-compose](./sqlite.md) - [Postgres docker-compose](./postgres.md) + - [Single container docker-compose](./single-container.md) ## Pre-work @@ -27,12 +28,15 @@ To deploy mealie on your local network it is highly recommended to use docker to ## Step 1: Deployment Type -SQLite is a popular, open source, self-contained, zero-configuration database that is the ideal choice for Mealie when you have 1-20 Users and your concurrent write operations will be some-what limited. If you need to support many concurrent users, you may want to consider a more robust database such as PostgreSQL. +SQLite is a popular, open source, self-contained, zero-configuration database that is the ideal choice for Mealie when you have 1-20 Users and your concurrent write operations will be some-what limited. + +PostgreSQL might be considered if you need to support many concurrent users. In addition, some features are only enabled on PostgreSQL, such as fuzzy search. You can find the relevant ready to use docker-compose files for supported installations at the links below. - [SQLite](./sqlite.md) - [PostgreSQL](./postgres.md) +- [Single container](./single-container.md) ## Step 2: Setting up your files. @@ -40,17 +44,17 @@ The following steps were tested on a Ubuntu 20.04 server, but should work for mo 1. SSH into your server and navigate to the home directory of the user you want to run Mealie as. If that is your current user, you can use `cd ~` to ensure you're in the right directory. -2. Create a directory called `docker` and navigate into it. `mkdir docker && cd docker` -3. Do the same for mealie `mkdir mealie && cd mealie` -4. Create a docker-compose.yaml file in the mealie directory. `touch docker-compose.yaml` -5. Use the text editor or your choice to edit the file and copy the contents of the docker-compose template for the deployment type you want to use. `nano docker-compose.yaml` or `vi docker-compose.yaml` +2. Create a directory called `docker` and navigate into it: `mkdir docker && cd docker` (this is optional, if you organizer your docker installs separate from everything else) +3. Do the same for mealie: `mkdir mealie && cd mealie` +4. Create a docker-compose.yaml file in the mealie directory: `touch docker-compose.yaml` +5. Use the text editor or your choice to edit the file and copy the contents of the docker-compose template for the deployment type you want to use: `nano docker-compose.yaml` or `vi docker-compose.yaml` ## Step 2: Customizing The `docker-compose.yaml` files. After you've decided setup the files it's important to set a few ENV variables to ensure that you can use all the features of Mealie. I recommend that you verify and check that: - [x] You've configured the relevant ENV variables for your database selection in the `docker-compose.yaml` files. -- [x] You've configured the [SMTP server settings](./backend-config.md#email) (used for invitations, password resets, etc) +- [x] You've configured the [SMTP server settings](./backend-config.md#email) (used for invitations, password resets, etc). You can setup a [google app password](https://support.google.com/accounts/answer/185833?hl=en) if you want to send email via gmail. - [x] Verified the port mapped on the `mealie-frontend` container is an open port on your server (Default: 9925) - [x] You've set the [`BASE_URL`](./backend-config.md#general) variable. - [x] You've set the `DEFAULT_EMAIL` and `DEFAULT_GROUP` variable. @@ -105,5 +109,5 @@ While the docker-compose file should work without modification, some users want In the diagram above there's a few crucial things to note. 1. Port 9925 is the host port, this can be anything you want. The important part is that it's mapped to the mealie-frontend container at port 3000. -2. The mealie-frontend container communicated with the mealie-api container through the INTERNAL docker network. This requires that the two containers are on the same network and that the network supports name resolution (anything but the default bridge network). The resolution URL can be specified in the docker-compose as the `API_URL` environment variable. +2. The mealie-frontend container communicated with the mealie-api container through the INTERNAL docker network. This requires that the two containers are on the same network and that the network supports name resolution (anything but the default bridge network). The resolution URL can be specified in the docker-compose as the `API_URL` environment variable. The API_URL must match the network name of the mealie-backend container, which should be the same as the container name (e.g. a container renamed to `my-api` should have an `API_URL` set to `http://my-api: - + Get started - + View the Demo @@ -251,10 +243,8 @@

- + Import Recipes

@@ -266,10 +256,8 @@

- + Automatic Backups

@@ -281,10 +269,8 @@

- + Rich User Interface

@@ -296,10 +282,8 @@

- + Meal Planner

@@ -312,10 +296,8 @@

- + Users

@@ -327,25 +309,21 @@

- + Groups

- Sort users into groups to share recipes with the whole family, but keep - your Meal Plans separate. + Sort users into groups to share recipes and mealplans with the whole family while keeping + your cooking club separate.

- + Webhooks

@@ -357,10 +335,8 @@

- + Open API

@@ -375,43 +351,28 @@