Gorse

https://gorse.io/docs
Admin
Gorse is an open-source recommender system that provides personalized recommendations through...
Tokens:81,745
Snippets:263
Trust Score:6.8
Update:1 year ago
Show doc for...
Tokens:
Raw
### Setup Gorse Single Node via Playground

Source: https://gorse.io/docs/0.4/quick-start

Installs and runs a Gorse all-in-one node using a playground script. This is the quickest way to get a minimal usable Gorse instance running.

```bash
curl -fsSL https://gorse.io/playground | bash
```

```docker
docker run -p 8088:8088 zhenghaoz/gorse-in-one --playground
```

--------------------------------

### Setup Gorse Development Environment

Source: https://gorse.io/docs/0.4/contribution-guide

Instructions to set up the Gorse development environment. Requires Go (>= 1.18) and Docker Compose for managing databases needed for tests. This snippet shows how to start the necessary databases.

```bash
cd storage
docker-compose up -d

```

--------------------------------

### Setup Gorse Single Node via Playground (Bash)

Source: https://gorse.io/docs/master/quick-start

This command downloads and executes a script to set up a Gorse all-in-one node. It's the simplest way to get a single-node Gorse instance running for testing or development.

```bash
curl -fsSL https://gorse.io/playground | bash
```

--------------------------------

### Setup Gorse Development Environment

Source: https://gorse.io/docs/master/contribution-guide

This snippet shows how to set up the necessary databases for Gorse development using Docker Compose. It requires Go (>= 1.18) and Docker Compose to be installed.

```bash
cd storage
docker-compose up -d
```

--------------------------------

### Install Gorse Go SDK

Source: https://gorse.io/docs/0.4/api/go-sdk

Instructions for installing the Gorse Go SDK using the go get command. This command fetches the latest version from the master branch.

```go
go get github.com/zhenghaoz/gorse/client@master
```

--------------------------------

### Setup Gorse Cluster via Docker Compose

Source: https://gorse.io/docs/0.4/quick-start

Deploys a Gorse cluster including master, server, and worker nodes, along with Redis and MySQL dependencies, using Docker Compose. This setup is for a multi-node cluster.

```bash
# Create a new directory
mkdir gorse
cd gorse

# Download docker-compose.yml and config.toml
# Note: The provided URL for docker-compose.yml in the text points to a specific release branch, which might change.
# Using a more stable source if available or the exact one from the text.
# For this example, we'll use the provided URLs.
wget https://raw.githubusercontent.com/zhenghaoz/gorse/release-0.4/docker-compose.yml
wget https://raw.githubusercontent.com/zhenghaoz/gorse/release-0.4/config/config.toml

# Setup the Gorse cluster using Docker Compose
docker-compose up -d
```

```bash
# Download sample data.
wget https://cdn.gorse.io/example/github.sql

# Import sample data into the MySQL instance.
# Assumes MySQL is running and accessible on 127.0.0.1 with user 'gorse' and password 'gorse_pass'.
mysql -h 127.0.0.1 -u gorse -pgorse_pass gorse < github.sql
```

```bash
# Restart the master node to reload imported data immediately.
docker-compose restart
```

--------------------------------

### Setup Gorse Cluster via Docker Compose (Download Files)

Source: https://gorse.io/docs/master/quick-start

These commands set up a Gorse cluster by downloading the necessary Docker Compose configuration and a sample configuration file. It prepares the environment for a multi-node Gorse deployment.

```bash
# Create a new directory
mkdir gorse
cd gorse

# Download docker-compose.yml and config.toml
wget https://raw.githubusercontent.com/zhenghaoz/gorse/release-0.4/docker-compose.yml
wget https://raw.githubusercontent.com/zhenghaoz/gorse/release-0.4/config/config.toml
```

--------------------------------

### Setup Gorse Cluster via Docker Compose (Run)

Source: https://gorse.io/docs/master/quick-start

This command starts the Gorse cluster defined in the docker-compose.yml file. It orchestrates the creation of master, server, worker nodes, along with Redis and MySQL instances.

```docker
docker-compose up -d
```

--------------------------------

### Java SDK Usage Example

Source: https://gorse.io/docs/0.4/api/java-sdk

Demonstrates how to create a Gorse client instance and perform basic operations like inserting feedback and getting recommendations using the Java SDK.

