Mirrors/mealie
1
0
Fork 0
mirror of https://github.com/mealie-recipes/mealie.git synced 2026-01-14 04:51:20 -05:00
Code Issues Packages Projects Releases Wiki 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
29 changed files with 104 additions and 78 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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