Skip to content

Commit

Permalink
docs: Single container install instructions (#373)
Browse files Browse the repository at this point in the history
TomBursch authored Apr 3, 2024

Verified

This commit was created on GitHub.com and signed with GitHub’s verified signature.
1 parent 9006934 commit 31c5486
Showing 8 changed files with 120 additions and 54 deletions.
Original file line number Diff line number Diff line change
@@ -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:
Original file line number Diff line number Diff line change
@@ -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:
15 changes: 15 additions & 0 deletions docker-compose-single.yml
Original file line number Diff line number Diff line change
@@ -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:
6 changes: 2 additions & 4 deletions backend/docker-compose.yml → docker-compose.yml
Original file line number Diff line number Diff line change
@@ -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

57 changes: 42 additions & 15 deletions docs/self-hosting/advanced.md
Original file line number Diff line number Diff line change
@@ -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:
```
75 changes: 52 additions & 23 deletions docs/self-hosting/index.md
Original file line number Diff line number Diff line change
@@ -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).
4 changes: 4 additions & 0 deletions docs/self-hosting/migration.md
Original file line number Diff line number Diff line change
@@ -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.

2 changes: 1 addition & 1 deletion docs/self-hosting/reverse-proxy.md
Original file line number Diff line number Diff line change
@@ -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

0 comments on commit 31c5486

Please sign in to comment.