```java
import io.gorse.gorse4j.*;
import java.util.List;

public class Main {

    public static void main(String[] args) {
        // Create a client.
        Gorse client = new Gorse("http://127.0.0.1:8087", "api_key");

        // Insert feedback.
        List<Feedback> feedbacks = List.of(
                new Feedback("read", "100", "300", "2022-11-20T13:55:27Z"),
                new Feedback("read", "100", "400", "2022-11-20T13:55:27Z")
        );
        client.insertFeedback(feedbacks);

        // Get recommendation.
        client.getRecommend("100");
    }
}
```

--------------------------------

### Setup Gorse Single Node via Playground (Docker)

Source: https://gorse.io/docs/master/quick-start

This command runs a Docker container for the Gorse all-in-one node, exposing the RESTful endpoint on port 8088. It's used after the playground script or as an alternative way to start the single-node instance.

```docker
docker run -p 8088:8088 zhenghaoz/gorse-in-one --playground
```

--------------------------------

### Start Gorse Services

Source: https://gorse.io/docs/0.4/deploy/docker

Starts all services defined in the docker-compose.yml file in detached mode, allowing Gorse to run in the background.

```bash
docker-compose up -d
```

--------------------------------

### Go SDK Installation

Source: https://gorse.io/docs/master/api/go-sdk

Installs the Gorse Go SDK client from the master branch. This command fetches the latest version of the SDK.

```bash
go get github.com/zhenghaoz/gorse/client@master
```

--------------------------------

### Run Gorse Integration Tests

Source: https://gorse.io/docs/master/contribution-guide

This snippet demonstrates how to run integration tests for Gorse. It involves starting Gorse with Docker Compose and then executing Go tests with the 'integrate_test' tag.

```bash
# Setup Gorse
docker-compose up -d

# Test
go test -tags='integrate_test' ./client/
```

--------------------------------

### Setup Gorse Service using NSSM on Windows

Source: https://gorse.io/docs/master/deploy/binary

This snippet outlines the process for installing Gorse as a Windows service using NSSM (Non-Sucking Service Manager). It includes creating directories, moving the executable and configuration, and configuring NSSM parameters for the service.

```powershell
New-Item -Type Directory -Path $env:ProgramFiles/Gorse/log
New-Item -Type Directory -Path $env:ProgramFiles/Gorse/data
```

```powershell
Move-Item config.toml -Destination $env:ProgramFiles/Gorse/bin
```

```powershell
nssm install Gorse $env:ProgramFiles\Gorse\bin\gorse-in-one.exe
nssm set Gorse AppParameters -c bin\config.toml --cache-path data\gorse.data
nssm set Gorse AppDirectory $env:ProgramFiles\Gorse
nssm set Gorse AppStdout $env:ProgramFiles\Gorse\log\gorse.log
nssm set Gorse AppStderr $env:ProgramFiles\Gorse\log\gorse.log
nssm start Gorse
```

--------------------------------

### Install Python SDK via PyPI

Source: https://gorse.io/docs/0.4/api/python-sdk

Install the Gorse Python SDK using pip, the standard package installer for Python. This is the recommended method for most users.

```bash
pip install PyGorse
```

--------------------------------

### Setup Gorse Systemd Service on Linux

Source: https://gorse.io/docs/master/deploy/binary

This snippet details the steps to set up Gorse as a systemd service on Linux. It covers creating necessary directories, moving configuration files, defining the service unit, and managing the service lifecycle (reload, enable, start, status).

```shell
sudo mkdir -p /etc/gorse/
sudo mkdir -p /var/log/gorse/
sudo mkdir -p /var/lib/gorse/
```

```shell
sudo mv config.toml /etc/gorse/
```

```shell
[Unit]
Description=Gorse, an open source recommender system service written in Go.
After=network.target

[Service]
Type=simple
Restart=always
ExecStart=/usr/local/bin/gorse-in-one -c /etc/gorse/config.toml \
    --log-path /var/log/gorse/gorse.log \
    --cache-path /var/lib/gorse/gorse.data

[Install]
WantedBy=multi-user.target
```

```shell
sudo systemctl daemon-reload
```

```shell
sudo systemctl enable gorse
```

```shell
sudo systemctl start gorse
```

```shell
systemctl status gorse
```

--------------------------------

### Install .NET SDK

Source: https://gorse.io/docs/master/api/dotnet-sdk

Instructions for installing the Gorse .NET SDK. You can use either the .NET CLI or the NuGet Package Manager to add the Gorse.NET package to your project.

```bash
dotnet add package Gorse.NET
```

```powershell
NuGet\Install-Package Gorse.NET
```

--------------------------------

### Gorse API: Get Recommendations

Source: https://gorse.io/docs/master/quick-start

