From b83f3a291b97b75eeb1bb98a147288cca9892f5f Mon Sep 17 00:00:00 2001 From: smilerz Date: Wed, 24 Apr 2024 12:23:35 -0500 Subject: [PATCH] update documentation --- docs/contribute/contribute.md | 40 +++++++++++++------------ docs/contribute/guidelines.md | 28 +++++++++-------- docs/contribute/installation.md | 19 ++++++++---- docs/contribute/translations.md | 7 +++-- docs/contribute/vscode.md | 14 ++++----- docs/features/authentication.md | 36 +++++++++++++++------- docs/features/automation.md | 14 +++++---- docs/features/connectors.md | 2 ++ docs/features/external_recipes.md | 50 +++++++++++++++++++------------ 9 files changed, 128 insertions(+), 82 deletions(-) diff --git a/docs/contribute/contribute.md b/docs/contribute/contribute.md index 26e6db4bc..2fdc87890 100644 --- a/docs/contribute/contribute.md +++ b/docs/contribute/contribute.md @@ -1,8 +1,10 @@ If you like this application and want it to give back, there are many ways to contribute. + !!! 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. + ## 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. diff --git a/docs/contribute/guidelines.md b/docs/contribute/guidelines.md index f1b3eea9e..aa3e20155 100644 --- a/docs/contribute/guidelines.md +++ b/docs/contribute/guidelines.md @@ -1,10 +1,12 @@ If you want to contribute bug fixes or small tweaks then your pull requests are always welcome! + !!! 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. + ## License @@ -20,23 +22,25 @@ To contribute to the project you are required to use the following packages with - isort - prettier + !!! 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. diff --git a/docs/contribute/installation.md b/docs/contribute/installation.md index 39eaba5a8..de6af376f 100644 --- a/docs/contribute/installation.md +++ b/docs/contribute/installation.md @@ -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. + +!!! 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. + ### Devcontainer Setup @@ -30,10 +32,17 @@ populated from default values. ### Vue.js + +!!! warning "Feature Freeze" + With the exception of bug fixes, no changes will be accepted on the legacy `vue` front-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. diff --git a/docs/contribute/translations.md b/docs/contribute/translations.md index cd8d451c2..db18a421d 100644 --- a/docs/contribute/translations.md +++ b/docs/contribute/translations.md @@ -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. + !!! 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. diff --git a/docs/contribute/vscode.md b/docs/contribute/vscode.md index ab938d0ed..bebdaffde 100644 --- a/docs/contribute/vscode.md +++ b/docs/contribute/vscode.md @@ -27,19 +27,19 @@ VS Marketplace Link: https://marketplace.visualstudio.com/items?itemName=esbenp. !!! 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. diff --git a/docs/features/authentication.md b/docs/features/authentication.md index 34a7970fb..65846f977 100644 --- a/docs/features/authentication.md +++ b/docs/features/authentication.md @@ -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. + !!! 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 ``` + !!! 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' } } ] } }" ``` + !!! 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`. + !!! 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 + !!! warning "Security Impact" If you just set `REMOTE_USER_AUTH=1` without any additional configuration, _anybody_ can authenticate with _any_ username! + !!! 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. + !!! 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 diff --git a/docs/features/automation.md b/docs/features/automation.md index 60a984c88..5c649d932 100644 --- a/docs/features/automation.md +++ b/docs/features/automation.md @@ -1,7 +1,8 @@ + !!! 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(, , , count=1) that will change the string into the string ` + !!! 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 diff --git a/docs/features/connectors.md b/docs/features/connectors.md index 1f9a1b9c2..672bdffc7 100644 --- a/docs/features/connectors.md +++ b/docs/features/connectors.md @@ -1,3 +1,4 @@ + !!! 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. + !!! 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. diff --git a/docs/features/external_recipes.md b/docs/features/external_recipes.md index 4d97904b5..3d377f20a 100644 --- a/docs/features/external_recipes.md +++ b/docs/features/external_recipes.md @@ -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. + !!! 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 + !!! 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. | + !!! success Only the providers listed below are currently implemented. If you need anything else feel free to open an issue or pull request. ### Local + !!! 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. + !!! 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 + !!! 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.