mirrors/recipes
1
0
Fork 0
mirror of https://github.com/TandoorRecipes/recipes.git synced 2025-12-23 18:29:23 -05:00
Code Issues Packages Projects Releases Wiki Activity

update documentation

Browse Source
This commit is contained in:
smilerz
2024-04-24 12:23:35 -05:00
parent e4ff6ed732
commit b83f3a291b
9 changed files with 128 additions and 82 deletions
Download Patch File Download Diff File Expand all files Collapse all files

40
docs/contribute/contribute.md
View File

@@ -1,8 +1,10 @@
If you like this application and want it to give back, there are many ways to contribute.
<!-- prettier-ignore-start -->
!!! success "Contribution List"
If you help bring this project forward you deserve to be credited for it.
Feel free to add yourself to `CONTRIBUTERS.md` or message me to add you if you have contributed anything.
If you help bring this project forward you deserve to be credited for it.
Feel free to add yourself to `CONTRIBUTERS.md` or message me to add you if you have contributed anything.
<!-- prettier-ignore-end -->
## Translations
@@ -11,23 +13,23 @@ Improve the translations for any of the existing languages.
Add a new language to the long list of existing translations.
- Armenian
- Bulgarian
- Catalan
- Czech
- Danish
- Dutch
- English
- French
- German
- Hungarian
- Italian
- Latvian
- Norwegian
- Polish
- Russian
- Spanish
- Swedish
- Armenian
- Bulgarian
- Catalan
- Czech
- Danish
- Dutch
- English
- French
- German
- Hungarian
- Italian
- Latvian
- Norwegian
- Polish
- Russian
- Spanish
- Swedish
See [here](/contribute/translations) for further information on how to contribute translation to Tandoor.

28
docs/contribute/guidelines.md
View File