Fetches a list of recommended item IDs for a specific user. The number of recommendations can be controlled using the 'n' query parameter. This is useful for personalized content delivery.

```APIDOC
GET /api/recommend/{userId}?n={count}

Description:
  Fetches recommended items for a given user.

Parameters:
  - userId (path parameter): The ID of the user for whom to fetch recommendations.
  - n (query parameter, optional): The number of recommendations to retrieve. Defaults to 10 if not specified.

Example cURL Command:
  curl http://127.0.0.1:8087/api/recommend/bob?n=10

Expected Output:
  A JSON array of item IDs, representing the recommendations for the user.
  [
      "mbostock:d3",
      "nt1m:material-framework",
      "mdbootstrap:vue-bootstrap-with-material-design",
      "justice47:f2-vue",
      "10clouds:cyclejs-cookie",
      "academicpages:academicpages.github.io",
      "accenture:alexia",
      "addyosmani:tmi",
      "1wheel:d3-starterkit",
      "acdlite:redux-promise"
  ]
```

--------------------------------

### Gorse Configuration Example (Feedback Types)

Source: https://gorse.io/docs/master/quick-start

This TOML snippet shows how to configure feedback types in Gorse. It defines which user interactions are considered positive feedback (e.g., 'star', 'like') and which are read feedback (e.g., 'read').

```toml
# The feedback types for positive events.
positive_feedback_types = ["star","like"]

# The feedback types for read events.
# read_feedback_types = ["read"]

```

--------------------------------

### Install Ruby SDK

Source: https://gorse.io/docs/0.4/api/ruby-sdk

This snippet shows the command to install the Gorse Ruby SDK using the RubyGems package manager. Ensure you have Ruby and RubyGems installed on your system.

```bash
gem install gorse

```

--------------------------------

### Start Gorse Services with Docker Compose

Source: https://gorse.io/docs/0.4/deploy/docker

This command initiates all the services defined in the `docker-compose.yaml` file. The `-d` flag ensures that the containers run in detached mode, meaning they will run in the background and the terminal will be freed up for other commands.

```bash
docker-compose up -d

```

--------------------------------

### Install Gorse-in-one Binary

Source: https://gorse.io/docs/0.4/deploy/binary

Install the downloaded Gorse-in-one binary to a system-wide accessible location. This typically involves unzipping the archive into a directory like /usr/local/bin.

```bash
sudo unzip gorse.zip -d /usr/local/bin
```

```bash
sudo unzip gorse.zip -d /usr/local/bin
```

```powershell
# Create install directory
New-Item -Type Directory -Path $env:ProgramFiles/Gorse/bin

# Extract binaries
Expand-Archive gorse.zip -DestinationPath $env:ProgramFiles/Gorse/bin
```

--------------------------------

### Install Python SDK via PyPI

Source: https://gorse.io/docs/master/api/python-sdk

Installs the Gorse Python SDK using pip, the standard package installer for Python. This is the recommended method for most users.

```bash
pip install PyGorse
```

--------------------------------

### Install Gorse Binary

Source: https://gorse.io/docs/master/deploy/binary

Install the downloaded Gorse-in-one binary to the system's executable path. This step involves unzipping the archive and placing the executable in a directory included in the system's PATH.

```shell
sudo unzip gorse.zip -d /usr/local/bin
```

```shell
sudo unzip gorse.zip -d /usr/local/bin
```

```powershell
# Create install directory
New-Item -Type Directory -Path $env:ProgramFiles/Gorse/bin

# Extract binaries
Expand-Archive gorse.zip -DestinationPath $env:ProgramFiles/Gorse/bin
```

--------------------------------

### Install Gorse .NET SDK via .NET CLI

Source: https://gorse.io/docs/0.4/api/dotnet-sdk

Instructions for installing the Gorse .NET SDK using the .NET command-line interface. This is a common method for adding package dependencies to .NET projects.

```bash
dotnet add package Gorse.NET
```

--------------------------------

### Gorse Go SDK Usage Example

Source: https://gorse.io/docs/0.4/api/go-sdk

Demonstrates how to use the Gorse Go SDK to create a client, insert feedback data, and retrieve recommendations. It requires importing the client package and initializing the client with a server address and API key.

