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. The key has expired.
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.