Merge pull request #2758 from smilerz/updated_documentation

Updated documentation

.env.template

@@ -28,7 +28,7 @@ SECRET_KEY_FILE=
 # ---------------------------------------------------------------
 
 # your default timezone See https://timezonedb.com/time-zones for a list of timezones
-TIMEZONE=Europe/Berlin
+TZ=Europe/Berlin
 
 # add only a database password if you want to run with the default postgres, otherwise change settings accordingly
 DB_ENGINE=django.db.backends.postgresql

docs/faq.md

@@ -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.
 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?
 If you are getting CSRF Errors this is most likely due to a reverse proxy not passing the correct headers.
 
@@ -48,6 +59,9 @@ The other common issue is that the recommended nginx container is removed from t
 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.
 
+## 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?
 

docs/install/docker.md

@@ -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.
 
+## **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**
 
 The docker image (`vabene1111/recipes`) simply exposes the application on the container's port `8080`.

docs/system/backup.md

@@ -56,3 +56,23 @@ You can now export recipes from Tandoor using the export function. This method r
 Import:
 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`

docs/system/updating.md

@@ -16,7 +16,79 @@ 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.
 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/'
+```
+
+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}}
+  ```
+  8. Install postgres extensions
+  ``` bash
+  docker exec -it {{database_container}} psql
+  ```
+  then
+  ``` psql
+  CREATE EXTENSION IF NOT EXISTS unaccent;
+  CREATE EXTENSION IF NOT EXISTS pg_trgm;
+  ```
+
+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).

recipes/settings.py

@@ -450,7 +450,11 @@ for p in PLUGINS:
 
 LANGUAGE_CODE = 'en'
 
+if os.getenv('TIMEZONE') is not None:
+    print('DEPRECATION WARNING: Environment var "TIMEZONE" is deprecated. Please use "TZ" instead.')
     TIME_ZONE = os.getenv('TIMEZONE') if os.getenv('TIMEZONE') else 'Europe/Berlin'
+else:
+    TIME_ZONE = os.getenv('TZ') if os.getenv('TZ') else 'Europe/Berlin'
 
 USE_I18N = True