huge documentation and setup restructure

README.md

@@ -1,4 +1,8 @@
-# Recipes ![CI](https://github.com/vabene1111/recipes/workflows/Continous%20Integration/badge.svg?branch=develop)
+# Recipes 
+![CI](https://github.com/vabene1111/recipes/workflows/Continous%20Integration/badge.svg?branch=develop) 
+![Stars](https://img.shields.io/github/stars/vabene1111/recipes)
+![Forks](https://img.shields.io/github/forks/vabene1111/recipes)
+![Docker Pulls](https://img.shields.io/docker/pulls/vabene1111/recipes)
 
 Recipes is a Django application to manage, tag and search recipes using either built in models or 
 external storage providers hosting PDF's, Images or other files.
@@ -34,36 +38,7 @@ While this application has been around for a while and is actively used by many
 **beta** software that has a lot of rough edges and unpolished parts.
 
 ## Installation
-
+Please refer to the Installation section of the [Documentation](https://vabene1111.github.io/recipes/).
-The docker image (`vabene1111/recipes`) simply exposes the application on port `8080`. You may choose any preferred installation method, the following are just examples to make it easier.
-
-> I will try to support issues with any kind of installation but since I run the docker setup I can only offer 
-> limited help for other methods.
-
-### Docker-Compose [Recommended]
-
-1. Choose one of the included configurations [here](docs/install/docker).
-2. Download the environment (config) file template and fill it out `wget https://raw.githubusercontent.com/vabene1111/recipes/develop/.env.template -O .env`
-3. Start the container `docker-compose up -d`
-4. Open the page to create the first user.
-
-### Manual
-
-**Python >= 3.8** is required to run this!
-Refer to [manual install](docs/install/manual_install) for detailed instructions.
-
-### Kubernetes
-
-You can find a basic kubernetes setup [here](docs/install/k8s/). Please see the README in the folder for more detail.
-
-## Updating
-
-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.
-
-0. Before updating it is recommended to **create a backup!**
-1. Stop the container using `docker-compose down`
-2. Pull the latest image using `docker-compose pull`
-3. Start the container again using `docker-compose up -d`
 
 ## Contributing
 

docs/index.md

@@ -1,21 +1,28 @@
-# Welcome to Recipes
+# Welcome to Recipes Documentation
 
 The recipe manager that allows you to manage your ever growing collection of digital recipes.
 
+![Preview](preview.png)
+
+!!! info "WIP"
+    The documentation is work in progress. New information will be added over time.
+    Feel free to open pull requests to enhance the documentation.
+
 ## Features
 
-- :package: **Sync** files with Dropbox and Nextcloud (more can easily be added)
+- 📦 **Sync** files with Dropbox and Nextcloud (more can easily be added)
-- :mag: Powerful **search** with Djangos [TrigramSimilarity](https://docs.djangoproject.com/en/3.0/ref/contrib/postgres/search/#trigram-similarity)
+- 🔍 Powerful **search** with Djangos [TrigramSimilarity](https://docs.djangoproject.com/en/3.0/ref/contrib/postgres/search/#trigram-similarity)
-- :label: Create and search for **tags**, assign them in batch to all files matching certain filters
+- 🏷️ Create and search for **tags**, assign them in batch to all files matching certain filters
-- :page_facing_up: **Create recipes** locally within a nice, standardized web interface
+- 📄 **Create recipes** locally within a nice, standardized web interface
-- :arrow_down: **Import recipes** from thousands of websites supporting [ld+json or microdata](https://schema.org/Recipe)
+- ⬇️ **Import recipes** from thousands of websites supporting [ld+json or microdata](https://schema.org/Recipe)
-- :iphone: Optimized for use on **mobile** devices like phones and tablets
+- 📱 Optimized for use on **mobile** devices like phones and tablets
-- :shopping_cart: Generate **shopping** lists from recipes
+- 🛒 Generate **shopping** lists from recipes
-- :calendar: Create a **Plan** on what to eat when
+- 📆 Create a **Plan** on what to eat when
-- :family: **Share** recipes with friends and comment on them to suggest or remember changes you made
+- 👪 **Share** recipes with friends and comment on them to suggest or remember changes you made
-- :heavy_division_sign: automatically convert decimal units to **fractions** for those who like this
+- ➗ automatically convert decimal units to **fractions** for those who like this
-- :whale: Easy setup with **Docker**
+- 🐳 Easy setup with **Docker**
-- :art: Customize your interface with **themes**
+- 🎨 Customize your interface with **themes**
-- :envelope: Export and import recipes from other users
+- ✉️ Export and import recipes from other users
-- :earth_africa: localized in many languages thanks to the awesome community
+- 🌍 localized in many languages thanks to the awesome community
-- :heavy_plus_sign: Many more like recipe scaling, image compression, cookbooks, printing views, ...
+- ➕ Many more like recipe scaling, image compression, cookbooks, printing views, ...
+

docs/install/docker.md

@@ -0,0 +1,366 @@
+!!! success "Recommended Installation"
+    Setting up this application using Docker is recommended. This does not mean that other options are bad, just that
+    support is much easier for this setup.
+
+It is possible to install this application using many docker configurations.
+
+Please read the instructions/notes on each example carefully and decide if this is the way for you.
+
+## Docker
+
+The docker image (`vabene1111/recipes`) simply exposes the application on port `8080`.
+
+It can be run using
+
+```shell
+docker run -d \
+    -v ./staticfiles:/opt/recipes/staticfiles \
+    -v ./mediafiles:/opt/recipes/mediafiles \
+    -p 80:8080 \
+    -e SECRET_KEY=
+    -e DB_ENGINE=django.db.backends.postgresql
+    -e POSTGRES_HOST=db_recipes
+    -e POSTGRES_PORT=5432
+    -e POSTGRES_USER=djangodb
+    -e POSTGRES_PASSWORD=
+    -e POSTGRES_DB=djangodb
+    vabene1111/recipes
+```
+
+Please make sure, if you run your image this way, to consult
+the [.env.template](https://raw.githubusercontent.com/vabene1111/recipes/master/.env.template)
+file in the GitHub repository to verify if additional environment variables are required for your setup.
+
+## Docker Compose
+
+The main and also recommended installation option is to install this application using docker compose.
+
+1. Choose your `docker-compose.yml` from the examples below
+2. Download the `.env` configuration file and **edit it accordingly**.
+   ```shell
+   wget https://raw.githubusercontent.com/vabene1111/recipes/develop/.env.template -O .env
+   ```
+3. Start your container using `docker-compose up -d`
+
+### Plain
+
+This configuration exposes the application trough a nginx web server on port 80 of you machine.
+
+```yaml
+version: "3"
+services:
+  db_recipes:
+    restart: always
+    image: postgres:11-alpine
+    volumes:
+      - ./postgresql:/var/lib/postgresql/data
+    env_file:
+      - ./.env
+
+  web_recipes:
+    image: vabene1111/recipes
+    restart: always
+    env_file:
+      - ./.env
+    volumes:
+      - staticfiles:/opt/recipes/staticfiles
+      - mediafiles:/opt/recipes/mediafiles
+      - nginx_config:/opt/recipes/nginx/conf.d
+    depends_on:
+      - db_recipes
+
+  nginx_recipes:
+    image: nginx:mainline-alpine
+    restart: always
+    ports:
+      - 80:80
+    env_file:
+      - ./.env
+    volumes:
+      - nginx_config:/etc/nginx/conf.d:ro
+      - staticfiles:/static
+      - mediafiles:/media
+
+volumes:
+  nginx
+  staticfiles
+  mediafiles:
+    driver: local
+    driver_opts:
+      type: 'none'
+      o: 'bind'
+      device: './mediafiles'
+```
+
+### Reverse Proxy
+
+Most deployments will likely use a reverse proxy.
+
+#### Traefik
+If you use traefik this configuration is the one for you.
+
+!!! info
+    Traefik can be a little confusing to setup. 
+    Please refer to [their excellent documentation](https://doc.traefik.io/traefik/). If that does not help
+    [this little example](traefik.md) might be for you.
+
+```yaml
+version: "3"
+services:
+  db_recipes:
+    restart: always
+    image: postgres:11-alpine
+    volumes:
+      - ./postgresql:/var/lib/postgresql/data
+    env_file:
+      - ./.env
+    networks:
+      - default
+
+  web_recipes:
+    image: vabene1111/recipes
+    restart: always
+    env_file:
+      - ./.env
+    volumes:
+      - staticfiles:/opt/recipes/staticfiles
+      - mediafiles:/opt/recipes/mediafiles
+      - nginx_config:/opt/recipes/nginx/conf.d
+    depends_on:
+      - db_recipes
+    networks:
+      - default
+
+  nginx_recipes:
+    image: nginx:mainline-alpine
+    restart: always
+    env_file:
+      - ./.env
+    volumes:
+      - nginx_config:/etc/nginx/conf.d:ro
+      - staticfiles:/static
+      - mediafiles:/media
+    labels: # traefik example labels
+      - "traefik.enable=true"
+      - "traefik.http.routers.recipes.rule=Host(`recipes.mydomain.com`, `recipes.myotherdomain.com`)"
+      - "traefik.http.routers.recipes.entrypoints=web_secure" # your https endpoint
+      - "traefik.http.routers.recipes.tls.certresolver=le_resolver" # your cert resolver
+    networks:
+      - default
+      - traefik
+
+networks:
+  default:
+  traefik: # This is you external traefik network
+    external: true
+
+volumes:
+  nginx
+  staticfiles
+  mediafiles:
+    driver: local
+    driver_opts:
+      type: 'none'
+      o: 'bind'
+      device: './mediafiles'
+```
+
+#### nginx-proxy
+
+This is a docker compose example when using [jwilder's nginx reverse proxy](https://github.com/jwilder/docker-gen) 
+in combination with [jrcs's letsencrypt companion](https://hub.docker.com/r/jrcs/letsencrypt-nginx-proxy-companion/).
+
+Please refer to the appropriate documentation on how to setup the reverse proxy and networks.
+
+Remember to add the appropriate environment variables to `.env` file:
+```
+VIRTUAL_HOST=
+LETSENCRYPT_HOST=
+LETSENCRYPT_EMAIL=
+```
+
+```yaml
+version: "3"
+services:
+  db_recipes:
+    restart: always
+    image: postgres:11-alpine
+    volumes:
+      - ./postgresql:/var/lib/postgresql/data
+    env_file:
+      - ./.env
+    networks:
+      - default
+
+  web_recipes:
+    image: vabene1111/recipes
+    restart: always
+    env_file:
+      - ./.env
+    volumes:
+      - staticfiles:/opt/recipes/staticfiles
+      - mediafiles:/opt/recipes/mediafiles
+      - nginx_config:/opt/recipes/nginx/conf.d
+    depends_on:
+      - db_recipes
+    networks:
+      - default
+
+  nginx_recipes:
+    image: nginx:mainline-alpine
+    restart: always
+    env_file:
+      - ./.env
+    volumes:
+      - nginx_config:/etc/nginx/conf.d:ro
+      - staticfiles:/static
+      - mediafiles:/media
+    networks:
+      - default
+      - nginx-proxy
+
+networks:
+  default:
+  nginx-proxy:
+    external:
+      name: nginx-proxy
+
+volumes:
+  nginx
+  staticfiles
+  mediafiles:
+    driver: local
+    driver_opts:
+      type: 'none'
+      o: 'bind'
+      device: './mediafiles'
+```
+
+## Additional Information
+
+### Nginx vs Gunicorn
+All examples use an additional `nginx` container to serve mediafiles and act as the forward facing webserver.
+This is **technically not required** but **very much recommended**.
+
+I do not 100% understand the deep technical details but the [developers of gunicorn](https://serverfault.com/questions/331256/why-do-i-need-nginx-and-something-like-gunicorn/331263#331263),
+the WSGi server that handles the python execution, explicitly state that it is not recommended to deploy without nginx.
+You will also likely not see any decrease in performance or a lot of space used as nginx is a very light container.
+
+!!! info
+    Even if you run behind a reverse proxy as described above, using an additional nginx container is the recommended option.
+
+If you run a small private deployment and dont care about performance, security and whatever else feel free to run 
+without a ngix container. 
+
+!!! warning
+    When running without nginx make sure to enable `GUNICORN_MEDIA` in the `.env`. Without it media files will be uploaded
+    but not shown on the page.
+
+For additional information please refer to the [0.9.0 Release](https://github.com/vabene1111/recipes/releases?after=0.9.0)
+and [Issue 201](https://github.com/vabene1111/recipes/issues/201) where these topics have been discussed.
+See also refer to the [official gunicorn docs](https://docs.gunicorn.org/en/stable/deploy.html).
+
+### Nginx Config
+
+In order to give the user (you) the greatest amount of freedom when choosing how to deploy this application the
+webserver is not directly bundled with the docker image.
+
+This has the downside that it is difficult to supply the configuration to the webserver (e.g. nginx). Up until
+Version `0.13.0` this had to be done manually by downloading the nginx config file and placing it in a directory that
+was then mounted into the nginx container.
+
+From version `0.13.0` the config file is supplied using the application image (`vabene1111/recipes`). It is then mounted
+to the host system and from there into the nginx container.
+
+This is not really a clean solution, but I could not find any better alternative that provided the same amount of
+usability. If you know of any better way feel free to open an issue.
+
+### Using Proxy Authentication
+
+!!! Info "Community Contributed Tutorial"
+     This tutorial was provided by a community member. Since i do not use reverse proxy authentication i cannot provide any
+     assistance should you choose to use this authentication method.
+
+In order use proxy authentication you will need to:
+
+1. set `REVERSE_PROXY_AUTH=1` in the `.env` file
+2. update your nginx configuration file
+
+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
+    warning `docker-compose.yml` but then you will need to manually create it. See Section `Volumes vs Bind Mounts` below
+    for more information.
+
+The following example shows a configuration for Authelia
+
+```
+server {
+  listen 80;
+  server_name localhost;
+
+  client_max_body_size 16M;
+
+  # serve static files
+  location /static/ {
+    alias /static/;
+  }
+  # serve media files
+  location /media/ {
+    alias /media/;
+  }
+  
+  # Authelia endpoint for authentication requests
+  include /config/nginx/auth.conf;
+
+  # pass requests for dynamic content to gunicorn
+  location / {
+    proxy_set_header Host $host;
+    proxy_pass http://web_recipes:8080;
+
+    # Ensure Authelia is specifically required for this endpoint
+    # This line is important as it will return a 401 error if the user doesn't have access
+    include /config/nginx/authelia.conf;
+
+    auth_request_set $user $upstream_http_remote_user;
+    proxy_set_header REMOTE-USER $user;
+  }
+
+  # Required to allow user to logout of authentication from within Recipes
+  # Ensure the <auth_endpoint> below is changed to actual the authentication url
+  location /accounts/logout/ {
+    return 301 http://<auth_endpoint>/logout
+  }
+}
+```
+
+Please refer to the appropriate documentation on how to setup the reverse proxy, authentication, and networks.
+
+Ensure users have been configured for Authelia, and that the endpoint that recipes is pointed to is protected, but
+available.
+
+There is a good guide to the other additional files that need to be added to your Nginx set up at
+the [Authelia Docs](https://docs.authelia.com/deployment/supported-proxies/nginx.html).
+
+Remember to add the appropriate environment variables to `.env` file (example for nginx proxy):
+
+```
+VIRTUAL_HOST=
+LETSENCRYPT_HOST=
+LETSENCRYPT_EMAIL=
+PROXY_HEADER=
+```
+
+### Volumes vs Bind Mounts
+
+Since I personally prefer to have my data where my `docker-compose.yml` resides, bind mounts are used in the example
+configuration files for all user generated data (e.g. Postgresql and media files).
+
+Please note that [there is a difference in functionality](https://docs.docker.com/storage/volumes/)
+between the two and you cannot always simply interchange them.
+
+You can move everything to volumes if you prefer it this way, **but you cannot convert the nginx config file to a bind
+mount.**
+If you do so you will have to manually create the nginx config file and restart the container once after creating it.

docs/install/docker/docker.md

@@ -1,68 +0,0 @@
-It is possible to install this application using many docker configurations. 
-
-!!! warning 
-    Please note that some examples here are given 
-    because some people want to use them even tough they are not recommended!
-
-Please read the instructions/notes on each example carefully and decide if this is the way for you.
-
-## Docker
-The docker image (`vabene1111/recipes`) simply exposes the application on port `8080`. 
-
-It can be run using
-```shell
-docker run -d \
-    -v ./staticfiles:/opt/recipes/staticfiles \
-    -v ./mediafiles:/opt/recipes/mediafiles \
-    -p 80:8080 \
-    -e SECRET_KEY=
-    -e DB_ENGINE=django.db.backends.postgresql
-    -e POSTGRES_HOST=db_recipes
-    -e POSTGRES_PORT=5432
-    -e POSTGRES_USER=djangodb
-    -e POSTGRES_PASSWORD=
-    -e POSTGRES_DB=djangodb
-    vabene1111/recipes
-```
-
-Please make sure, if you run your image this way, to consult the [.env.template](https://raw.githubusercontent.com/vabene1111/recipes/master/.env.template)
-file in the GitHub repository to verify if additional environment variables are required for your setup.
-
-## Docker Compose
-The main and also recommended installation option is to install this application using docker compose.
-
-```yaml
-version: "3"
-services:
-  db_recipes:
-    restart: always
-    image: postgres:11-alpine
-    volumes:
-      - ./postgresql:/var/lib/postgresql/data
-    env_file:
-      - ./.env
-
-  web_recipes:
-    image: vabene1111/recipes
-    restart: always
-    env_file:
-      - ./.env
-    volumes:
-      - ./staticfiles:/opt/recipes/staticfiles
-      - ./mediafiles:/opt/recipes/mediafiles
-    depends_on:
-      - db_recipes
-
-  nginx_recipes:
-    image: nginx:mainline-alpine
-    restart: always
-    ports:
-      - 80:80
-    env_file:
-      - ./.env
-    volumes:
-      - ./nginx/conf.d:/etc/nginx/conf.d
-      - ./staticfiles:/static
-      - ./mediafiles:/media
-
-```

docs/install/docker/nginx-proxy with proxy authentication/README.md

@@ -1,15 +0,0 @@
-This is a further example combining the power of nginx with the reverse proxy authentication service, [Authelia](https://github.com/authelia/authelia).
-
-Please refer to the appropriate documentation on how to setup the reverse proxy, authentication, and networks.
-
-Ensure users have been configured for Authelia, and that the endpoint that recipes is pointed to is protected, but available.
-
-There is a good guide to the other additional files that need to be added to your Nginx set up at the [Authelia Docs](https://docs.authelia.com/deployment/supported-proxies/nginx.html).
-
-Remember to add the appropriate environment variables to `.env` file:
-```
-VIRTUAL_HOST=
-LETSENCRYPT_HOST=
-LETSENCRYPT_EMAIL=
-PROXY_HEADER=
-```

docs/install/docker/nginx-proxy with proxy authentication/docker-compose.yml

@@ -1,43 +0,0 @@
-version: "3"
-services:
-  db_recipes:
-    restart: always
-    image: postgres:11-alpine
-    volumes:
-      - ./postgresql:/var/lib/postgresql/data
-    env_file:
-      - ./.env
-    networks:
-      - default
-
-  web_recipes:
-    image: vabene1111/recipes
-    restart: always
-    env_file:
-      - ./.env
-    volumes:
-      - ./staticfiles:/opt/recipes/staticfiles
-      - ./mediafiles:/opt/recipes/mediafiles
-    depends_on:
-      - db_recipes
-    networks:
-      - default
-
-  nginx_recipes:
-    image: nginx:mainline-alpine
-    restart: always
-    env_file:
-      - ./.env
-    volumes:
-      - ./nginx/conf.d:/etc/nginx/conf.d
-      - ./staticfiles:/static
-      - ./mediafiles:/media
-    networks:
-      - default
-      - nginx-proxy
-
-networks:
-  default:
-  nginx-proxy:
-    external:
-      name: nginx-proxy

docs/install/docker/nginx-proxy with proxy authentication/nginx/conf.d/Recipes.conf

@@ -1,37 +0,0 @@
-server {
-  listen 80;
-  server_name localhost;
-
-  client_max_body_size 16M;
-
-  # serve static files
-  location /static/ {
-    alias /static/;
-  }
-  # serve media files
-  location /media/ {
-    alias /media/;
-  }
-  
-  # Authelia endpoint for authentication requests
-  include /config/nginx/auth.conf;
-
-  # pass requests for dynamic content to gunicorn
-  location / {
-    proxy_set_header Host $host;
-    proxy_pass http://web_recipes:8080;
-
-    # Ensure Authelia is specifically required for this endpoint
-    # This line is important as it will return a 401 error if the user doesn't have access
-    include /config/nginx/authelia.conf;
-
-    auth_request_set $user $upstream_http_remote_user;
-    proxy_set_header REMOTE-USER $user;
-  }
-
-  # Required to allow user to logout of authentication from within Recipes
-  # Ensure the <auth_endpoint> below is changed to actual the authentication url
-  location /accounts/logout/ {
-    return 301 http://<auth_endpoint>/logout
-  }
-}

docs/install/docker/nginx-proxy/README.md

@@ -1,11 +0,0 @@
-This is a docker compose example when using [jwilder's nginx reverse proxy](https://github.com/jwilder/docker-gen) 
-in combination with [jrcs's letsencrypt companion](https://hub.docker.com/r/jrcs/letsencrypt-nginx-proxy-companion/).
-
-Please refer to the appropriate documentation on how to setup the reverse proxy and networks.
-
-Remember to add the appropriate environment variables to `.env` file:
-```
-VIRTUAL_HOST=
-LETSENCRYPT_HOST=
-LETSENCRYPT_EMAIL=
-```

docs/install/docker/nginx-proxy/docker-compose.yml

@@ -16,8 +16,9 @@ services:
     env_file:
       - ./.env
     volumes:
-      - ./staticfiles:/opt/recipes/staticfiles
+      - staticfiles:/opt/recipes/staticfiles
-      - ./mediafiles:/opt/recipes/mediafiles
+      - mediafiles:/opt/recipes/mediafiles
+      - nginx_config:/opt/recipes/nginx/conf.d
     depends_on:
       - db_recipes
     networks:
@@ -29,9 +30,9 @@ services:
     env_file:
       - ./.env
     volumes:
-      - ./nginx/conf.d:/etc/nginx/conf.d
+      - nginx_config:/etc/nginx/conf.d:ro
-      - ./staticfiles:/static
+      - staticfiles:/static
-      - ./mediafiles:/media
+      - mediafiles:/media
     networks:
       - default
       - nginx-proxy
@@ -40,4 +41,14 @@ networks:
   default:
   nginx-proxy:
     external:
-      name: nginx-proxy
+      name: nginx-proxy
+
+volumes:
+  nginx
+  staticfiles
+  mediafiles:
+    driver: local
+    driver_opts:
+      type: 'none'
+      o: 'bind'
+      device: './mediafiles'

docs/install/docker/nginx-proxy/nginx/conf.d/Recipes.conf

@@ -1,16 +0,0 @@
-server {
-  listen 80;
-  server_name localhost;
-
-  client_max_body_size 16M;
-
-  # serve media files
-  location /media/ {
-    alias /media/;
-  }
-  # pass requests for dynamic content to gunicorn
-  location / {
-    proxy_set_header Host $host;
-    proxy_pass http://web_recipes:8080;
-  }
-}

docs/install/docker/plain/README.md

@@ -1 +0,0 @@
-This is the most basic configuration to run this image with docker compose.

docs/install/docker/plain/docker-compose.yml

@@ -14,8 +14,9 @@ services:
     env_file:
       - ./.env
     volumes:
-      - ./staticfiles:/opt/recipes/staticfiles
+      - staticfiles:/opt/recipes/staticfiles
-      - ./mediafiles:/opt/recipes/mediafiles
+      - mediafiles:/opt/recipes/mediafiles
+      - nginx_config:/opt/recipes/nginx/conf.d
     depends_on:
       - db_recipes
 
@@ -27,6 +28,16 @@ services:
     env_file:
       - ./.env
     volumes:
-      - ./nginx/conf.d:/etc/nginx/conf.d
+      - nginx_config:/etc/nginx/conf.d:ro
-      - ./staticfiles:/static
+      - staticfiles:/static
-      - ./mediafiles:/media
+      - mediafiles:/media
+
+volumes:
+  nginx
+  staticfiles
+  mediafiles:
+    driver: local
+    driver_opts:
+      type: 'none'
+      o: 'bind'
+      device: './mediafiles'

docs/install/docker/plain/nginx/conf.d/Recipes.conf

@@ -1,16 +0,0 @@
-server {
-  listen 80;
-  server_name localhost;
-
-  client_max_body_size 16M;
-
-  # serve media files
-  location /media/ {
-    alias /media/;
-  }
-  # pass requests for dynamic content to gunicorn
-  location / {
-    proxy_set_header Host $host;
-    proxy_pass http://web_recipes:8080;
-  }
-}

docs/install/docker/traefik-nginx/docker-compose.yml

@@ -16,8 +16,9 @@ services:
     env_file:
       - ./.env
     volumes:
-      - ./staticfiles:/opt/recipes/staticfiles
+      - staticfiles:/opt/recipes/staticfiles
-      - ./mediafiles:/opt/recipes/mediafiles
+      - mediafiles:/opt/recipes/mediafiles
+      - nginx_config:/opt/recipes/nginx/conf.d
     depends_on:
       - db_recipes
     networks:
@@ -29,13 +30,14 @@ services:
     env_file:
       - ./.env
     volumes:
-      - ./nginx/conf.d:/etc/nginx/conf.d
+      - nginx_config:/etc/nginx/conf.d:ro
-      - ./mediafiles:/media
+      - staticfiles:/static
+      - mediafiles:/media
     labels: # traefik example labels
       - "traefik.enable=true"
       - "traefik.http.routers.recipes.rule=Host(`recipes.mydomain.com`, `recipes.myotherdomain.com`)"
-      - "traefik.http.routers.recipes.entrypoints=web_secure"
+      - "traefik.http.routers.recipes.entrypoints=web_secure" # your https endpoint
-      - "traefik.http.routers.recipes.tls.certresolver=le_resolver"
+      - "traefik.http.routers.recipes.tls.certresolver=le_resolver" # your cert resolver
     networks:
       - default
       - traefik
@@ -43,4 +45,14 @@ services:
 networks:
   default:
   traefik: # This is you external traefik network
-    external: true
+    external: true
+
+volumes:
+  nginx
+  staticfiles
+  mediafiles:
+    driver: local
+    driver_opts:
+      type: 'none'
+      o: 'bind'
+      device: './mediafiles'

docs/install/docker/traefik-nginx/nginx/conf.d/Recipes.conf

@@ -1,16 +0,0 @@
-server {
-  listen 80;
-  server_name localhost;
-
-  client_max_body_size 16M;
-
-  # serve media files
-  location /media/ {
-    alias /media/;
-  }
-  # pass requests for dynamic content to gunicorn
-  location / {
-    proxy_set_header Host $host;
-    proxy_pass http://web_recipes:8080;
-  }
-}

docs/install/docker/traefik/README.md

@@ -1,69 +0,0 @@
-# :warning: Important Information [NOT RECOMMENDED]
-Although this application allows running without any webserver in front of gunicorn it is heavily recommended by almost 
-everyone **not** to do this. It is hard to find exact explanations and appears not to be a security but only
-a performance risk but that is just my personal interpretation.
-
-**If you dont know what you are doing please choose the traefik-nginx config**
-
-----
-
-Please refer to the traefik documentation on how to setup a docker service in traefik. Since treafik can be a little
-confusing at times, the following are examples of my traefik configuration.
-
-
-You need to create a network called `traefik` using `docker network create traefik`.
-## docker-compose.yml
-
-```
-version: "3.3"
-
-services:
-
-  traefik:
-    image: "traefik:v2.1"
-    container_name: "traefik"
-    ports:
-      - "443:443"
-      - "80:80"
-      - "8080:8080"
-    volumes:
-      - "./letsencrypt:/letsencrypt"
-      - "/var/run/docker.sock:/var/run/docker.sock:ro"
-      - "./config:/etc/traefik/"
-
-
-networks:
-    default:
-       external:
-         name: traefik
-```
-
-## traefik.toml
-Place this in a directory called `config` as this is mounted into the traefik container (see docer compose).
-**Change the email address accordingly**.
-```
-[api]
-  insecure=true
-
-[providers.docker]
-  endpoint = "unix:///var/run/docker.sock"
-  exposedByDefault = false
-  network = "traefik"
-
-#[log]
-#  level = "DEBUG"
-
-[entryPoints]
-  [entryPoints.web]
-    address = ":80"
-
-  [entryPoints.web_secure]
-    address = ":443"
-
-[certificatesResolvers.le_resolver.acme]
-
-  email = "you_email@mail.com"
-  storage = "/letsencrypt/acme.json"
-
-  tlsChallenge=true
-```

docs/install/docker/traefik/docker-compose.yml

@@ -1,35 +0,0 @@
-version: "3"
-services:
-  db_recipes:
-    restart: always
-    image: postgres:11-alpine
-    volumes:
-      - ./postgresql:/var/lib/postgresql/data
-    env_file:
-      - ./.env
-    networks:
-      - default
-
-  web_recipes:
-    image: vabene1111/recipes
-    restart: always
-    env_file:
-      - ./.env
-    volumes:
-      - ./staticfiles:/opt/recipes/staticfiles
-      - ./mediafiles:/opt/recipes/mediafiles
-    depends_on:
-      - db_recipes
-    labels: # This lables are only examples!
-      - "traefik.enable=true"
-      - "traefik.http.routers.recipes.rule=Host(`recipes.mydomain.com`, `recipes.myotherdomain.com`)"
-      - "traefik.http.routers.recipes.entrypoints=web_secure"
-      - "traefik.http.routers.recipes.tls.certresolver=le_resolver"
-    networks:
-      - default
-      - traefik
-
-networks:
-  default:
-  traefik: # This is you external traefic network
-    external: true

docs/install/kubernetes.md

@@ -1,9 +1,15 @@
-> :warning: This guide was contributed by the community and is neither officially supported, nor updated or tested.
+!!! info "Community Contributed"
+    This guide was contributed by the community and is neither officially supported, nor updated or tested.
 
 
 # Kubernetes
 
-This is a basic kubernetes setup. Please note that this does not necessarily follow Kubernetes best practices and should only used as a basis to build your own setup from!
+This is a basic kubernetes setup. 
+Please note that this does not necessarily follow Kubernetes best practices and should only used as a 
+basis to build your own setup from!
+
+All files con be found here in the Github Repo: 
+[docs/install/k8s](https://github.com/vabene1111/recipes/tree/develop/docs/install/k8s)
 
 ## Important notes
 

docs/install/manual.md

@@ -2,7 +2,8 @@
 
 These intructions are inspired from a standard django/gunicorn/postgresql instructions ([for example](https://www.digitalocean.com/community/tutorials/how-to-set-up-django-with-postgres-nginx-and-gunicorn-on-ubuntu-16-04))
 
-**Important note:** Be sure to use pyton3.8 and pip related to python 3.8. Depending on your distribution calling `python` or `pip` will use python2 instead of pyton 3.8.
+!!! warning
+    Be sure to use pyton3.8 and pip related to python 3.8. Depending on your distribution calling `python` or `pip` will use python2 instead of pyton 3.8.
 
 ## Prerequisites
 
@@ -34,43 +35,9 @@ ALTER ROLE djangouser SET timezone TO 'UTC';
 ALTER USER djangouser WITH SUPERUSER;
 ```
 
-Move or copy `.env.template` to `.env` and update it with relevent values. For example:
+Download the `.env` configuration file and **edit it accordingly**.
-
+```shell
-```env
+wget https://raw.githubusercontent.com/vabene1111/recipes/develop/.env.template -O .env
-# only set this to true when testing/debugging
-# when unset: 1 (true) - dont unset this, just for development
-DEBUG=0
-
-# hosts the application can run under e.g. recipes.mydomain.com,cooking.mydomain.com,...
-#ALLOWED_HOSTS=*
-
-# random secret key, use for example base64 /dev/urandom | head -c50 to generate one
-SECRET_KEY=TOGENERATE
-
-# add only a database password if you want to run with the default postgres, otherwise change settings accordingly
-DB_ENGINE=django.db.backends.postgresql_psycopg2
-POSTGRES_HOST=localhost
-POSTGRES_PORT=5432
-POSTGRES_USER=djangouser
-POSTGRES_PASSWORD=password
-POSTGRES_DB=djangodb
-
-# Serve mediafiles directly using gunicorn. Basically everyone recommends not doing this. Please use any of the examples
-# provided that include an additional nxginx container to handle media file serving.
-# If you know what you are doing turn this back on (1) to serve media files using djangos serve() method.
-# when unset: 1 (true) - this is temporary until an appropriate amount of time has passed for everyone to migrate
-GUNICORN_MEDIA=0
-
-
-# allow authentication via reverse proxy (e.g. authelia), leave of if you dont know what you are doing
-# docs: https://github.com/vabene1111/recipes/tree/develop/docs/docker/nginx-proxy%20with%20proxy%20authentication
-# when unset: 0 (false)
-REVERSE_PROXY_AUTH=0
-
-
-# the default value for the user preference 'comments' (enable/disable commenting system)
-# when unset: 1 (true)
-COMMENT_PREF_DEFAULT=1
 ```
 
 ## Initialize the application
@@ -79,7 +46,7 @@ Execute `export $(cat .env |grep "^[^#]" | xargs)` to load variables from `.env`
 
 Execute `/python3.8 manage.py migrate`
 
-And revert superuser from postgres: `sudo -u postgres psql` and `ALTER USER djangouser WITH NOSUPERUSER;`
+and revert superuser from postgres: `sudo -u postgres psql` and `ALTER USER djangouser WITH NOSUPERUSER;`
 
 Generate static files: `python3.8 manage.py collectstatic` and remember the folder where files have been copied.
 

docs/install/synology.md

@@ -1,4 +1,5 @@
-> :warning: This guide was contributed by the community and is neither officially supported, nor updated or tested.
+!!! info "Community Contributed"
+    This guide was contributed by the community and is neither officially supported, nor updated or tested.
 
 Many people appear to host this application on their Synology NAS. The following documentation was provided by 
 @therealschimmi in [this issue discussion](https://github.com/vabene1111/recipes/issues/98#issuecomment-643062907).
@@ -8,7 +9,7 @@ setup. Since i cannot test it myself feedback and improvements are always very w
 
 ## Instructions
 
-Basic guide to setup vabenee1111/recipes docker container on Synology NAS
+Basic guide to setup `vabenee1111/recipes docker` container on Synology NAS
 
 1. Login to Synology DSM through your browser
 
@@ -21,9 +22,9 @@ Basic guide to setup vabenee1111/recipes docker container on Synology NAS
 
 2. Download templates
 - vabene1111 gives you a few samples for various setups to work with. I chose to use the plain setup for now.
-- Open https://github.com/vabene1111/recipes/tree/develop/docs/docker
+- Open https://github.com/vabene1111/recipes/tree/develop/docs/install/docker
 - Download docker-compose.yml to your recipes folder 
-- Open https://github.com/vabene1111/recipes/tree/develop/docs/docker/plain/nginx/conf.d
+- Open https://github.com/vabene1111/recipes/tree/develop/nginx/conf.d
 - Download Recipes.conf to your conf.d folder 
 - Open https://github.com/vabene1111/recipes/blob/develop/.env.template
 - Copy the text and save it as '.env' to your recipes folder (no filename extension!)

docs/install/traefik.md

@@ -1,10 +1,6 @@
-**This is the recommended setup to run django recipes with traefik.**
+!!! danger
-
+    Please refer to [the offical documentation](https://doc.traefik.io/traefik/).
-----
+    This example just shows something similar to my setup in case you dont understand the offical documentation.
-
-Please refer to the traefik documentation on how to setup a docker service in traefik. Since treafik can be a little
-confusing at times, the following are examples of my traefik configuration.
-
 
 You need to create a network called `traefik` using `docker network create traefik`.
 ## docker-compose.yml

docs/system/backup.md

@@ -0,0 +1,28 @@
+There is currently no "good" way of backing up your data implemented in the application itself.
+This mean that you will be responsible for backing up your data.
+
+It is planned to add a "real" backup feature similar to applications like homeassistant where a snapshot can be
+downloaded and restored trough the web interface.
+
+!!! warning
+    When developing a new backup strategy, make sure to also test the restore process!
+
+## Database
+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.
+
+Please refer to your Database System documentation.
+
+I personally use a [little script](https://github.com/vabene1111/DockerPostgresBackups) that I have created to automatically pull SQL dumps from a postgresql database.
+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.
+
+## Mediafiles
+The only Data this application stores apart from the database are the media files (e.g. images) used in your 
+recipes.
+
+They can be found in the mediafiles mounted directory (depending on your installation).
+
+To create a backup of those files simply copy them elsewhere. Do it the other way around for restoring.
+
+The filenames consist of `<random uuid4>_<recipe_id>`. In case you screw up really badly this can help restore data.

docs/system/updating.md

@@ -0,0 +1,23 @@
+The Updating process depends on your chosen method of [installation](/install/docker)
+
+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.
+
+## Docker
+For all setups using Docker the updating process look something like this
+
+0. Before updating it is recommended to **create a [backup](/system/backup)!**
+1. Stop the container using `docker-compose down`
+2. Pull the latest image using `docker-compose pull`
+3. Start the container again using `docker-compose up -d`
+
+
+## Manual
+
+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`
+2. `manage.py migrate`
+
+To apply all new migrations and collect new static files.

mkdocs.yml

@@ -1,12 +1,13 @@
 site_name: Recipes
-site_description: Documentation for Firefly III
+site_description: Documentation for Recipes
 site_author: vabene1111
 repo_url: https://github.com/vabene1111/recipes
 edit_uri: https://github.com/vabene1111/recipes/tree/develop/docs
 theme:
   name: material
   palette:
-    primary: lime
+    scheme: slate
+    primary: green
     accent: deep orange
     logo: cookbook/static/favicon.png
     favicon: cookbook/static/favicon.ico
@@ -21,4 +22,10 @@ markdown_extensions:
 nav:
   - Home: 'index.md'
   - Installation:
-      - Docker: install/docker/docker.md
+      - Docker: install/docker.md
+      - Synology: install/synology.md
+      - Kubernetes: install/kubernetes.md
+      - Manual: install/manual.md
+  - System:
+      - Updating: system/updating.md
+      - Backup: system/backup.md