Skip to content

Commit

Permalink
add more info to README (#15)
Browse files Browse the repository at this point in the history
  • Loading branch information
@zhenghaoz
zhenghaoz authored Feb 20, 2023
1 parent f88c544 commit 8e98203
Show file tree
Hide file tree
Showing 4 changed files with 96 additions and 100 deletions.
2 changes: 1 addition & 1 deletion charts/gorse/Chart.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ type: application
# This is the chart version. This version number should be incremented each time you make changes
# to the chart and its templates, including the app version.
# Versions are expected to follow Semantic Versioning (https://semver.org/)
version: 0.4.0
version: 0.4.1

# This is the version number of the application being deployed. This version number should be
# incremented each time you make changes to the application. Versions are not expected to
Expand Down
75 changes: 40 additions & 35 deletions charts/gorse/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,19 +2,19 @@

[Gorse](https://gorse.io) An open-source recommender system service written in Go.

## TL;DR;
## TL;DR

```bash
$ helm repo add bitnami https://charts.bitnami.com/bitnami
$ helm repo add gorse-io https://charts.gorse.io
$ helm upgrade --name my-release --install gorse-io/gorse --devel
helm repo add bitnami https://charts.bitnami.com/bitnami
helm repo add gorse-io https://charts.gorse.io
helm install gorse gorse-io/gorse
```

## Introduction

This chart bootstraps a Gorse deployment on a [Kubernetes](http://kubernetes.io) cluster using the [Helm](https://helm.sh) package manager.

> **Note**: This chart doesn't support horizontal scaling yet.
It also packages the [Bitnami MongoDB chart](https://github.com/bitnami/charts/tree/main/bitnami/mongodb) which is required for bootstrapping a MongoDB deployment for the database requirements of the Gorse application.

## Prerequisites

Expand All @@ -24,30 +24,24 @@ This chart bootstraps a Gorse deployment on a [Kubernetes](http://kubernetes.io)

## Installing the Chart

To install the chart with the release name `my-release` in the `gorse` namespace:
To install the chart with the release name `gorse`:

```bash
$ helm repo add bitnami https://charts.bitnami.com/bitnami
$ helm repo add gorse-io https://charts.gorse.io
$ helm upgrade --name my-release --install gorse-io/gorse --create-namespace --namespace gorse --devel
helm repo add bitnami https://charts.bitnami.com/bitnami
helm repo add gorse-io https://charts.gorse.io
helm install gorse gorse-io/gorse
```

The command deploys Gorse on the Kubernetes cluster in the default configuration. The [Parameters](#parameters) section lists the parameters that can be configured during installation.

> **Tip**: Tou can override the default values by passing `-f ./values.yaml` to the `helm upgrade` command.
**Note**: Gorse requires a properly configured database in order to initialize. See the `values.yaml` file for the configuration values that need to be set. Also, if preferred you can set `postgresql.enabled` to `true` and Helm will deploy the PostgreSQL chart, and Gorse will be able to initialize properly using the default values. (**UNTESTED**)

**Note**: Gorse requires a properly configured cahce in order to initialize. See the `values.yaml` file for the configuration values that need to be set. Also, if preferred you can set `redis.enabled` to `true` and Helm will deploy the Redis chart, and Gorse will be able to initialize properly using the default values. (**UNTESTED**)

> **Tip**: List all releases using `helm list`
## Uninstalling the Chart

To uninstall/delete the `my-release` deployment in the `gorse` namespace:
To uninstall/delete the `gorse` deployment:

```bash
$ helm unistall my-release --namespace gorse
helm unistall gorse
```

The command removes all the Kubernetes components associated with the chart and deletes the release.
Expand Down Expand Up @@ -84,27 +78,27 @@ The command removes all the Kubernetes components associated with the chart and
| `gorse.dashboard.password` | Password for the dashboard. | `""` |
| `gorse.dashboard.authServer` | Token server for the dashboard. | `""` |
| `gorse.api.key` | The key to secure the API endpoint | `""` |
| `gorse.master.http.cors.domains` | List of allowed values for Http Origin | `[]` |
| `gorse.master.http.cors.methods` | List of http methods names. Checking is case-insensitive. | `[]` |
| `gorse.api.corsDomains` | List of allowed values for Http Origin | `[]` |
| `gorse.api.corsMethods` | List of http methods names. Checking is case-insensitive. | `[]` |
| `gorse.api.autoInsertUsers` | Insert new users while inserting feedback | `true` |
| `gorse.api.autoInsertItems` | Insert new items while inserting feedback. | `true` |
| `gorse.api.returnSize` | Default number of returned items | `10` |
| `gorse.api.serverCacheExpire` | Server-side cache expire time | `10s` |
| `gorse.master.jobs` | Number of working jobs in the master node | `1` |
| `gorse.server.items` | Default number of returned items | `10` |
| `gorse.server.insert.users` | Insert new users while inserting feedback | `true` |
| `gorse.server.insert.items` | Insert new items while inserting feedback. | `true` |
| `gorse.server.cache.expire` | Server-side cache expire time | `10s` |
| `gorse.recommend.cache.size` | The cache size for recommended/popular/latest items | `10` |
| `gorse.recommend.cache.expire` | Recommended cache expire time | `72h` |
| `gorse.recommend.ttl.feedback` | The time-to-live (days) of positive feedback | `0` |
| `gorse.recommend.ttl.item` | The time-to-live (days) of items | `0` |
| `gorse.recommend.ttl.popular` | The time window of popular items | `4320h` |
| `gorse.recommend.feedback.positive` | The feedback types for positive events | `[]` |
| `gorse.recommend.feedback.read` | The feedback types for read events. | `[]` |
| `gorse.cache.size` | The cache size for recommended/popular/latest items | `10` |
| `gorse.cache.expire` | Recommended cache expire time | `72h` |
| `gorse.dataSource.feedbackTimeToLive` | The time-to-live (days) of positive feedback | `0` |
| `gorse.dataSource.itemTimeToLive` | The time-to-live (days) of items | `0` |
| `gorse.dataSource.positiveFeedbacks` | The feedback types for positive events | `[]` |
| `gorse.dataSource.readFeedbacks` | The feedback types for read events. | `[]` |
| `gorse.recommend.popular` | The time window of popular items | `4320h` |
| `gorse.recommend.neighbors.users.type` | The type of neighbors for users | `similar` |
| `gorse.recommend.neighbors.items.type` | The type of neighbors for items. | `similar` |
| `gorse.recommend.collaborative.enable` | Enable approximate collaborative filtering recommend using vector index | `true` |
| `gorse.recommend.replacement.enable` | Replace historical items back to recommendations | `false` |
| `gorse.recommend.replacement.decay.positive` | Decay the weights of replaced items from positive feedbacks | `0.8` |
| `gorse.recommend.replacement.decay.read` | Decay the weights of replaced items from read feedbacks | `0.6` |
| `gorse.recommend.online.failback` | The fallback recommendation method is used when cached recommendation drained | `["latest"]` |
| `gorse.recommend.online.fallback` | The fallback recommendation method is used when cached recommendation drained | `["latest"]` |


### Gorse master node parameters
Expand Down Expand Up @@ -297,10 +291,21 @@ The command removes all the Kubernetes components associated with the chart and
| `externalDatabase.existingSecretPasswordKey` | Name of an existing secret key containing the database credentials | `mongodb-passwords` |


## Configuration
helm install gorse \
--set gorse.dashboard.username=admin \
--set gorse.dashboard.password=password \
--set gorse.api.key=api_key \
gorse-io/gorse
```
The above command sets the Gorse administrator account username and password to `admin` and `password` respectively. Additionally, it sets the RESTful API key to `api_key`.
> NOTE: Once this chart is deployed, it is not possible to change the application's access credentials, such as usernames or passwords, using Helm. To change these application credentials after deployment, delete any persistent volumes (PVs) used by the chart and re-deploy it, or use the application's built-in administrative tools if available.
Additional configuration parameters for the Redis chart deployed with Gorse can be found [here](https://github.com/bitnami/charts/tree/master/bitnami/redis).
Alternatively, a YAML file that specifies the values for the above parameters can be provided while installing the chart. For example,
Additional configuration parameters for the PostgreSQL chart deployed with Gorse can be found [here](https://github.com/bitnami/charts/tree/master/bitnami/postgresql).
```bash
helm install gorse -f values.yaml gorse-io/gorse
```

> **Tip**: You can use the default [values.yaml](values.yaml). this will auto generate some secrets.
> **Tip:** You can use the default values.yaml
26 changes: 13 additions & 13 deletions charts/gorse/templates/configmap.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -55,10 +55,10 @@ data:
# AllowedDomains is a list of allowed values for Http Origin.
# The list may contain the special wildcard string ".*" ; all is allowed
# If empty all are allowed.
http_cors_domains = {{ include "gorse.toTOMLArray" (dict "List" .Values.gorse.master.http.domains) }}
http_cors_domains = {{ include "gorse.toTOMLArray" (dict "List" .Values.gorse.api.corsDomains) }}
# AllowedMethods is either empty or has a list of http methods names. Checking is case-insensitive.
http_cors_methods = {{ include "gorse.toTOMLArray" (dict "List" .Values.gorse.master.http.methods) }}
http_cors_methods = {{ include "gorse.toTOMLArray" (dict "List" .Values.gorse.api.corsMethods) }}
# Number of working jobs in the master node. The default value is 1.
n_jobs = 1
Expand All @@ -78,7 +78,7 @@ data:
[server]
# Default number of returned items. The default value is 10.
default_n = {{ .Values.gorse.server.items }}
default_n = {{ .Values.gorse.api.returnSize }}
# Secret key for RESTful APIs (SSL required).
api_key = ""
Expand All @@ -87,40 +87,40 @@ data:
clock_error = "5s"
# Insert new users while inserting feedback. The default value is true.
auto_insert_user = {{ .Values.gorse.server.insert.users }}
auto_insert_user = {{ .Values.gorse.api.autoInsertUsers }}
# Insert new items while inserting feedback. The default value is true.
auto_insert_item = {{ .Values.gorse.server.insert.items }}
auto_insert_item = {{ .Values.gorse.api.autoInsertItems }}
# Server-side cache expire time. The default value is 10s.
cache_expire = {{ .Values.gorse.server.cache.expire | quote }}
cache_expire = {{ .Values.gorse.api.serverCacheExpire | quote }}
[recommend]
# The cache size for recommended/popular/latest items. The default value is 10.
cache_size = {{ .Values.gorse.recommend.cache.size }}
cache_size = {{ .Values.gorse.cache.size }}
# Recommended cache expire time. The default value is 72h.
cache_expire = {{ .Values.gorse.recommend.cache.expire | quote }}
cache_expire = {{ .Values.gorse.cache.expire | quote }}
[recommend.data_source]
# The feedback types for positive events.
positive_feedback_types = {{ include "gorse.toTOMLArray" (dict "List" .Values.gorse.recommend.feedback.positive) }}
positive_feedback_types = {{ include "gorse.toTOMLArray" (dict "List" .Values.gorse.dataSource.positiveFeedbacks) }}
# The feedback types for read events.
read_feedback_types = {{ include "gorse.toTOMLArray" (dict "List" .Values.gorse.recommend.feedback.read) }}
read_feedback_types = {{ include "gorse.toTOMLArray" (dict "List" .Values.gorse.dataSource.readFeedbacks) }}
# The time-to-live (days) of positive feedback, 0 means disabled. The default value is 0.
positive_feedback_ttl = {{ .Values.gorse.recommend.ttl.feedback }}
positive_feedback_ttl = {{ .Values.gorse.dataSource.feedbackTimeToLive }}
# The time-to-live (days) of items, 0 means disabled. The default value is 0.
item_ttl = {{ .Values.gorse.recommend.ttl.item }}
item_ttl = {{ .Values.gorse.dataSource.itemTimeToLive }}
[recommend.popular]
# The time window of popular items. The default values is 4320h.
popular_window = {{ .Values.gorse.recommend.ttl.popular | quote }}
popular_window = {{ .Values.gorse.recommend.popular | quote }}
[recommend.user_neighbors]
Expand Down
93 changes: 42 additions & 51 deletions charts/gorse/values.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -60,65 +60,56 @@ gorse:
## @param gorse.api.key The key to secure the API endpoint
##
key: ""
## @param gorse.api.corsDomains List of allowed values for Http Origin
##
corsDomains: []
## @param gorse.api.corsMethods List of http methods names. Checking is case-insensitive.
##
corsMethods: []
## @param gorse.api.autoInsertUsers Insert new users while inserting feedback
##
autoInsertUsers: true
## @param gorse.api.autoInsertItems Insert new items while inserting feedback.
##
autoInsertItems: true
## @param gorse.api.returnSize Default number of returned items
##
returnSize: 10
## @param gorse.api.serverCacheExpire Server-side cache expire time
##
serverCacheExpire: "10s"

master:
http:
cors:
## @param gorse.master.http.cors.domains List of allowed values for Http Origin
##
domains: []
## @param gorse.master.http.cors.methods List of http methods names. Checking is case-insensitive.
##
methods: []
## @param gorse.master.jobs Number of working jobs in the master node
##
jobs: 1

server:
## @param gorse.server.items Default number of returned items
cache:
## @param gorse.cache.size The cache size for recommended/popular/latest items
##
items: 10

insert:
## @param gorse.server.insert.users Insert new users while inserting feedback
##
users: true
## @param gorse.server.insert.items Insert new items while inserting feedback.
##
items: true
size: 10
## @param gorse.cache.expire Recommended cache expire time
##
expire: "72h"

cache:
## @param gorse.server.cache.expire Server-side cache expire time
##
expire: "10s"
dataSource:
## @param gorse.dataSource.feedbackTimeToLive The time-to-live (days) of positive feedback
##
feedbackTimeToLive: 0
## @param gorse.dataSource.itemTimeToLive The time-to-live (days) of items
##
itemTimeToLive: 0
## @param gorse.dataSource.positiveFeedbacks The feedback types for positive events
##
positiveFeedbacks: []
## @param gorse.dataSource.readFeedbacks The feedback types for read events.
##
readFeedbacks: []

recommend:
cache:
## @param gorse.recommend.cache.size The cache size for recommended/popular/latest items
##
size: 10
## @param gorse.recommend.cache.expire Recommended cache expire time
##
expire: "72h"

ttl:
## @param gorse.recommend.ttl.feedback The time-to-live (days) of positive feedback
##
feedback: 0
## @param gorse.recommend.ttl.item The time-to-live (days) of items
##
item: 0
## @param gorse.recommend.ttl.popular The time window of popular items
##
popular: "4320h"

feedback:
## @param gorse.recommend.feedback.positive The feedback types for positive events
##
positive: []
## @param gorse.recommend.feedback.read The feedback types for read events.
##
read: []
## @param gorse.recommend.popular The time window of popular items
##
popular: "4320h"

neighbors:
users:
Expand Down Expand Up @@ -148,9 +139,9 @@ gorse:
read: 0.6

online:
## @param gorse.recommend.online.failback The fallback recommendation method is used when cached recommendation drained
## @param gorse.recommend.online.fallback The fallback recommendation method is used when cached recommendation drained
##
failback:
fallback:
- "latest"

## @section Gorse master node parameters
Expand Down

0 comments on commit 8e98203

Please sign in to comment.