```go
import "github.com/zhenghaoz/gorse/client"

func main() {
    // Create a client
    gorse := client.NewGorseClient("http://127.0.0.1:8087", "api_key")

    // Insert feedback
    gorse.InsertFeedback([]client.Feedback{
        {FeedbackType: "star", UserId: "bob", ItemId: "vuejs:vue", Timestamp: "2022-02-24"},
        {FeedbackType: "star", UserId: "bob", ItemId: "d3:d3", Timestamp: "2022-02-25"},
        {FeedbackType: "star", UserId: "bob", ItemId: "dogfalo:materialize", Timestamp: "2022-02-26"},
        {FeedbackType: "star", UserId: "bob", ItemId: "mozilla:pdf.js", Timestamp: "2022-02-27"},
        {FeedbackType: "star", UserId: "bob", ItemId: "moment:moment", Timestamp: "2022-02-28"},
    })

    // Get recommendation.
    gorse.GetRecommend("bob", "", 10)
}
```

--------------------------------

### Go SDK Usage Example

Source: https://gorse.io/docs/master/api/go-sdk

Demonstrates how to create a Gorse client, insert feedback data, and retrieve recommendations using the Go SDK. It shows basic client initialization and common operations.

```go
import "github.com/zhenghaoz/gorse/client"

func main() {
    // Create a client
    gorse := client.NewGorseClient("http://127.0.0.1:8087", "api_key")

    // Insert feedback
    gorse.InsertFeedback([]client.Feedback{
        {FeedbackType: "star", UserId: "bob", ItemId: "vuejs:vue", Timestamp: "2022-02-24"},
        {FeedbackType: "star", UserId: "bob", ItemId: "d3:d3", Timestamp: "2022-02-25"},
        {FeedbackType: "star", UserId: "bob", ItemId: "dogfalo:materialize", Timestamp: "2022-02-26"},
        {FeedbackType: "star", UserId: "bob", ItemId: "mozilla:pdf.js", Timestamp: "2022-02-27"},
        {FeedbackType: "star", UserId: "bob", ItemId: "moment:moment", Timestamp: "2022-02-28"},
    })

    // Get recommendation.
    gorse.GetRecommend("bob", "", 10)
}
```

--------------------------------

### Import GitHub Data to Gorse MySQL Instance

Source: https://gorse.io/docs/master/quick-start

These commands download a sample dataset (github.sql) and import it into the Gorse MySQL instance. This populates the database with user-repository interactions required for the recommender system.

```bash
# Download sample data.
wget https://cdn.gorse.io/example/github.sql

# Import sample data.
mysql -h 127.0.0.1 -u gorse -pgorse_pass gorse < github.sql
```

--------------------------------

### Install Gorse Rust SDK

Source: https://gorse.io/docs/master/api/rust-sdk

Add the gorse_rs crate to your project's dependencies in Cargo.toml to start using the Gorse Rust SDK.

```toml
[dependencies]
gorse_rs = "0.4.1"

```

--------------------------------

### Usage of .NET SDK

Source: https://gorse.io/docs/master/api/dotnet-sdk

Example demonstrating how to use the Gorse .NET SDK. This includes initializing the Gorse client with a server URL and API key, inserting feedback data, and retrieving recommendations.

```csharp
using Gorse.NET;

var client = new Gorse("http://127.0.0.1:8087", "api_key");

client.InsertFeedback(new Feedback[]
{
    new Feedback{FeedbackType="star", UserId="bob", ItemId="vuejs:vue", Timestamp="2022-02-24"},
    new Feedback{FeedbackType="star", UserId="bob", ItemId="d3:d3", Timestamp="2022-02-25"},
    new Feedback{FeedbackType="star", UserId="bob", ItemId="dogfalo:materialize", Timestamp="2022-02-26"},
    new Feedback{FeedbackType="star", UserId="bob", ItemId="mozilla:pdf.js", Timestamp="2022-02-27"},
    new Feedback{FeedbackType="star", UserId="bob", ItemId="moment:moment", Timestamp="2022-02-28"},
});

client.GetRecommend("10");

```

--------------------------------

### Gorse .NET SDK Usage Example

Source: https://gorse.io/docs/0.4/api/dotnet-sdk

Demonstrates how to initialize the Gorse client and perform common operations such as inserting feedback data and requesting recommendations. It shows the basic structure for interacting with the Gorse API using the .NET SDK.

