From e1395870bcc9326568836c0d5e2b93d3160069d2 Mon Sep 17 00:00:00 2001 From: Tom Bursch Date: Wed, 3 Apr 2024 15:58:45 +0200 Subject: [PATCH] docs: Single container install instructions --- ...ostgres.yml => docker-compose-postgres.yml | 12 +-- ...abbitmq.yml => docker-compose-rabbitmq.yml | 3 +- docker-compose-single.yml | 15 ++++ .../docker-compose.yml => docker-compose.yml | 6 +- docs/self-hosting/advanced.md | 57 ++++++++++---- docs/self-hosting/index.md | 75 +++++++++++++------ docs/self-hosting/migration.md | 4 + docs/self-hosting/reverse-proxy.md | 2 +- 8 files changed, 120 insertions(+), 54 deletions(-) rename backend/docker-compose-postgres.yml => docker-compose-postgres.yml (81%) rename backend/docker-compose-rabbitmq.yml => docker-compose-rabbitmq.yml (83%) create mode 100644 docker-compose-single.yml rename backend/docker-compose.yml => docker-compose.yml (62%) diff --git a/backend/docker-compose-postgres.yml b/docker-compose-postgres.yml similarity index 81% rename from backend/docker-compose-postgres.yml rename to docker-compose-postgres.yml index fd1d2734..f70f9e64 100644 --- a/backend/docker-compose-postgres.yml +++ b/docker-compose-postgres.yml @@ -17,19 +17,11 @@ services: timeout: 60s retries: 5 start_period: 80s - front: - image: tombursch/kitchenowl-web:latest - restart: unless-stopped - ports: - - "80:80" - depends_on: - - back - networks: - - default back: image: tombursch/kitchenowl:latest restart: unless-stopped - #command: wsgi.ini --gevent 2000 #default: 100 + ports: + - "80:8080" networks: - default environment: diff --git a/backend/docker-compose-rabbitmq.yml b/docker-compose-rabbitmq.yml similarity index 83% rename from backend/docker-compose-rabbitmq.yml rename to docker-compose-rabbitmq.yml index d679fb80..fa3b9ae3 100644 --- a/backend/docker-compose-rabbitmq.yml +++ b/docker-compose-rabbitmq.yml @@ -1,5 +1,6 @@ version: "3" services: +# rabbitmq is only supported with a separate front & backend container front: image: tombursch/kitchenowl-web:latest restart: unless-stopped @@ -10,7 +11,7 @@ services: depends_on: - back back: - image: tombursch/kitchenowl:latest + image: tombursch/kitchenowl-backend:latest restart: unless-stopped command: --ini wsgi.ini:celery --gevent 100 environment: diff --git a/docker-compose-single.yml b/docker-compose-single.yml new file mode 100644 index 00000000..2143f223 --- /dev/null +++ b/docker-compose-single.yml @@ -0,0 +1,15 @@ +version: "3" +services: + back: + image: tombursch/kitchenowl:latest + restart: unless-stopped + ports: + - "80:8080" + environment: + - JWT_SECRET_KEY=PLEASE_CHANGE_ME + # - FRONT_URL=http://localhost # Optional take a look at https://docs.kitchenowl.org/self-hosting/advanced/ for more info + volumes: + - kitchenowl_data:/data + +volumes: + kitchenowl_data: diff --git a/backend/docker-compose.yml b/docker-compose.yml similarity index 62% rename from backend/docker-compose.yml rename to docker-compose.yml index ac11ce26..fedd335a 100644 --- a/backend/docker-compose.yml +++ b/docker-compose.yml @@ -10,13 +10,11 @@ services: depends_on: - back back: - image: tombursch/kitchenowl:latest + image: tombursch/kitchenowl-backend:latest restart: unless-stopped - # ports: # Should only be needed if you're not using docker-compose - # - "5000:5000" # uwsgi protocol environment: - JWT_SECRET_KEY=PLEASE_CHANGE_ME - # - FRONT_URL=http://localhost # Optional should not be changed unless you know what youre doing + # - FRONT_URL=http://localhost # Optional take a look at https://docs.kitchenowl.org/self-hosting/advanced/ for more info volumes: - kitchenowl_data:/data diff --git a/docs/self-hosting/advanced.md b/docs/self-hosting/advanced.md index 5914e7c1..9af012f5 100644 --- a/docs/self-hosting/advanced.md +++ b/docs/self-hosting/advanced.md @@ -5,19 +5,13 @@ There are a few options for advanced users. Customization is done using environm ### Tags There are three tags available: `latest`, `beta` and `dev`. `latest` is the most current stable release and is the default. `beta` corresponds to the most recent prerelease and might have some experimental features. The `dev` tag is directly build from the main branch and should not be used in production. Release notes can be found on the [releases page](https://github.com/TomBursch/kitchenowl/releases). -Additionally, the releases are tagged, so you can always choose a specific version with `vXX` for the backend or `vX.X.X` for the frontend. - -### Frontend - -Environment variables for `tombursch/kitchenowl-web`: - -| Variable | Default | Description | -| ---------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `BACK_URL` | `back:5000` | Allows to set a custom address for the backend. Needs to be an uWSGI protocol endpoint. Should correspond to the name or IP of the backend container and port `5000` | +Additionally, the releases are tagged, so you can always choose a specific version with `vX.X.X`. ### Backend +- Set up with OpenID Connect: [OIDC](./oidc.md) +- Set up with a PostgreSQL database: [docker-compose.yml](https://github.com/TomBursch/kitchenowl/blob/main/docker-compose-postgres.yml) -Environment variables for `tombursch/kitchenowl`: +Environment variables for `tombursch/kitchenowl` and `tombursch/kitchenowl-backend`: | Variable | Default | Description | | ---------------------------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -33,6 +27,7 @@ Environment variables for `tombursch/kitchenowl`: | `STORAGE_PATH` | `/data` | Images are stored in `STORAGE_PATH/upload` | | `DB_DRIVER` | `sqlite` | Supported: `sqlite` and `postgresql` | | `DB_HOST` | | | +| `DB_PORT` | | | | `DB_NAME` | `STORAGE_PATH/database.db` | When the driver is `sqlite` this decides where to store the DB | | `DB_USER` | | | | `DB_PASSWORD` | | | @@ -50,17 +45,49 @@ Environment variables for `tombursch/kitchenowl`: | `GOOGLE_CLIENT_ID` | | | | `GOOGLE_CLIENT_SECRET` | | | -- Set up with OpenID Connect: [OIDC](./oidc.md) -- Set up with a PostgreSQL database: [docker-compose.yml](https://github.com/TomBursch/kitchenowl-backend/blob/main/docker-compose-postgres.yml) - Additionally, to setting these environment variables you can also override the start command to scale the backend up. -Add the following line or take a look at this exemplary [docker-compose.yml](https://github.com/TomBursch/kitchenowl-backend/blob/main/docker-compose-postgres.yml) file: +Add the following line or take a look at this exemplary [docker-compose.yml](https://github.com/TomBursch/kitchenowl/blob/main/docker-compose-postgres.yml) file: ```yml back: [...] - command: wsgi.ini --gevent 2000 # default: 100 + command: --ini wsgi.ini:web --gevent 2000 # default: 100 [...] ``` Overriding the command is not recommended as we might change the underlying process in the future. + +### Frontend + +Environment variables for `tombursch/kitchenowl-web`: + +| Variable | Default | Description | +| ---------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `BACK_URL` | `back:5000` | Allows to set a custom address for the backend. Needs to be an uWSGI protocol endpoint. Should correspond to the name or IP of the backend container and port `5000` | + +## Multiservice Setup +All provided examples can be turned into a multiservice setup with just a few changes. This means separating frontend and backend into multiple docker containers. + + +See [docker-compose.yml](https://github.com/TomBursch/kitchenowl/blob/main/docker-compose.yml) +```yml +version: "3" +services: + front: + image: tombursch/kitchenowl-web:latest + restart: unless-stopped + ports: + - "80:80" + depends_on: + - back + back: + image: tombursch/kitchenowl-backend:latest + restart: unless-stopped + environment: + - JWT_SECRET_KEY=PLEASE_CHANGE_ME + volumes: + - kitchenowl_data:/data + +volumes: + kitchenowl_data: +``` diff --git a/docs/self-hosting/index.md b/docs/self-hosting/index.md index e4c306ac..cf091f5c 100644 --- a/docs/self-hosting/index.md +++ b/docs/self-hosting/index.md @@ -6,31 +6,60 @@ There are multiple ways you can install the KitchenOwl server. The official installation method is using [Docker](https://docs.docker.com/engine/install/) and [docker-compose](https://docs.docker.com/compose/): -1. Download the [docker-compose.yml](https://github.com/TomBursch/kitchenowl-backend/blob/main/docker-compose.yml) -```yml -version: "3" -services: - front: - image: tombursch/kitchenowl-web:latest - restart: unless-stopped - ports: - - "80:80" - depends_on: - - back - back: - image: tombursch/kitchenowl:latest - restart: unless-stopped - environment: - - JWT_SECRET_KEY=PLEASE_CHANGE_ME +=== "Docker compose" + 1. Download [docker-compose.yml](https://github.com/TomBursch/kitchenowl/blob/main/docker-compose.yml) + ```yml + version: "3" + services: + front: + image: tombursch/kitchenowl-web:latest + restart: unless-stopped + # environment: + # - BACK_URL=back:5000 # Change this if you rename the containers + ports: + - "80:80" + depends_on: + - back + back: + image: tombursch/kitchenowl-backend:latest + restart: unless-stopped + environment: + - JWT_SECRET_KEY=PLEASE_CHANGE_ME + volumes: + - kitchenowl_data:/data + volumes: - - kitchenowl_data:/data + kitchenowl_data: + ``` + 2. Change the default value for `JWT_SECRET_KEY` + 3. If you want to use PostgreSQL, change the container names, or want to set other settings take a look at the [advanced](advanced.md) options + 4. Run `docker compose up -d` -volumes: - kitchenowl_data: -``` -2. Change the default value for `JWT_SECRET_KEY` -3. If you change the container names, want to use PostgreSQL, or want to set other settings take a look at the [advanced](advanced.md) options -4. Run `docker compose up -d` +=== "Docker (All-in-one) BETA" + 1. Create a volume `docker volume create kitchenowl_data` + 2. Run `docker exec -d -p 8080:8080 -e "JWT_SECRET_KEY=PLEASE_CHANGE_ME" -v kitchenowl_data:/data tombursch/kitchenowl:latest` + +=== "Docker compose (All-in-one) BETA" + 1. Download [docker-compose.yml](https://github.com/TomBursch/kitchenowl/blob/main/docker-compose-single.yml) + ```yml + version: "3" + services: + back: + image: tombursch/kitchenowl:latest + restart: unless-stopped + ports: + - "80:8080" + environment: + - JWT_SECRET_KEY=PLEASE_CHANGE_ME + volumes: + - kitchenowl_data:/data + + volumes: + kitchenowl_data: + ``` + 2. Change the default value for `JWT_SECRET_KEY` + 3. If you want to use PostgreSQL, use separate containers for front and backend, or want to set other settings take a look at the [advanced](advanced.md) options + 4. Run `docker compose up -d` !!! danger "Important" We recommend running KitchenOwl behind a reverse proxy with HTTPS (e.g. [nginx](https://nginx.org/en/docs/http/configuring_https_servers.html) or [Traefik](https://doc.traefik.io/traefik/)). Some [example configurations have been contributed](reverse-proxy.md). diff --git a/docs/self-hosting/migration.md b/docs/self-hosting/migration.md index 7e8567cb..602f4b6b 100644 --- a/docs/self-hosting/migration.md +++ b/docs/self-hosting/migration.md @@ -1,5 +1,9 @@ # Migrating from Older Versions +### v0.5.0 +The fronted is not required any more `tombursch/kitchenowl:latest` is now an all-in-one container that hosts the web application and backend. Take a look at the [install instructions](index.md) if you want to switch your setup. +Existing setups don't need to be adapted, they will still work like they used to. Although, there now exists a docker image `tombursch/kitchenowl-backend:latest` specifically designed for the split setup. + ### v0.4.9 The frontend is now required and using the option to use the backend as an HTTP server has been removed. diff --git a/docs/self-hosting/reverse-proxy.md b/docs/self-hosting/reverse-proxy.md index a54df401..a0b8b240 100644 --- a/docs/self-hosting/reverse-proxy.md +++ b/docs/self-hosting/reverse-proxy.md @@ -4,7 +4,7 @@ These are community provided and might need to be adapted to your specific setup ### HAProxy -Assumes HAProxy is part of your KitchenOwl docker compose stack. +Assumes HAProxy is part of your KitchenOwl docker compose stack, and you use the multiservice setup method. ``` global