@@ -1,10 +1,12 @@
If you want to contribute bug fixes or small tweaks then your pull requests are always welcome!
<!-- prettier-ignore-start -->
!!! danger "Discuss First!"
If you want to contribute larger features that introduce more complexity to the project please
make sure to **first submit a technical description** outlining what and how you want to do it.
This allows me and the community to give feedback and manage the complexity of the overall
application. If you don't do this please don't be mad if I reject your PR.
If you want to contribute larger features that introduce more complexity to the project please
make sure to **first submit a technical description** outlining what and how you want to do it.
This allows me and the community to give feedback and manage the complexity of the overall
application. If you don't do this please don't be mad if I reject your PR.
<!-- prettier-ignore-end -->
## License
@@ -20,23 +22,25 @@ To contribute to the project you are required to use the following packages with
- isort
- prettier
<!-- prettier-ignore -->
!!! tip "Manual Formatting"
It is possible to run formatting manually, but it is recommended to setup your IDE to format on save.
``` bash
flake8 file.py --ignore=E501 | isort -q file.py | yapf -i file.py
prettier --write file.vue
It is possible to run formatting manually, but it is recommended to setup your IDE to format on save.
``` bash
flake8 file.py --ignore=E501 | isort -q file.py | yapf -i file.py
prettier --write file.vue
```
## Testing
Django uses pytest-django to implement a full suite of testing. If you make any functional changes, please implment the appropriate
Django uses pytest-django to implement a full suite of testing. If you make any functional changes, please implment the appropriate
tests.
Tandoor is also actively soliciting contribors willing to setup vue3 testing. If you have knowledge in this area it would be greatly appreciated.
Tandoor is also actively soliciting contribors willing to setup vue3 testing. If you have knowledge in this area it would be greatly appreciated.
## API Client
Tandoor uses [django-rest-framework](https://www.django-rest-framework.org/) for API implementation. Making contributions that impact the API requires an understanding of
Viewsets and Serializers.
Tandoor uses [django-rest-framework](https://www.django-rest-framework.org/) for API implementation. Making contributions that impact the API requires an understanding of
Viewsets and Serializers.
Also double check that your changes are actively reflected in the schema so that client apis are generated accurately.

19
docs/contribute/installation.md
View File

@@ -1,5 +1,7 @@
!!! info
The dev setup is a little messy as this application combines the best (at least in my opinion) of both Django and Vue.js.
<!-- prettier-ignore-start -->
!!! info "Development Setup"
The dev setup is a little messy as this application combines the best (at least in my opinion) of both Django and Vue.js.
<!-- prettier-ignore-end -->
### Devcontainer Setup
@@ -30,10 +32,17 @@ populated from default values.
### Vue.js
<!-- prettier-ignore-start -->
!!! warning "Feature Freeze"
With the exception of bug fixes, no changes will be accepted on the legacy `vue` front-end.
<!-- prettier-ignore-end -->
Most new frontend pages are build using [Vue.js](https://vuejs.org/).
In order to work on these pages, you will have to install a Javascript package manager of your choice. The following examples use yarn.
In the `vue` folder run `yarn install` to install the dependencies. After that you can use `yarn serve` to start the development server,
and proceed to test your changes. If you do not wish to work on those pages, but instead want the application to work properly during
development, run `yarn build` to build the frontend pages once.
In the `vue` folder run `yarn install` followed by `yarn build` to install and build the legacy front-end.
In the `vue3` folder run `yarn install` followed by `yarn build` to install and build the new front-end.
After that you can use `yarn serve` from the `vue3` folder to start the development server, and proceed to test your changes.
If you do not wish to work on those pages, but instead want the application to work properly during development, run `yarn build` to build the frontend pages once.

7
docs/contribute/translations.md
View File

@@ -7,10 +7,11 @@ You can simply register an account and then follow these steps to add translatio
3. Select Tandoor and on the top-right hand corner, select `Watch project Tandoor` (click on `Not watching`).
4. Go back to the dashboard. It now shows you the relevant translations for your languages. Click on the pencil icon to get started.
<!-- prettier-ignore -->
!!! info "Creating a new language"
To create a new language you must first select Tandoor (the project) and then a component.
Here you will have the option to add the language. Afterwards you can also simply add it to the other components as well.
Once a new language is (partially) finished let me know on GitHub so I can add it to the language-switcher in Tandoor itself.
To create a new language you must first select Tandoor (the project) and then a component.
Here you will have the option to add the language. Afterwards you can also simply add it to the other components as well.
Once a new language is (partially) finished let me know on GitHub so I can add it to the language-switcher in Tandoor itself.
There is also [a lot of documentation](https://docs.weblate.org/en/latest/user/translating.html) available from Weblate directly.

14
docs/contribute/vscode.md
View File

@@ -27,19 +27,19 @@ VS Marketplace Link: https://marketplace.visualstudio.com/items?itemName=esbenp.
<!-- prettier-ignore -->
!!! hint
Adding a comma at the end of a list will trigger yapf to put each element of the list on a new line
Adding a comma at the end of a list will trigger yapf to put each element of the list on a new line
## VSCode Tasks
There are a number of built in tasks that are available. Here are a few of the key ones:
- `Setup Dev Server` - Runs all the prerequisite steps so that the dev server can be run inside VSCode.
- `Setup Tests` - Runs all prerequisites so tests can be run inside VSCode.
- `Setup Dev Server` - Runs all the prerequisite steps so that the dev server can be run inside VSCode.
- `Setup Tests` - Runs all prerequisites so tests can be run inside VSCode.
Once these are run, you should be able to run/debug a django server in VSCode as well as run/debug tests directly through VSCode.
There are also a few other tasks specified in case you have specific development needs:
- `Run Dev Server` - Runs a django development server not connected to VSCode.
- `Run all pytests` - Runs all the pytests outside of VSCode.
- `Yarn Serve` - Runs development Vue.js server not connected to VSCode. Useful if you want to make Vue changes and see them in realtime.
- `Serve Documentation` - Runs a documentation server. Useful if you want to see how changes to documentation show up.
- `Run Dev Server` - Runs a django development server not connected to VSCode.
- `Run all pytests` - Runs all the pytests outside of VSCode.
- `Yarn Serve` - Runs development Vue.js server not connected to VSCode. Useful if you want to make Vue changes and see them in realtime.
- `Serve Documentation` - Runs a documentation server. Useful if you want to see how changes to documentation show up.

36
docs/features/authentication.md
View File

@@ -1,18 +1,20 @@
Besides the normal django username and password authentication this application supports multiple
Besides the normal django username and password authentication this application supports multiple
methods of central account management and authentication.
## Allauth
[Django Allauth](https://django-allauth.readthedocs.io/en/latest/index.html) is an awesome project that
[Django Allauth](https://django-allauth.readthedocs.io/en/latest/index.html) is an awesome project that
allows you to use a [huge number](https://docs.allauth.org/en/latest/socialaccount/providers/index.html) of different
authentication providers.
They basically explain everything in their documentation, but the following is a short overview on how to get started.
<!-- prettier-ignore -->
!!! warning "Public Providers"
If you choose Google, Github or any other publicly available service as your authentication provider anyone
with an account on that site can create an account on your installation.
A new account does not have any permission but it is still **not recommended** to give public access to
your installation.
A new account does not have any permission but it is still **not recommended** to give public access to
your installation.
Choose a provider from the [list](https://docs.allauth.org/en/latest/socialaccount/providers/index.html) and install it using the environment variable `SOCIAL_PROVIDERS` as shown
in the example below.
@@ -23,29 +25,31 @@ When at least one social provider is set up, the social login sign in buttons sh
SOCIAL_PROVIDERS=allauth.socialaccount.providers.openid_connect,allauth.socialaccount.providers.nextcloud
```
<!-- prettier-ignore -->
!!! warning "Formatting"
The exact formatting is important so make sure to follow the steps explained here!
The exact formatting is important so make sure to follow the steps explained here!
### Configuration, via environment
Depending on your authentication provider you **might need** to configure it.
This needs to be done through the settings system. To make the system flexible (allow multiple providers) and to
Depending on your authentication provider you **might need** to configure it.
This needs to be done through the settings system. To make the system flexible (allow multiple providers) and to
not require another file to be mounted into the container the configuration ins done through a single
environment variable. The downside of this approach is that the configuration needs to be put into a single line
as environment files loaded by docker compose don't support multiple lines for a single variable.
The line data needs to either be in json or as Python dictionary syntax.
Take the example configuration from the allauth docs, fill in your settings and then inline the whole object
Take the example configuration from the allauth docs, fill in your settings and then inline the whole object
(you can use a service like [www.freeformatter.com](https://www.freeformatter.com/json-formatter.html) for formatting).
Assign it to the additional `SOCIALACCOUNT_PROVIDERS` variable.
The example below is for a generic OIDC provider with PKCE enabled. Most values need to be customized for your specifics!
```ini
SOCIALACCOUNT_PROVIDERS = "{ 'openid_connect': { 'OAUTH_PKCE_ENABLED': True, 'APPS': [ { 'provider_id': 'oidc', 'name': 'My-IDM', 'client_id': 'my_client_id', 'secret': 'my_client_secret', 'settings': { 'server_url': 'https://idm.example.com/oidc/recipes' } } ] } }"
```
<!-- prettier-ignore -->
!!! success "Improvements ?"
There are most likely ways to achieve the same goal but with a cleaner or simpler system.
If you know such a way feel free to let me know.
@@ -62,16 +66,19 @@ Use your superuser account to configure your authentication backend by opening t
Now the provider is configured and you should be able to sign up and sign in using the provider.
Use the superuser account to grant permissions to the newly created users, or enable default access via `SOCIAL_DEFAULT_ACCESS` & `SOCIAL_DEFAULT_GROUP`.
<!-- prettier-ignore -->
!!! info "WIP"
I do not have a ton of experience with using various single signon providers and also cannot test all of them.
If you have any Feedback or issues let me know.
### Third-party authentication example
Keycloak is a popular IAM solution and integration is straight forward thanks to Django Allauth. This example can also be used as reference for other third-party authentication solutions, as documented by Allauth.
At Keycloak, create a new client and assign a `Client-ID`, this client comes with a `Secret-Key`. Both values are required later on. Make sure to define the correct Redirection-URL for the service, for example `https://tandoor.example.com/*`. Depending on your Keycloak setup, you need to assign roles and groups to grant access to the service.
To enable Keycloak as a sign in option, set those variables to define the social provider and specify its configuration:
```ini
SOCIAL_PROVIDERS=allauth.socialaccount.providers.openid_connect
SOCIALACCOUNT_PROVIDERS='{"openid_connect":{"APPS":[{"provider_id":"keycloak","name":"Keycloak","client_id":"KEYCLOAK_CLIENT_ID","secret":"KEYCLOAK_CLIENT_SECRET","settings":{"server_url":"https://auth.example.org/realms/KEYCLOAK_REALM/.well-known/openid-configuration"}}]}}
@@ -81,7 +88,8 @@ SOCIALACCOUNT_PROVIDERS='{"openid_connect":{"APPS":[{"provider_id":"keycloak","n
You are now able to sign in using Keycloak after a restart of the service.
### Linking accounts
To link an account to an already existing normal user go to the settings page of the user and link it.
To link an account to an already existing normal user go to the settings page of the user and link it.
Here you can also unlink your account if you no longer want to use a social login method.
## LDAP
@@ -89,13 +97,16 @@ Here you can also unlink your account if you no longer want to use a social logi
LDAP authentication can be enabled in the `.env` file by setting `LDAP_AUTH=1`.
If set, users listed in the LDAP instance will be able to sign in without signing up.
These variables must be set to configure the connection to the LDAP instance:
```
AUTH_LDAP_SERVER_URI=ldap://ldap.example.org:389
AUTH_LDAP_BIND_DN=uid=admin,ou=users,dc=example,dc=org
AUTH_LDAP_BIND_PASSWORD=adminpassword
AUTH_LDAP_USER_SEARCH_BASE_DN=ou=users,dc=example,dc=org
```
Additional optional variables:
```
AUTH_LDAP_USER_SEARCH_FILTER_STR=(uid=%(user)s)
AUTH_LDAP_USER_ATTR_MAP={'first_name': 'givenName', 'last_name': 'sn', 'email': 'mail'}
@@ -107,11 +118,13 @@ AUTH_LDAP_TLS_CACERTFILE=/etc/ssl/certs/own-ca.pem
## External Authentication
<!-- prettier-ignore -->
!!! warning "Security Impact"
If you just set `REMOTE_USER_AUTH=1` without any additional configuration, _anybody_ can authenticate with _any_ username!
<!-- prettier-ignore -->
!!! Info "Community Contributed Tutorial"
This tutorial was provided by a community member. We are not able to provide any support! Please only use, if you know what you are doing!
This tutorial was provided by a community member. We are not able to provide any support! Please only use, if you know what you are doing!
In order use external authentication (i.e. using a proxy auth like Authelia, Authentik, etc.) you will need to:
@@ -121,6 +134,7 @@ In order use external authentication (i.e. using a proxy auth like Authelia, Aut
Using any of the examples above will automatically generate a configuration file inside a docker volume.
Use `docker volume inspect recipes_nginx` to find out where your volume is stored.
<!-- prettier-ignore -->
!!! warning "Configuration File Volume"
The nginx config volume is generated when the container is first run. You can change the volume to a bind mount in the
`docker-compose.yml`, but then you will need to manually create it. See section `Volumes vs Bind Mounts` below

14
docs/features/automation.md
View File

@@ -1,7 +1,8 @@
<!-- prettier-ignore -->
!!! warning
Automations are currently in a beta stage. They work pretty stable but if I encounter any
issues while working on them, I might change how they work breaking existing automations.
I will try to avoid this and am pretty confident it won't happen.
Automations are currently in a beta stage. They work pretty stable but if I encounter any
issues while working on them, I might change how they work breaking existing automations.
I will try to avoid this and am pretty confident it won't happen.
Automations allow Tandoor to automatically perform certain tasks, especially when importing recipes, that
would otherwise have to be done manually. Currently, the following automations are supported.
@@ -45,10 +46,11 @@ ChatGPT and similiar LLMs are also useful for creating RegEx patterns:
`ChatGPT please create a Regex expression in the format of re.sub(<parameter 2>, <parameter 3>, <description>, count=1)
that will change the string <example string here> into the string <desired result here>`
<!-- prettier-ignore -->
!!! info
In order to prevent denial of service attacks on the RegEx engine the number of replace automations
and the length of the inputs that are processed are limited. Those limits should never be reached
during normal usage.
In order to prevent denial of service attacks on the RegEx engine the number of replace automations
and the length of the inputs that are processed are limited. Those limits should never be reached
during normal usage.
## Instruction Replace, Title Replace, Food Replace & Unit Replace

2
docs/features/connectors.md
View File

@@ -1,3 +1,4 @@
<!-- prettier-ignore -->
!!! warning
Connectors are currently in a beta stage.
@@ -6,6 +7,7 @@
Connectors are a powerful add-on component to TandoorRecipes.
They allow for certain actions to be translated to api calls to external services.
<!-- prettier-ignore -->
!!! danger
In order for this application to push data to external providers it needs to store authentication information.
Please use read only/separate accounts or app passwords wherever possible.

50
docs/features/external_recipes.md
View File

@@ -1,6 +1,7 @@
The original intend of this application was to provide a search interface to my large collection of PDF scans of recipes.
This feature is now called External recipes.
<!-- prettier-ignore -->
!!! info
Internal recipes are stored in a structured manner inside the database. They can be displayed using the standardized
interface and support features like shopping lists, scaling and steps.
@@ -12,76 +13,87 @@ Lastly you will need to sync with the external path and import recipes you desir
## Storage
<!-- prettier-ignore -->
!!! danger
In order for this application to retrieve data from external providers it needs to store authentication information.
Please use read only/separate accounts or app passwords wherever possible.
There are better ways to do this but they are currently not implemented
A `Storage Backend` is a remote storage location where files are **read** from.
To add a new backend click on `username >> External Recipes >> Manage External Storage >> the + next to Storage Backend List`.
To add a new backend click on `username >> External Recipes >> Manage External Storage >> the + next to Storage Backend List`.
There click the plus button.
The basic configuration is the same for all providers.
The basic configuration is the same for all providers.
| Field | Value |
|----------|-------|
| Name | Your identifier for this storage source, can be everything you want. |
| Method | The desired method. |
| Field | Value |
| ------ | -------------------------------------------------------------------- |
| Name | Your identifier for this storage source, can be everything you want. |
| Method | The desired method. |
<!-- prettier-ignore -->
!!! success
Only the providers listed below are currently implemented. If you need anything else feel free to open
an issue or pull request.
### Local
<!-- prettier-ignore -->
!!! info
There is currently no way to upload files through the webinterface. This is a feature that might be added later.
The local provider does not need any configuration (username, password, token or URL).
For the monitor you will need to define a valid path on your host system. (Path)
The Path depends on your setup and can be both relative and absolute.
For the monitor you will need to define a valid path on your host system. (Path)
The Path depends on your setup and can be both relative and absolute.
<!-- prettier-ignore -->
!!! warning "Volume"
By default no data other than the mediafiles and the database is persisted. If you use the local provider
make sure to mount the path you choose to monitor to your host system in order to keep it persistent.
#### Docker
If you use docker the default directory is `/opt/recipes/`.
add
```
- ./externalfiles:/opt/recipes/externalfiles
```
to your docker-compose.yml file under the `web_recipes >> volumes` section. This will create a folder in your docker directory named `externalfiles` under which you could choose to store external pdfs (you could of course store them anywhere, just change `./externalfiles` to your preferred location).
save the docker-compose.yml and restart your docker container.
### Dropbox
| Field | Value |
|----------|-------|
| Username | Dropbox username |
| Token | Dropbox API Token. Can be found [here](https://dropbox.github.io/dropbox-api-v2-explorer/#auth_token/from_oauth1)|
| Field | Value |
| -------- | ----------------------------------------------------------------------------------------------------------------- |
| Username | Dropbox username |
| Token | Dropbox API Token. Can be found [here](https://dropbox.github.io/dropbox-api-v2-explorer/#auth_token/from_oauth1) |
### Nextcloud
<!-- prettier-ignore -->
!!! warning "Path"
It appears that the correct webdav path varies from installation to installation (for whatever reason).
In the Nextcloud webinterface click the `Settings` button in the bottom left corner, there your WebDav Url will be displayed.
| Field | Value |
|----------|-------|
| Username | Nextcloud username |
| Password | Nextcloud app password |
| Url | Nextcloud Server URL (e.g. `https://cloud.mydomain.com`) |
| Field | Value |
| -------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| Username | Nextcloud username |
| Password | Nextcloud app password |
| Url | Nextcloud Server URL (e.g. `https://cloud.mydomain.com`) |
| Path | (optional) webdav path (e.g. `/remote.php/dav/files/vabene1111`). If no path is supplied `/remote.php/dav/files/` plus your username will be used. |
## Adding External Recipes
To add a new path from your Storage backend to the sync list, go to `username >> External Recipes` and
To add a new path from your Storage backend to the sync list, go to `username >> External Recipes` and
select the storage backend you want to use.
Then enter the path you want to monitor starting at the storage root (e.g. `/Folder/RecipesFolder`, or `/opt/recipes/externalfiles' in the docker example above) and save it.
## Syncing Data
To sync the recipes app with the storage backends press `Sync now` under `username >> External Recipes`
## Discovered Recipes
All files found by the sync can be found under `Manage Data >> Discovered recipes`.
All files found by the sync can be found under `Manage Data >> Discovered recipes`.
There you can either import all at once without modifying them or import one by one, adding tags while importing.