```csharp
using Gorse.NET;

var client = new Gorse("http://127.0.0.1:8087", "api_key");

client.InsertFeedback(new Feedback[]
{
    new Feedback{FeedbackType="star", UserId="bob", ItemId="vuejs:vue", Timestamp="2022-02-24"},
    new Feedback{FeedbackType="star", UserId="bob", ItemId="d3:d3", Timestamp="2022-02-25"},
    new Feedback{FeedbackType="star", UserId="bob", ItemId="dogfalo:materialize", Timestamp="2022-02-26"},
    new Feedback{FeedbackType="star", UserId="bob", ItemId="mozilla:pdf.js", Timestamp="2022-02-27"},
    new Feedback{FeedbackType="star", UserId="bob", ItemId="moment:moment", Timestamp="2022-02-28"},
});

client.GetRecommend("10");

```

--------------------------------

### Gorse Docker Images Overview

Source: https://gorse.io/docs/0.4/deploy/docker

Lists the official Docker images provided by Gorse for various components. Includes links to Docker Hub and badge information for version, size, and pull counts.

```APIDOC
Docker Image Table:

| Docker Image | Version | Image Size | Pulls |
| --- | --- | --- | --- |
| [gorse-master](https://hub.docker.com/r/zhenghaoz/gorse-master) | ![Docker Image Version (tag latest semver)](https://img.shields.io/docker/v/zhenghaoz/gorse-master/latest) | ![gorse-master](https://img.shields.io/docker/image-size/zhenghaoz/gorse-master) | ![Docker Pulls](https://img.shields.io/docker/pulls/zhenghaoz/gorse-master) |
| [gorse-server](https://hub.docker.com/r/zhenghaoz/gorse-server) | ![Docker Image Version (tag latest semver)](https://img.shields.io/docker/v/zhenghaoz/gorse-server/latest) | ![gorse-server](https://img.shields.io/docker/image-size/zhenghaoz/gorse-server) | ![Docker Pulls](https://img.shields.io/docker/pulls/zhenghaoz/gorse-server) |
| [gorse-worker](https://hub.docker.com/r/zhenghaoz/gorse-worker) | ![Docker Image Version (tag latest semver)](https://img.shields.io/docker/v/zhenghaoz/gorse-worker/latest) | ![gorse-worker](https://img.shields.io/docker/image-size/zhenghaoz/gorse-worker) | ![Docker Pulls](https://img.shields.io/docker/pulls/zhenghaoz/gorse-worker) |
| [gorse-in-one](https://hub.docker.com/r/zhenghaoz/gorse-in-one) | ![Docker Image Version (tag latest semver)](https://img.shields.io/docker/v/zhenghaoz/gorse-in-one/latest) | ![gorse-in-one](https://img.shields.io/docker/image-size/zhenghaoz/gorse-in-one) | ![Docker Pulls](https://img.shields.io/docker/pulls/zhenghaoz/gorse-in-one) |

Nightly Version:
Images tagged with `nightly` are built from the master branch.

Windows Container:
Images tagged with `*-windowsservercore` are built for the Windows container.
```

--------------------------------

### Gorse API Documentation

Source: https://gorse.io/docs/0.4/quick-start

This section details the Gorse API endpoints for managing feedback and retrieving recommendations. It includes request methods, parameters, expected payloads, and response formats.

```APIDOC
API Endpoints:

1. Insert User Feedback
   - Method: POST
   - Endpoint: /api/feedback
   - Description: Inserts feedback data for users and items into Gorse.
   - Headers:
     - Content-Type: application/json
   - Request Body:
     - Type: Array of JSON objects.
     - Each object represents a feedback entry and should contain:
       - FeedbackType (string): The type of feedback (e.g., "star", "click", "purchase").
       - UserId (string): The unique identifier for the user.
       - ItemId (string): The unique identifier for the item.
       - Timestamp (string): The time the feedback was given (e.g., "YYYY-MM-DD").
   - Example Request Body:
     [
         { "FeedbackType": "star", "UserId": "bob", "ItemId": "vuejs:vue", "Timestamp": "2022-02-24" },
         { "FeedbackType": "star", "UserId": "bob", "ItemId": "d3:d3", "Timestamp": "2022-02-25" }
     ]
   - Success Response:
     - Status Code: 200 OK
     - Body:
       - {"RowAffected": integer}: The number of feedback records inserted.
   - Example Success Response:
     {
      "RowAffected": 5
     }

2. Fetch Recommendations
   - Method: GET
   - Endpoint: /api/recommend/{UserId}
   - Description: Retrieves a list of recommended items for a specific user.
   - Parameters:
     - UserId (path parameter, string): The unique identifier for the user.
     - n (query parameter, integer, optional): The number of recommendations to return. Defaults to 10.
   - Example Request:
     curl http://127.0.0.1:8087/api/recommend/bob?n=10
   - Success Response:
     - Status Code: 200 OK
     - Body:
       - Array of strings: A list of recommended ItemIds.
   - Example Success Response:
     [
         "mbostock:d3",
         "nt1m:material-framework",
         "mdbootstrap:vue-bootstrap-with-material-design"
     ]

Note: Ensure Gorse is running and accessible at the specified host and port (e.g., http://127.0.0.1:8087).
```

