cgiacofei/TandoorRecipes
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

updated documentation for postgres upgrade

Browse Source 
installing pgbackup container
installing with DockSTARTer
This commit is contained in:
smilerz 2023-11-28 15:45:27 -06:00
parent 6af28e6fe5
commit 7f1eecddc4
No known key found for this signature in database
GPG Key ID: 39444C7606D47126
4 changed files with 123 additions and 29 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

54
docs/faq.md
View File

@ -1,5 +1,5 @@
There are several questions and issues that come up from time to time, here are some answers: There are several questions and issues that come up from time to time, here are some answers:
please note that the existence of some questions is due the application not being perfect in some parts. please note that the existence of some questions is due the application not being perfect in some parts.
Many of those shortcomings are planned to be fixed in future release but simply could not be addressed yet due to time limits. Many of those shortcomings are planned to be fixed in future release but simply could not be addressed yet due to time limits.
## Is there a Tandoor app? ## Is there a Tandoor app?
@ -15,7 +15,7 @@ Open Tandoor, click the `add Tandoor to the home screen` message that pops up at
### Desktop browsers ### Desktop browsers
#### Google Chrome #### Google Chrome
Open Tandoor, open the menu behind the three vertical dots at the top right, select `Install Tandoor Recipes...` Open Tandoor, open the menu behind the three vertical dots at the top right, select `Install Tandoor Recipes...`
#### Microsoft Edge #### Microsoft Edge
@ -32,6 +32,17 @@ If you just set up your Tandoor instance and you're having issues like;
then make sure you have set [all required headers](install/docker.md#required-headers) in your reverse proxy correctly. then make sure you have set [all required headers](install/docker.md#required-headers) in your reverse proxy correctly.
If that doesn't fix it, you can also refer to the appropriate sub section in the [reverse proxy documentation](install/docker.md#reverse-proxy) and verify your general webserver configuration. If that doesn't fix it, you can also refer to the appropriate sub section in the [reverse proxy documentation](install/docker.md#reverse-proxy) and verify your general webserver configuration.
### Required Headers
Navigate to `/system` and review the headers listed in the DEBUG section. At a minimum, if you are using a reverse proxy the headers must match the below conditions.
| Header | Requirement |
| :--- | ----: |
| HTTP_HOST:mydomain.tld | The host domain must match the url that you are using to open Tandoor. |
| HTTP_X_FORWARDED_HOST:mydomain.tld | The host domain must match the url that you are using to open Tandoor. |
| HTTP_X_FORWARDED_PROTO:http(s) | The protocol must match the url you are using to open Tandoor. There must be exactly one protocol listed. |
| HTTP_X_SCRIPT_NAME:/subfolder | If you are hosting Tandoor at a subfolder instead of a subdomain this header must exist. |
## Why am I getting CSRF Errors? ## Why am I getting CSRF Errors?
If you are getting CSRF Errors this is most likely due to a reverse proxy not passing the correct headers. If you are getting CSRF Errors this is most likely due to a reverse proxy not passing the correct headers.
@ -41,19 +52,22 @@ If you are using a plain ngix you might need `proxy_set_header Host $http_host;`
Further discussions can be found in this [Issue #518](https://github.com/vabene1111/recipes/issues/518) Further discussions can be found in this [Issue #518](https://github.com/vabene1111/recipes/issues/518)
## Why are images not loading? ## Why are images not loading?
If images are not loading this might be related to the same issue as the CSRF errors (see above). If images are not loading this might be related to the same issue as the CSRF errors (see above).
A discussion about that can be found at [Issue #452](https://github.com/vabene1111/recipes/issues/452) A discussion about that can be found at [Issue #452](https://github.com/vabene1111/recipes/issues/452)
The other common issue is that the recommended nginx container is removed from the deployment stack. The other common issue is that the recommended nginx container is removed from the deployment stack.
If removed, the nginx webserver needs to be replaced by something else that servers the /mediafiles/ directory or If removed, the nginx webserver needs to be replaced by something else that servers the /mediafiles/ directory or
`GUNICORN_MEDIA` needs to be enabled to allow media serving by the application container itself. `GUNICORN_MEDIA` needs to be enabled to allow media serving by the application container itself.
## Why am I getting an error stating database files are incompatible with server?
Your version of Postgres has been upgraded. See [Updating PostgreSQL](https://docs.tandoor.dev/system/updating/#postgresql)
## Why does the Text/Markdown preview look different than the final recipe? ## Why does the Text/Markdown preview look different than the final recipe?
Tandoor has always rendered the recipe instructions markdown on the server. This also allows tandoor to implement things like ingredient templating and scaling in text. Tandoor has always rendered the recipe instructions markdown on the server. This also allows tandoor to implement things like ingredient templating and scaling in text.
To make editing easier a markdown editor was added to the frontend with integrated preview as a temporary solution. Since the markdown editor uses a different To make editing easier a markdown editor was added to the frontend with integrated preview as a temporary solution. Since the markdown editor uses a different
specification than the server the preview is different to the final result. It is planned to improve this in the future. specification than the server the preview is different to the final result. It is planned to improve this in the future.
The markdown renderer follows this markdown specification https://daringfireball.net/projects/markdown/ The markdown renderer follows this markdown specification https://daringfireball.net/projects/markdown/
@ -66,18 +80,18 @@ To create a new user click on your name (top right corner) and select 'space set
It is not possible to create users through the admin because users must be assigned a default group and space. It is not possible to create users through the admin because users must be assigned a default group and space.
To change a user's space you need to go to the admin and select User Infos. To change a user's space you need to go to the admin and select User Infos.
If you use an external auth provider or proxy authentication make sure to specify a default group and space in the If you use an external auth provider or proxy authentication make sure to specify a default group and space in the
environment configuration. environment configuration.
## What are spaces? ## What are spaces?
Spaces are is a type of feature used to separate one installation of Tandoor into several parts. Spaces are is a type of feature used to separate one installation of Tandoor into several parts.
In technical terms it is a multi-tenant system. In technical terms it is a multi-tenant system.
You can compare a space to something like google drive or dropbox. You can compare a space to something like google drive or dropbox.
There is only one installation of the Dropbox system, but it handles multiple users without them noticing each other. There is only one installation of the Dropbox system, but it handles multiple users without them noticing each other.
For Tandoor that means all people that work together on one recipe collection can be in one space. For Tandoor that means all people that work together on one recipe collection can be in one space.
If you want to host the collection of your friends, family, or neighbor you can create a separate space for them (through the admin interface). If you want to host the collection of your friends, family, or neighbor you can create a separate space for them (through the admin interface).
Sharing between spaces is currently not possible but is planned for future releases. Sharing between spaces is currently not possible but is planned for future releases.
@ -90,7 +104,7 @@ To reset a lost password if access to the container is lost you need to:
3. run `python manage.py changepassword <username>` and follow the steps shown. 3. run `python manage.py changepassword <username>` and follow the steps shown.
## How can I add an admin user? ## How can I add an admin user?
To create a superuser you need to To create a superuser you need to
1. execute into the container using `docker-compose exec web_recipes sh` 1. execute into the container using `docker-compose exec web_recipes sh`
2. activate the virtual environment `source venv/bin/activate` 2. activate the virtual environment `source venv/bin/activate`
@ -98,11 +112,11 @@ To create a superuser you need to
## Why cant I get support for my manual setup? ## Why cant I get support for my manual setup?
Even tough I would love to help everyone get tandoor up and running I have only so much time Even tough I would love to help everyone get tandoor up and running I have only so much time
that I can spend on this project besides work, family and other life things. that I can spend on this project besides work, family and other life things.
Due to the countless problems that can occur when manually installing I simply do not have Due to the countless problems that can occur when manually installing I simply do not have
the time to help solving each one. the time to help solving each one.
You can install Tandoor manually but please do not expect me or anyone to help you with that. You can install Tandoor manually but please do not expect me or anyone to help you with that.
As a general advice: If you do it manually do NOT change anything at first and slowly work yourself As a general advice: If you do it manually do NOT change anything at first and slowly work yourself
to your dream setup. to your dream setup.

12
docs/install/docker.md
View File

@ -6,6 +6,12 @@ It is possible to install this application using many different Docker configura
Please read the instructions on each example carefully and decide if this is the way for you. Please read the instructions on each example carefully and decide if this is the way for you.
## **DockSTARTer**
The main goal of [DockSTARTer](https://dockstarter.com/) is to make it quick and easy to get up and running with Docker.
You may choose to rely on DockSTARTer for various changes to your Docker system or use DockSTARTer as a stepping stone and learn to do more advanced configurations.
Follow the guide for installing DockSTARTer and then run `ds` then select 'Configuration' and 'Select Apps' to get Tandoor up and running quickly and easily.
## **Docker** ## **Docker**
The docker image (`vabene1111/recipes`) simply exposes the application on the container's port `8080`. The docker image (`vabene1111/recipes`) simply exposes the application on the container's port `8080`.
@ -110,7 +116,7 @@ in combination with [jrcs's letsencrypt companion](https://hub.docker.com/r/jrcs
Please refer to the appropriate documentation on how to setup the reverse proxy and networks. Please refer to the appropriate documentation on how to setup the reverse proxy and networks.
!!! warning "Adjust client_max_body_size" !!! warning "Adjust client_max_body_size"
By using jwilder's Nginx-proxy, uploads will be restricted to 1 MB file size. This can be resolved by adjusting the ```client_max_body_size``` variable in the jwilder nginx configuration. By using jwilder's Nginx-proxy, uploads will be restricted to 1 MB file size. This can be resolved by adjusting the ```client_max_body_size``` variable in the jwilder nginx configuration.
Remember to add the appropriate environment variables to the `.env` file: Remember to add the appropriate environment variables to the `.env` file:
@ -360,11 +366,11 @@ follow these instructions:
### Sub Path nginx config ### Sub Path nginx config
If hosting under a sub-path you might want to change the default nginx config (which gets mounted through the named volume from the application container into the nginx container) If hosting under a sub-path you might want to change the default nginx config (which gets mounted through the named volume from the application container into the nginx container)
with the following config. with the following config.
```nginx ```nginx
location /my_app { # change to subfolder name location /my_app { # change to subfolder name
include /config/nginx/proxy.conf; include /config/nginx/proxy.conf;
proxy_pass https://mywebapp.com/; # change to your host name:port proxy_pass https://mywebapp.com/; # change to your host name:port
proxy_set_header Host $host; proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

24
docs/system/backup.md
View File

@ -8,7 +8,7 @@ downloaded and restored through the web interface.
When developing a new backup strategy, make sure to also test the restore process! When developing a new backup strategy, make sure to also test the restore process!
## Database ## Database
Please use any standard way of backing up your database. For most systems this can be achieved by using a dump Please use any standard way of backing up your database. For most systems this can be achieved by using a dump
command that will create an SQL file with all the required data. command that will create an SQL file with all the required data.
Please refer to your Database System documentation. Please refer to your Database System documentation.
@ -18,7 +18,7 @@ It is **neither** well tested nor documented so use at your own risk.
I would recommend using it only as a starting place for your own backup strategy. I would recommend using it only as a starting place for your own backup strategy.
## Mediafiles ## Mediafiles
The only Data this application stores apart from the database are the media files (e.g. images) used in your The only Data this application stores apart from the database are the media files (e.g. images) used in your
recipes. recipes.
They can be found in the mediafiles mounted directory (depending on your installation). They can be found in the mediafiles mounted directory (depending on your installation).
@ -56,3 +56,23 @@ You can now export recipes from Tandoor using the export function. This method r
Import: Import:
Go to Import > from app > tandoor and select the zip file you want to import from. Go to Import > from app > tandoor and select the zip file you want to import from.
## Backing up using the pgbackup container
You can add [pgbackup](https://hub.docker.com/r/prodrigestivill/postgres-backup-local) to manage the scheduling and automatic backup of your postgres database.
Modify the below to match your environment and add it to your `docker-compose.yml`
``` yaml
pgbackup:
container_name: pgbackup
environment:
BACKUP_KEEP_DAYS: "8"
BACKUP_KEEP_MONTHS: "6"
BACKUP_KEEP_WEEKS: "4"
POSTGRES_EXTRA_OPTS: -Z6 --schema=public --blobs
SCHEDULE: '@daily'
# Note: the tag must match the version of postgres you are using
image: prodrigestivill/postgres-backup-local:15
restart: unless-stopped
volumes:
- backups/postgres:/backups
```
You can manually initiate a backup by running `docker exec -it pgbackup ./backup.sh`

62
docs/system/updating.md
View File

@ -1,6 +1,6 @@
The Updating process depends on your chosen method of [installation](/install/docker) The Updating process depends on your chosen method of [installation](/install/docker)
While intermediate updates can be skipped when updating please make sure to While intermediate updates can be skipped when updating please make sure to
**read the release notes** in case some special action is required to update. **read the release notes** in case some special action is required to update.
## Docker ## Docker
@ -16,7 +16,61 @@ For all setups using Docker the updating process look something like this
For all setups using a manual installation updates usually involve downloading the latest source code from GitHub. For all setups using a manual installation updates usually involve downloading the latest source code from GitHub.
After that make sure to run: After that make sure to run:
1. `manage.py collectstatic` 1. `pip install -r requirements.txt`
2. `manage.py migrate` 2. `manage.py collectstatic`
3. `manage.py migrate`
4. `cd ./vue`
5. `yarn install`
6. `yarn build`
To apply all new migrations and collect new static files. To install latest libraries, apply all new migrations and collect new static files.
## PostgreSQL
Postgres does not automatically upgrade database files when you change versions and requires manual intervention.
One option is to manually [backup/restore](https://docs.tandoor.dev/system/updating/#postgresql) the database.
A full list of options to upgrade a database provide in the [official PostgreSQL documentation](https://www.postgresql.org/docs/current/upgrading.html).
1. Collect information about your environment.
``` bash
grep -E 'POSTGRES|DATABASE' ~/.docker/compose/.env
docker ps -a --format 'table {{.ID}}\t{{.Names}}\t{{.Image}}\t{{.Status}}' | awk 'NR == 1 || /postgres/ || /recipes/'
```
[ ] Database Container
[ ] Tandoor Container
[ ] Database User
2. Export the tandoor database
``` bash
docker exec -t {{database_container}} pg_dumpall -U {{djangouser}} > ~/tandoor.sql
```
3. Stop the postgres container
``` bash
docker stop {{database_container}} {{tandoor_container}}
```
4. Rename the tandoor volume
``` bash
sudo mv -R ~/.docker/compose/postgres ~/.docker/compose/postgres.old
```
5. Update image tag on postgres container.
``` yaml
db_recipes:
restart: always
image: postgres:16-alpine
volumes:
- ./postgresql:/var/lib/postgresql/data
env_file:
- ./.env
```
6. Pull and rebuild container.
``` bash
docker-compose pull && docker-compose up -d
```
7. Import the database export
``` bash
cat ~/tandoor.sql | sudo docker exec -i {{database_container}} psql postgres -U {{djangouser}}
```
If anything fails, go back to the old postgres version and data directory and try again.
There are many articles and tools online that might provide a good starting point to help you upgrade [1](https://thomasbandt.com/postgres-docker-major-version-upgrade), [2](https://github.com/tianon/docker-postgres-upgrade), [3](https://github.com/vabene1111/DockerPostgresBackups).