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

huge documentation and setup restructure

Browse Source
This commit is contained in:
vabene1111 2021-01-05 10:38:18 +01:00
parent bcf50f30bc
commit b90c70b2a3
26 changed files with 530 additions and 447 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

37
README.md
View File

@ -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
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`
Please refer to the Installation section of the [Documentation](https://vabene1111.github.io/recipes/).
## Contributing

39
docs/index.md
View File

@ -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)
- :mag: 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
- :page_facing_up: **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)
- :iphone: Optimized for use on **mobile** devices like phones and tablets
- :shopping_cart: Generate **shopping** lists from recipes
- :calendar: Create a **Plan** on what to eat when
- :family: **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
- :whale: Easy setup with **Docker**
- :art: Customize your interface with **themes**
- :envelope: Export and import recipes from other users
- :earth_africa: localized in many languages thanks to the awesome community
- :heavy_plus_sign: Many more like recipe scaling, image compression, cookbooks, printing views, ...
- 📦 **Sync** files with Dropbox and Nextcloud (more can easily be added)
- 🔍 Powerful **search** with Djangos [TrigramSimilarity](https://docs.djangoproject.com/en/3.0/ref/contrib/postgres/search/#trigram-similarity)
- 🏷️ Create and search for **tags**, assign them in batch to all files matching certain filters
- 📄 **Create recipes** locally within a nice, standardized web interface
- ⬇️ **Import recipes** from thousands of websites supporting [ld+json or microdata](https://schema.org/Recipe)
- 📱 Optimized for use on **mobile** devices like phones and tablets
- 🛒 Generate **shopping** lists from recipes
- 📆 Create a **Plan** on what to eat when
- 👪 **Share** recipes with friends and comment on them to suggest or remember changes you made
- ➗ automatically convert decimal units to **fractions** for those who like this
- 🐳 Easy setup with **Docker**
- 🎨 Customize your interface with **themes**
- ✉️ Export and import recipes from other users
- 🌍 localized in many languages thanks to the awesome community
- ➕ Many more like recipe scaling, image compression, cookbooks, printing views, ...

366
docs/install/docker.md Normal file
View File

@ -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.

68
docs/install/docker/docker.md
View File

@ -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
```

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

@ -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=
```

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

@ -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

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

@ -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
}
}

11
docs/install/docker/nginx-proxy/README.md
View File

@ -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=
```

21
docs/install/docker/nginx-proxy/docker-compose.yml
View File

@ -16,8 +16,9 @@ services:
env_file:
- ./.env
volumes:
- ./staticfiles:/opt/recipes/staticfiles
- ./mediafiles:/opt/recipes/mediafiles
- staticfiles:/opt/recipes/staticfiles
- 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
- ./staticfiles:/static
- ./mediafiles:/media
- nginx_config:/etc/nginx/conf.d:ro
- staticfiles:/static
- mediafiles:/media
networks:
- default
- nginx-proxy
@ -41,3 +42,13 @@ networks:
nginx-proxy:
external:
name: nginx-proxy
volumes:
nginx
staticfiles
mediafiles:
driver: local
driver_opts:
type: 'none'
o: 'bind'
device: './mediafiles'

16
docs/install/docker/nginx-proxy/nginx/conf.d/Recipes.conf
View File

@ -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;
}
}

1
docs/install/docker/plain/README.md
View File

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

21
docs/install/docker/plain/docker-compose.yml
View File

@ -14,8 +14,9 @@ services:
env_file:
- ./.env
volumes:
- ./staticfiles:/opt/recipes/staticfiles
- ./mediafiles:/opt/recipes/mediafiles
- staticfiles:/opt/recipes/staticfiles
- 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
- ./staticfiles:/static
- ./mediafiles:/media
- 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'

16
docs/install/docker/plain/nginx/conf.d/Recipes.conf
View File

@ -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;
}
}

24
docs/install/docker/traefik-nginx/docker-compose.yml
View File

@ -16,8 +16,9 @@ services:
env_file:
- ./.env
volumes:
- ./staticfiles:/opt/recipes/staticfiles
- ./mediafiles:/opt/recipes/mediafiles
- staticfiles:/opt/recipes/staticfiles
- 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
- ./mediafiles:/media
- 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"
- "traefik.http.routers.recipes.tls.certresolver=le_resolver"
- "traefik.http.routers.recipes.entrypoints=web_secure" # your https endpoint
- "traefik.http.routers.recipes.tls.certresolver=le_resolver" # your cert resolver
networks:
- default
- traefik
@ -44,3 +46,13 @@ 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'

16
docs/install/docker/traefik-nginx/nginx/conf.d/Recipes.conf
View File

@ -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;
}
}

69
docs/install/docker/traefik/README.md
View File

@ -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
```

35
docs/install/docker/traefik/docker-compose.yml
View File

@ -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

10
docs/install/k8s/README.md → docs/install/kubernetes.md
View File

@ -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

45
docs/install/manual_install/Readme.md → docs/install/manual.md
View File

@ -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:
```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
Download the `.env` configuration file and **edit it accordingly**.
```shell
wget https://raw.githubusercontent.com/vabene1111/recipes/develop/.env.template -O .env
```
## 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.

9
docs/install/docker/synology/README.md → docs/install/synology.md
View File

@ -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!)

10
docs/install/docker/traefik-nginx/README.md → docs/install/traefik.md
View File

@ -1,10 +1,6 @@
**This is the recommended setup to run django recipes with traefik.**
----
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.
!!! 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.
You need to create a network called `traefik` using `docker network create traefik`.
## docker-compose.yml

BIN
docs/preview.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 1.5 MiB

After

Width:  |  Height:  |  Size: 1.4 MiB

BIN
docs/preview.xcf
View File

Binary file not shown.

28
docs/system/backup.md Normal file
View File

@ -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.

23
docs/system/updating.md Normal file
View File

@ -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.

13
mkdocs.yml
View File

@ -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