--------------------------------

### Gorse Cluster Deployment with Docker Compose

Source: https://gorse.io/docs/0.4/deploy/docker

This Docker Compose configuration defines a Gorse cluster setup, including master, server, and worker nodes. It specifies dependencies on Redis for caching and MySQL for data storage, along with volume mounts for logs and data persistence. This allows for easy deployment and scaling of Gorse recommendation services.

```yaml
version: "3"
services:
  redis:
    image: redis
    restart: unless-stopped
    ports:
      - 6379:6379

  mysql:
    image: mysql/mysql-server
    restart: unless-stopped
    ports:
      - 3306:3306
    environment:
      MYSQL_ROOT_PASSWORD: root_pass
      MYSQL_DATABASE: gorse
      MYSQL_USER: gorse
      MYSQL_PASSWORD: gorse_pass
    volumes:
      - mysql_data:/var/lib/mysql

  # postgres:
  #   image: postgres:10.0
  #   ports:
  #     - 5432:5432
  #   environment:
  #     POSTGRES_DB: gorse
  #     POSTGRES_USER: gorse
  #     POSTGRES_PASSWORD: gorse_pass
  #   volumes:
  #     - postgres_data:/var/lib/postgresql/data

  # mongo:
  #   image: mongo:4.0
  #   ports:
  #     - 27017:27017
  #   environment:
  #     MONGO_INITDB_DATABASE: gorse
  #     MONGO_INITDB_ROOT_USERNAME: root
  #     MONGO_INITDB_ROOT_PASSWORD: password
  #   volumes:
  #     - mongo_data:/data/db

  # clickhouse:
  #   image: yandex/clickhouse-server:21.10
  #   ports:
  #     - 8123:8123
  #   environment:
  #     CLICKHOUSE_DB: gorse
  #     CLICKHOUSE_USER: gorse
  #     CLICKHOUSE_PASSWORD: gorse_pass
  #   volumes:
  #     - clickhouse_data:/var/lib/clickhouse

  worker:
    image: zhenghaoz/gorse-worker
    restart: unless-stopped
    ports:
      - 8089:8089
    command: >
      --master-host master --master-port 8086
      --http-host 0.0.0.0 --http-port 8089
      --log-path /var/log/gorse/worker.log
      --cache-path /var/lib/gorse/worker_cache.data
    volumes:
      - gorse_log:/var/log/gorse
      - worker_data:/var/lib/gorse
    depends_on:
      - master

  server:
    image: zhenghaoz/gorse-server
    restart: unless-stopped
    ports:
      - 8087:8087
    command: >
      --master-host master --master-port 8086
      --http-host 0.0.0.0 --http-port 8087
      --log-path /var/log/gorse/server.log
      --cache-path /var/lib/gorse/server_cache.data
    volumes:
      - gorse_log:/var/log/gorse
      - server_data:/var/lib/gorse
    depends_on:
      - master

  master:
    image: zhenghaoz/gorse-master
    restart: unless-stopped
    ports:
      - 8086:8086
      - 8088:8088
    environment:
      GORSE_CACHE_STORE: redis://redis:6379
      GORSE_DATA_STORE: mysql://gorse:gorse_pass@tcp(mysql:3306)/gorse
      # GORSE_DATA_STORE: postgres://gorse:gorse_pass@postgres/gorse?sslmode=disable
      # GORSE_DATA_STORE: mongodb://root:password@mongo:27017/gorse?authSource=admin&connect=direct
      # GORSE_DATA_STORE: clickhouse://gorse:gorse_pass@clickhouse:8123/gorse
    command: >
      -c /etc/gorse/config.toml
    volumes:
      - ./config/config.toml:/etc/gorse/config.toml
      - gorse_log:/var/log/gorse
      - master_data:/var/lib/gorse
    depends_on:
      - redis
      - mysql

volumes:
  worker_data:
  server_data:
  master_data:
  gorse_log:

```

--------------------------------

### Gorse TypeScript SDK Usage Example

Source: https://gorse.io/docs/0.4/api/typescript-sdk

Demonstrates how to create a Gorse client instance with an endpoint and API key, insert feedback data, and request recommendations. It showcases the core functionalities of the SDK.

