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

Enhancement of docker install docs

Browse Source
This commit is contained in:
MaxJa4 2022-01-19 19:13:33 +01:00
parent 6b154b05a6
commit 71a2f1955e
1 changed files with 58 additions and 42 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

100
docs/install/docker.md
View File

@ -1,12 +1,12 @@
!!! success "Recommended Installation" !!! success "Recommended Installation"
Setting up this application using Docker is recommended. This does not mean that other options are bad, just that 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. support is much easier for this setup.
It is possible to install this application using many Docker configurations. It is possible to install this application using many different Docker configurations.
Please read the instructions/notes 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.
## 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`.
@ -32,34 +32,37 @@ Please make sure, if you run your image this way, to consult
the [.env.template](https://raw.githubusercontent.com/vabene1111/recipes/master/.env.template) 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. file in the GitHub repository to verify if additional environment variables are required for your setup.
### Versions Also, don't forget to replace the placeholders for ```SECRET_KEY``` and ```POSTGRES_PASSWORD```!
There are different versions (tags) released on docker hub. ## **Versions**
There are different versions (tags) released on [Docker Hub](https://hub.docker.com/r/vabene1111/recipes/tags).
- **latest** Default image. The one you should use if you don't know that you need anything else. - **latest** Default image. The one you should use if you don't know that you need anything else.
- **beta** Partially stable version that gets updated every now and then. Expect to have some problems. - **beta** Partially stable version that gets updated every now and then. Expect to have some problems.
- **develop** If you want the most bleeding edge version with potentially many breaking changes feel free to use this version (I don't recommend it!). - **develop** If you want the most bleeding edge version with potentially many breaking changes feel free to use this version (not recommended!).
- **X.Y.Z** each released version has its own image. If you need to revert to an old version or want to make sure you stay on one specific use these tags. - **X.Y.Z** each released version has its own image. If you need to revert to an old version or want to make sure you stay on one specific use these tags.
!!! danger "No Downgrading" !!! danger "No Downgrading"
There is currently no way to migrate back to an older version as there is no mechanism to downgrade the database. There is currently no way to migrate back to an older version as there is no mechanism to downgrade the database.
You could probably do it but I cannot help you with that. Choose wisely if you want to use the unstable images. You could probably do it but I cannot help you with that. Choose wisely if you want to use the unstable images.
That said **beta** should usually be working if you like frequent updates and new stuff. That said **beta** should usually be working if you like frequent updates and new stuff.
## Docker Compose ## **Docker Compose**
The main, and also recommended, installation option is to install this application using Docker Compose. The main, and also recommended, installation option for this application is Docker Compose.
1. Choose your `docker-compose.yml` from the examples below. 1. Choose your `docker-compose.yml` from the examples below.
2. Download the `.env` configuration file with `wget`, then **edit it accordingly** (you NEED to set `SECRET_KEY` and `POSTGRES_PASSWORD`). 2. Download the `.env` configuration file with `wget`
```shell ```shell
wget https://raw.githubusercontent.com/vabene1111/recipes/develop/.env.template -O .env wget https://raw.githubusercontent.com/vabene1111/recipes/develop/.env.template -O .env
``` ```
3. Start your container using `docker-compose up -d`. 3. **Edit it accordingly** (you NEED to set `SECRET_KEY` and `POSTGRES_PASSWORD`).
4. Start your container using `docker-compose up -d`.
### Plain ### **Plain**
This configuration exposes the application through an nginx web server on port 80 of your machine. This configuration exposes the application through a containerized nginx web server on port 80 of your machine.
Be aware that having some other web server or container running on your host machine on port 80 will block this from working. Be aware that having some other web server or container running on your host machine on port 80 will block this from working.
```shell ```shell
@ -70,20 +73,23 @@ wget https://raw.githubusercontent.com/vabene1111/recipes/develop/docs/install/d
{% include "./docker/plain/docker-compose.yml" %} {% include "./docker/plain/docker-compose.yml" %}
~~~ ~~~
### Reverse Proxy !!!note
Don't forget to [download and configure](#docker-compose) your ```.env``` file!
### **Reverse Proxy**
Most deployments will likely use a reverse proxy. Most deployments will likely use a reverse proxy.
If your reverse proxy is not listed here, please refer to [Others](https://docs.tandoor.dev/install/docker/#others). If your reverse proxy is not listed below, please refer to chapter [Others](#others).
#### Traefik #### **Traefik**
If you use traefik, this configuration is the one for you. If you use Traefik, this configuration is the one for you.
!!! info !!! info
Traefik can be a little confusing to setup. Traefik can be a little confusing to setup.
Please refer to [their excellent documentation](https://doc.traefik.io/traefik/). If that does not help, 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. [this little example](traefik.md) might be for you.
```shell ```shell
wget https://raw.githubusercontent.com/vabene1111/recipes/develop/docs/install/docker/traefik-nginx/docker-compose.yml wget https://raw.githubusercontent.com/vabene1111/recipes/develop/docs/install/docker/traefik-nginx/docker-compose.yml
@ -93,14 +99,17 @@ wget https://raw.githubusercontent.com/vabene1111/recipes/develop/docs/install/d
{% include "./docker/traefik-nginx/docker-compose.yml" %} {% include "./docker/traefik-nginx/docker-compose.yml" %}
~~~ ~~~
#### nginx-proxy !!!note
Don't forget to [download and configure](#docker-compose) your ```.env``` file!
#### **nginx-proxy**
This is a docker compose example using [jwilder's nginx reverse proxy](https://github.com/jwilder/docker-gen) This is a docker compose example 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/). 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. 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: Remember to add the appropriate environment variables to the `.env` file:
``` ```
VIRTUAL_HOST= VIRTUAL_HOST=
@ -116,7 +125,10 @@ wget https://raw.githubusercontent.com/vabene1111/recipes/develop/docs/install/d
{% include "./docker/nginx-proxy/docker-compose.yml" %} {% include "./docker/nginx-proxy/docker-compose.yml" %}
~~~ ~~~
#### Nginx Swag by LinuxServer !!!note
Don't forget to [download and configure](#docker-compose) your ```.env``` file!
#### **Nginx Swag by LinuxServer**
[This container](https://github.com/linuxserver/docker-swag) is an all in one solution created by LinuxServer.io. [This container](https://github.com/linuxserver/docker-swag) is an all in one solution created by LinuxServer.io.
@ -140,15 +152,18 @@ Please refer to the [appropriate documentation](https://github.com/linuxserver/d
For step-by-step instructions to set this up from scratch, see [this example](swag.md). For step-by-step instructions to set this up from scratch, see [this example](swag.md).
### Others #### **Others**
If you use none of the above mentioned reverse proxies or want to use an existing one on your host machine (like a local nginx or Caddy), simply use the [PLAIN](https://docs.tandoor.dev/install/docker/#plain) setup above and change the outbound port to one of your liking. If you use none of the above mentioned reverse proxies or want to use an existing one on your host machine (like a local nginx or Caddy), simply use the [Plain](#plain) setup above and change the outbound port to one of your liking.
An example port config (inside the respective docker-compose.yml) would be: `8123:80` instead of the `80:80` or if you want to be sure, that Tandoor is **just** accessible via your proxy and don't wanna bother with your firewall, then `127.0.0.1:8123:80` is a viable option too. An example port config (inside the respective docker-compose.yml) would be: `8123:80` instead of the `80:80` or if you want to be sure, that Tandoor is **just** accessible via your proxy and don't wanna bother with your firewall, then `127.0.0.1:8123:80` is a viable option too.
## Additional Information !!!note
Don't forget to [download and configure](#docker-compose) your ```.env``` file!
### Nginx vs Gunicorn ## **Additional Information**
### **Nginx vs Gunicorn**
All examples use an additional `nginx` container to serve mediafiles and act as the forward facing webserver. 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**. This is **technically not required** but **very much recommended**.
@ -158,20 +173,20 @@ the WSGi server that handles the Python execution, explicitly state that it is n
You will also likely not see any decrease in performance or a lot of space used as nginx is a very light container. You will also likely not see any decrease in performance or a lot of space used as nginx is a very light container.
!!! info !!! info
Even if you run behind a reverse proxy as described above, using an additional nginx container is the recommended option. 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 don't care about performance, security and whatever else feel free to run If you run a small private deployment and don't care about performance, security and whatever else feel free to run
without a ngix container. without a nginx container.
!!! warning !!! warning
When running without nginx make sure to enable `GUNICORN_MEDIA` in the `.env`. Without it, media files will be uploaded 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. 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) 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. 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). See also refer to the [official gunicorn docs](https://docs.gunicorn.org/en/stable/deploy.html).
### Nginx Config ### **Nginx Config**
In order to give the user (you) the greatest amount of freedom when choosing how to deploy this application the 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. webserver is not directly bundled with the Docker image.
@ -186,13 +201,14 @@ 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 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. usability. If you know of any better way, feel free to open an issue.
### Volumes vs Bind Mounts ### **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 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). 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/) !!!warning
between the two and you cannot always simply interchange them. 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 You can move everything to volumes if you prefer it this way, **but you cannot convert the nginx config file to a bind
mount.** mount.**