diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index d994cbd7961..114aa16bdab 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -2,6 +2,15 @@ This template provides some ideas of things to include in your PR description. To start, try providing a short summary of your changes in the Title above. If a section of the PR template does not apply to this PR, then delete that section. + + PLEASE READ: + ------------------------- + Mealie is moving to a regular, automatic release schedule. This means that all PRs should be in a + stable state, ready for release. This includes: + + - Ensuring new tests have been added to cover new features, or to prevent regressions. + - Work is fully complete and usable + --> ## What type of PR is this? @@ -56,17 +65,3 @@ _(fill-in or delete this section)_ - -## Release Notes - -_(REQUIRED)_ - - -```release-note -``` diff --git a/MAINTAINERS.md b/MAINTAINERS.md new file mode 100644 index 00000000000..21c8424a234 --- /dev/null +++ b/MAINTAINERS.md @@ -0,0 +1,3 @@ +# Maintainers Guide + +See -> ./docs/docs/contributors/developers-guide/maintainers.md diff --git a/docs/docs/contributors/developers-guide/maintainers.md b/docs/docs/contributors/developers-guide/maintainers.md new file mode 100644 index 00000000000..f62c940848a --- /dev/null +++ b/docs/docs/contributors/developers-guide/maintainers.md @@ -0,0 +1,57 @@ +# Maintainers Guide + +This is the start of the maintainers guide for Mealie developers. Those who have been invited to the GitHub organization and/or those who whish to play a bigger part in the Mealie developers community may find this helpful. + +## Managing Issues + +If you are working on issues, it can be helpful to understand the workflow for our repository. When an issue comes in it is tagged with the `bug` and `triage` flags. This is to indicate that they need to be reviewed by a maintainer to determine validity. + +After you've reviered an issue it will generally move into one of two states: + +`bug:confirmed` +: Your were able to verify the issue and we determined we need to fix it + + +`needs more info` +: The orignal post does not contain enough information, and if the reporter does not provide additional information, the issue will be automatically closed. + +Once you've reviewed an issue and moved it into another category, you should remove the triage label. + +### While going through issues try to keep the following in mind + +- It is perfectly okay to ignore an issue if it is low quality +- You should close any issues that ignore the standard report template and request they reopen the issue using the proper template +- You should **not** try to reproduce issues that don't have clear reproduction steps, don't have a version provided, or are generally unclear. +- Issues that are not bugs, should likely be converted to discussions. + +## Drafting Releases + +### Tags + +Mealie is published via GitHub actions to the GitHub container registry with the follow tags: + +`ghcr.io/mealie-recipes/mealie:nightly` +: published with every push to `mealie-next` branch - [Actions File](https://github.com/mealie-recipes/mealie/blob/mealie-next/.github/workflows/nightly.yml) + +`ghcr.io/mealie-recipes/mealie:latest` +: published when a new GitHub Release is created - [Actions File](https://github.com/mealie-recipes/mealie/blob/mealie-next/.github/workflows/release.yml) + +`ghcr.io/mealie-recipes/mealie:{version}` +: published when a new GitHub Release is created - [Actions File](https://github.com/mealie-recipes/mealie/blob/mealie-next/.github/workflows/release.yml) + +!!! note + Both the latest, and {version} tags will be the same container on the release of a new version + +### Process + +Because we've built all our publishing effors on GitHub Actions we rely primarily on automations to perform our releases. As such creating a new build of Mealie is as simple as creating a new GitHub release. Here are the general steps we take to create a new release + +1. Navigate to the [Github Release Page](https://github.com/mealie-recipes/mealie/releases) and click the 'Draft a new release' button. +2. Choose a tag and increment the version according to the semver specification. i.e, **major** version for breaking changes, **minor** for feature updates, and **patch** for bug fixes. +3. Name the Release, usually just the tag is fine, however if there is a special feature you'd like to higlight this would be a great place to do it. +4. Click the "Generate release notes" button which will pull in all the Git Commits as a changelog. For bug fix only releases this is sufficient, however if there are major features, or good quality of life improvements it's good to provide those prior to listing the full changelog. + +!!! tip + Don't worry about setting the version number in the container or code, it's set during the build process and uses the tag you specified when drafting a new release. + + You can see how this is done in the [Actions File](https://github.com/mealie-recipes/mealie/blob/mealie-next/.github/workflows/partial-builder.yml#L35-L37) diff --git a/docs/docs/documentation/getting-started/installation/advanced.md b/docs/docs/documentation/getting-started/installation/advanced.md deleted file mode 100644 index 3c1c4d2d632..00000000000 --- a/docs/docs/documentation/getting-started/installation/advanced.md +++ /dev/null @@ -1,70 +0,0 @@ -# Advanced Installation - -!!! 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. - -[workers_per_core]: https://github.com/tiangolo/uvicorn-gunicorn-docker/blob/2daa3e3873c837d5781feb4ff6a40a89f791f81b/README.md#workers_per_core -[max_workers]: https://github.com/tiangolo/uvicorn-gunicorn-docker/blob/2daa3e3873c837d5781feb4ff6a40a89f791f81b/README.md#max_workers -[web_concurrency]: https://github.com/tiangolo/uvicorn-gunicorn-docker/blob/2daa3e3873c837d5781feb4ff6a40a89f791f81b/README.md#web_concurrency diff --git a/docs/docs/documentation/getting-started/installation/installation-checklist.md b/docs/docs/documentation/getting-started/installation/installation-checklist.md index a6f7b1e0bff..91f8328fcd6 100644 --- a/docs/docs/documentation/getting-started/installation/installation-checklist.md +++ b/docs/docs/documentation/getting-started/installation/installation-checklist.md @@ -3,6 +3,7 @@ To install Mealie on your server there are a few steps for proper configuration. Let's go through them. !!! tip TLDR + Don't need step by step? Checkout the - [SQLite docker-compose](./sqlite.md) @@ -22,22 +23,23 @@ To deploy mealie on your local network it is highly recommended to use docker to - linux/amd64 - linux/arm64 - !!! warning "32bit Support" + Due to a build dependency limitation, Mealie is not supported on 32bit ARM systems. If you're running into this limitation on a newer Raspberry Pi, please consider upgrading to a 64bit operating system on the Raspberry Pi. ## Migrating From Other V1 Versions -We've gone through a few versions of Mealie v1 deployment targets. We have settled on a single container deployment and we've begun publishing the nightly container on github containers. If you're looking to move from the old nightly (split containers *or* the omni image) to the new nightly, there are a few things you need to do: +We've gone through a few versions of Mealie v1 deployment targets. We have settled on a single container deployment and we've begun publishing the nightly container on github containers. If you're looking to move from the old nightly (split containers _or_ the omni image) to the new nightly, there are a few things you need to do: 1. Take a backup just in case! -2. Replace the image for the API container with `ghcr.io/mealie-recipes/mealie:nightly` +2. Replace the image for the API container with `ghcr.io/mealie-recipes/mealie:v1.0.0-RC1.1` 3. Take the external port from the frontend container and set that as the port mapped to port `9000` on the new container. The frontend is now served on port 9000 from the new container, so it will need to be mapped for you to have access. 4. Restart the container For an example of what these changes look like, see the new [SQLite](./sqlite.md) or [PostgreSQL](./postgres.md) docker-compose examples. The container swap should be seemless, at least that's our hope! ## 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. 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. @@ -51,15 +53,14 @@ You can find the relevant ready to use docker-compose files for supported instal The following steps were tested on a Ubuntu 20.04 server, but should work for most other Linux distributions. These steps are not required, but is how I generally will setup services on my server. - 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` (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. @@ -68,6 +69,7 @@ After you've decided setup the files it's important to set a few ENV variables t - [x] You've set the `DEFAULT_EMAIL` and `DEFAULT_GROUP` variable. ## Step 3: Startup + After you've configured your database, and updated the `docker-compose.yaml` files, you can start Mealie by running the following command in the directory where you've added your `docker-compose.yaml`. ```bash @@ -91,6 +93,7 @@ You should see the containers start up without error. You should now be able to After the startup is complete you should see a login screen. Use the default credentials above to login and navigate to `/admin/site-settings`. Here you'll find a summary of your configuration details and their respective status. Before proceeding you should validate that the configuration is correct. For any warnings or errors the page will display an error and notify you of what you need to verify. ## Step 5: Backup + While v1.0.0 is a great step to data-stability and security, it's not a backup. Mealie provides a full site data backup mechanism through the UI. These backups are just plain .zip files that you can download from the UI or access via the mounted volume on your system. For complete data protection you MUST store these backups somewhere safe, and outside of the server where they are deployed. @@ -99,10 +102,22 @@ These backups are just plain .zip files that you can download from the UI or acc ### Docker Tags +See all available tags on [GitHub](https://github.com/mealie-recipes/mealie/pkgs/container/mealie). We do not currently publish new images to Dockerhub. + `ghcr.io/mealie-recipes/mealie:nightly` The nightly build are the latest and greatest builds that are built directly off of every commit to the `mealie-next` branch and as such may contain bugs. These are great to help the community catch bugs before they hit the stable release or if you like living on the edge. +`ghrc.io/mealie-recipes/mealie:` + +We also provide versioned containers that allow to pin to a specific release. Each time a new release is built a new tag will be pushed with the version. These are great to pin to a specific version and allows you to have absolute control on when you upgrade your container. + +`ghrc.io/mealie-recipes/mealie:latest` + +_Note: This tag is not yet available, it will be available with the v1 stable release_ + +The latest tag provides the latest released image of Mealie. + --- **These tags no are long updated** diff --git a/docs/docs/documentation/getting-started/installation/postgres.md b/docs/docs/documentation/getting-started/installation/postgres.md index 418d21034af..fa88e8b6c91 100644 --- a/docs/docs/documentation/getting-started/installation/postgres.md +++ b/docs/docs/documentation/getting-started/installation/postgres.md @@ -11,7 +11,7 @@ PostgreSQL might be considered if you need to support many concurrent users. In version: "3.7" services: mealie: - image: ghcr.io/mealie-recipes/mealie:nightly + image: ghcr.io/mealie-recipes/mealie:v1.0.0-RC1.1 container_name: mealie ports: - "9925:9000" diff --git a/docs/docs/documentation/getting-started/installation/sqlite.md b/docs/docs/documentation/getting-started/installation/sqlite.md index bb069a8f33b..5b63f963414 100644 --- a/docs/docs/documentation/getting-started/installation/sqlite.md +++ b/docs/docs/documentation/getting-started/installation/sqlite.md @@ -11,7 +11,7 @@ SQLite is a popular, open source, self-contained, zero-configuration database th version: "3.7" services: mealie: - image: ghcr.io/mealie-recipes/mealie:nightly + image: ghcr.io/mealie-recipes/mealie:v1.0.0-RC1.1 container_name: mealie ports: - "9925:9000" # (1) diff --git a/docs/docs/documentation/getting-started/introduction.md b/docs/docs/documentation/getting-started/introduction.md index 479403a0b97..a3091b6e55e 100644 --- a/docs/docs/documentation/getting-started/introduction.md +++ b/docs/docs/documentation/getting-started/introduction.md @@ -1,17 +1,17 @@ # About The Project !!! warning "Mealie v1 Beta Release" + This documentation is for the Mealie v1 Beta release and is not final. As such, it may contain incomplete or incorrect information. You should understand that installing Mealie v1 Beta is a work in progress and while we've committed to maintaining the database schema and provided migrations, we are still in the process of adding new features, and robust testing to ensure the application works as expected. You should likely find bugs, errors, and unfinished pages within the application. To find the current status of the release you can checkout the [project on github](https://github.com/hay-kot/mealie/projects/7) or reach out on discord. - 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) - ## Key Features + - 🔍 Smart search, mix & match of "quoted literal searches" and keyword search. Fuzzy search ("is it brocolli or broccoli?") is also available when using a Postgres database. - 🏷️ Tag recipes with categories or tags for flexible sorting - 🕸 Import recipes from around the web by URL @@ -20,32 +20,35 @@ Mealie is a self hosted recipe manager and meal planner with a RestAPI backend a - 🛒 Generate shopping lists - 🐳 Easy setup with Docker - 🎨 Customize your interface with color themed 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 + - 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 + - Copy Me That + - Paprika + - Tandoor Recipes + - Random meal plan generation + - Advanced rule configuration to fine tune random recipes ## FAQ -See the [Frequently Asked Questions page](./faq.md) +See the [Frequently Asked Questions page](./faq.md) ## Built With -* [Vue.js](https://vuejs.org/) -* [Vuetify](https://vuetifyjs.com/en/) -* [FastAPI](https://fastapi.tiangolo.com/) -* [Docker](https://www.docker.com/) - +- [Vue.js](https://vuejs.org/) +- [Vuetify](https://vuetifyjs.com/en/) +- [FastAPI](https://fastapi.tiangolo.com/) +- [Docker](https://www.docker.com/) + ## Contributing Contributions are what make the open source community such an amazing place to learn, develop, and create. Any contributions you make are **greatly appreciated**. See the [Contributors Guide](../../contributors/non-coders.md) for help getting started. diff --git a/docs/docs/overrides/api.html b/docs/docs/overrides/api.html index 806093125af..24abea5c24c 100644 --- a/docs/docs/overrides/api.html +++ b/docs/docs/overrides/api.html @@ -14,7 +14,7 @@
diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 0a514679a0b..28194174b13 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -65,7 +65,6 @@ nav: - FAQ: "documentation/getting-started/faq.md" - API: "documentation/getting-started/api-usage.md" - Road Map: "documentation/getting-started/roadmap.md" - - Advanced: "documentation/getting-started/installation/advanced.md" - Installation: - Installation Checklist: "documentation/getting-started/installation/installation-checklist.md" @@ -91,6 +90,7 @@ nav: - Developers Guide: - Code Contributions: "contributors/developers-guide/code-contributions.md" - Dev Getting Started: "contributors/developers-guide/starting-dev-server.md" + - Maintainers Guide: "contributors/developers-guide/maintainers.md" - Guides: - Improving Ingredient Parser: "contributors/guides/ingredient-parser.md"