```typescript
import { Gorse } from "gorsejs";

// Create the client.
const client = new Gorse({ endpoint: "http://127.0.0.1:8087", secret: "api_key" });

// Insert feedbacks.
await client.insertFeedbacks([
    { FeedbackType: 'star', UserId: 'bob', ItemId: 'vuejs:vue', Timestamp: '2022-02-24' },
    { FeedbackType: 'star', UserId: 'bob', ItemId: 'd3:d3', Timestamp: '2022-02-25' },
    { FeedbackType: 'star', UserId: 'bob', ItemId: 'dogfalo:materialize', Timestamp: '2022-02-26' },
    { FeedbackType: 'star', UserId: 'bob', ItemId: 'mozilla:pdf.js', Timestamp: '2022-02-27' },
    { FeedbackType: 'star', UserId: 'bob', ItemId: 'moment:moment', Timestamp: '2022-02-28' }
]);

// Get recommendation.
await client.getRecommend({ userId: 'bob', cursorOptions: { n: 10 } });

```

--------------------------------

### Gorse TypeScript SDK Usage Example

Source: https://gorse.io/docs/master/api/typescript-sdk

Demonstrates how to initialize the Gorse client with an endpoint and API key, insert multiple feedback entries, and retrieve recommendations for a user. It showcases asynchronous operations using async/await.

```TypeScript
import { Gorse } from "gorsejs";

// Create the client.
const client = new Gorse({ endpoint: "http://127.0.0.1:8087", secret: "api_key" });

// Insert feedbacks.
await client.insertFeedbacks([
    { FeedbackType: 'star', UserId: 'bob', ItemId: 'vuejs:vue', Timestamp: '2022-02-24' },
    { FeedbackType: 'star', UserId: 'bob', ItemId: 'd3:d3', Timestamp: '2022-02-25' },
    { FeedbackType: 'star', UserId: 'bob', ItemId: 'dogfalo:materialize', Timestamp: '2022-02-26' },
    { FeedbackType: 'star', UserId: 'bob', ItemId: 'mozilla:pdf.js', Timestamp: '2022-02-27' },
    { FeedbackType: 'star', UserId: 'bob', ItemId: 'moment:moment', Timestamp: '2022-02-28' }
]);

// Get recommendation.
await client.getRecommend({ userId: 'bob', cursorOptions: { n: 10 } });

```

--------------------------------

### Use Gorse Java SDK

Source: https://gorse.io/docs/master/api/java-sdk

Demonstrates how to create a Gorse client instance, insert feedback data, and retrieve recommendations. It shows the basic workflow for interacting with the Gorse recommendation engine using the Java SDK.

```Java
import io.gorse.gorse4j.*;

import java.util.List;

public class Main {

    public static void main(String[] args) {
        // Create a client.
        Gorse client = new Gorse("http://127.0.0.1:8087", "api_key");

        // Insert feedback.
        List<Feedback> feedbacks = List.of(
                new Feedback("read", "100", "300", "2022-11-20T13:55:27Z"),
                new Feedback("read", "100", "400", "2022-11-20T13:55:27Z")
        );
        client.insertFeedback(feedbacks);

        // Get recommendation.
        client.getRecommend("100");
    }
}
```

--------------------------------

### Gorse PHP SDK Usage Example

Source: https://gorse.io/docs/0.4/api/php-sdk

This example demonstrates how to use the Gorse PHP SDK. It shows how to create a client instance with an API endpoint and key, and then how to insert feedback data using the Feedback class and retrieve recommendations.

```php
$client = new Gorse("http://127.0.0.1:8087/", "api_key");

$rowsAffected = $client->insertFeedback([
    new Feedback("star", "bob", "vuejs:vue", "2022-02-24"),
    new Feedback("star", "bob", "d3:d3", "2022-02-25"),
    new Feedback("star", "bob", "dogfalo:materialize", "2022-02-26"),
    new Feedback("star", "bob", "mozilla:pdf.js", "2022-02-27"),
    new Feedback("star", "bob", "moment:moment", "2022-02-28")
]);

$client->getRecommend('10');
```

--------------------------------

### Install Python SDK from Source

Source: https://gorse.io/docs/master/api/python-sdk

Installs the Gorse Python SDK by cloning the repository and installing from the local source. This method is useful for developers contributing to the SDK or needing the latest unreleased features.

```bash
git clone https://github.com/gorse-io/PyGorse.git
cd PyGorse
pip install .
```

--------------------------------

### Start Gorse Services

Source: https://gorse.io/docs/master/deploy/docker

Command to start all services defined in the docker-compose.yml file in detached mode.

```shell
docker-compose up -d
```

--------------------------------

### Setup Gorse Service with NSSM (Windows PowerShell)

Source: https://gorse.io/docs/0.4/deploy/binary

This snippet shows the PowerShell commands for setting up Gorse as a service on Windows using NSSM. It includes creating directories, moving the executable and configuration, and configuring NSSM parameters for the Gorse service.

```powershell
New-Item -Type Directory -Path $env:ProgramFiles/Gorse/log
New-Item -Type Directory -Path $env:ProgramFiles/Gorse/data
```

```powershell
Move-Item config.toml -Destination $env:ProgramFiles/Gorse/bin
```

```powershell
nssm install Gorse $env:ProgramFiles\Gorse\bin\gorse-in-one.exe
nssm set Gorse AppParameters -c bin\config.toml --cache-path data\gorse.data
nssm set Gorse AppDirectory $env:ProgramFiles\Gorse
nssm set Gorse AppStdout $env:ProgramFiles\Gorse\log\gorse.log
nssm set Gorse AppStderr $env:ProgramFiles\Gorse\log\gorse.log
nssm start Gorse
```

--------------------------------

### ClickHouse DSN Example

Source: https://gorse.io/docs/0.4/config

Example of a Data Source Name (DSN) string for connecting to a ClickHouse database via HTTPS.

```APIDOC
https://user:password@host[:port]/database?param1=value1&...&paramN=valueN
```

--------------------------------

### Run Gorse-in-one

Source: https://gorse.io/docs/master/deploy/binary

Execute the Gorse-in-one binary. This requires a configuration file (e.g., config.toml) and specifies the path to this configuration file using the -c flag.

```shell
gorse-in-one -c config.toml
```

```shell
gorse-in-one -c config.toml
```

```powershell
& $env:ProgramFiles/Gorse/bin/gorse-in-one -c config.toml
```

--------------------------------

### Run Gorse Integration Tests

Source: https://gorse.io/docs/0.4/contribution-guide

Steps to run integration tests for Gorse. This involves first setting up Gorse using Docker Compose and then executing the Go tests with the 'integrate_test' tag enabled.

```bash
# Setup Gorse
docker-compose up -d

# Test
go test -tags='integrate_test' ./client/

```

--------------------------------

### Install Gorse Helm Chart with values.yaml

Source: https://gorse.io/docs/master/deploy/kubernetes

Installs the Gorse Helm chart by providing a custom configuration file named 'values.yaml' to specify deployment parameters.

```bash
helm install gorse -f values.yaml gorse-io/gorse
```

--------------------------------

### Install Gorse TypeScript SDK with yarn

Source: https://gorse.io/docs/master/api/typescript-sdk

Installs the Gorse TypeScript SDK package using yarn. This command is an alternative for projects managed with the yarn package manager.

```Shell
yarn add gorsejs
```

--------------------------------

### Install Gorse TypeScript SDK with npm

Source: https://gorse.io/docs/master/api/typescript-sdk

Installs the Gorse TypeScript SDK package using npm. This is the standard way to add the library to your Node.js or frontend project.

```Shell
npm install gorsejs
```

--------------------------------

### Feedback Insertion Response Body Example

Source: https://gorse.io/docs/0.4/api/restful-api

Example JSON structure for the response body after inserting or overwriting feedback, indicating the number of rows affected.

```JSON
{
  "RowAffected": 1
}
```

--------------------------------

### Feedback Response Body Example

Source: https://gorse.io/docs/0.4/api/restful-api

Example JSON structure for the response body when retrieving feedback, including a cursor for pagination and a list of feedback entries.

```JSON
{
  "Cursor": "fish",
  "Feedback": [
    {
      "Comment": "crocodilia",
      "FeedbackType": "bird",
      "ItemId": "fish",
      "Timestamp": "2020-02-02T20:20:02.02Z",
      "UserId": "crocodilia"
    },
    {
      "Comment": "crocodilia",
      "FeedbackType": "bird",
      "ItemId": "fish",
      "Timestamp": "2020-02-02T20:20:02.02Z",
      "UserId": "crocodilia"
    },
    {
      "Comment": "crocodilia",
      "FeedbackType": "bird",
      "ItemId": "fish",
      "Timestamp": "2020-02-02T20:20:02.02Z",
      "UserId": "crocodilia"
    }
  ]
}
```
Tokens:
Raw