Skip to main content

Quick Start

About 2 min

Quick Start

This guide walks you through the quickest way to setup a recommender system for GitHub repositories based on dataset from GitRecopen in new window. Make sure you have installed the following softwares at the beginning:

Setup Gorse

Gorse supports to be single node or multiple nodes. This section demonstrates how to setup a minimal usable Gorse single node via playground and a multiple nodes cluster via Docker Compose.

Option 1: Setup Gorse-in-one node via Playground

Use the following command to setup a Gorse all-in-one node.

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

Tips

For Gorse-in-one, the RESTful endpoint is http://127.0.0.1:8088open in new window.

Option 2: Setup Gorse Cluster via Docker Compose

There is an example docker-compose.ymlopen in new window consists of a master node, a server node and a worker node, a Redis instance, and a MySQL instance.

  1. Download docker-compose.ymlopen in new window and the config file config.tomlopen in new window.
# 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
  1. Setup the Gorse cluster using Docker Compose.
docker-compose up -d
Expected outputs
Creating network "gorse_default" with the default driver
Creating gorse_worker_1 ... done
Creating gorse_master_1 ... done
Creating gorse_mysql_1  ... done
Creating gorse_server_1 ... done
Creating gorse_redis_1  ... done
  1. Download the SQL file github.sqlopen in new window and import to the MySQL instance. This dataset consists of GitHub users, GitHub repositories and interactions between users and repositories.
# 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

There are three kinds of interactions (called "feedbacks" in Gorse) between users and repositories in this dataset.

Feedback TypeDescription
starA user "starred" a repository in GitHub
readA user read a repository in GitRecopen in new window
likeA user "liked" a repository in GitRecopen in new window

In the configuration file, "read" belongs to read_feedback_types while "star" and “like” belong to positive_feedback_types.

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

# The feedback types for read events.
read_feedback_types = ["read"]
  1. Restart the master node to reload imported data immediately.
docker-compose restart
Expected outputs
Restarting gorse_redis_1  ... done
Restarting gorse_mysql_1  ... done
Restarting gorse_master_1 ... done
Restarting gorse_server_1 ... done
Restarting gorse_worker_1 ... done

Get Recommendation

Gorse generate recommendations for users after feedbacks from users are inserted.

Open http://127.0.0.1:8088open in new window in browser and the dashboard summarizes all status and data in Gorse.

Wait for all tasks except "Searching collaborative filtering model" and "Searching click-through prediction model" completed.

Suppose Bob is a frontend developers who starred several frontend repositories in GitHub. We insert his star feedback to Gorse via the RESTful API.

read -d '' JSON << EOF
[
    { \"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\" }
]
EOF

curl -X POST http://127.0.0.1:8087/api/feedback \
   -H 'Content-Type: application/json' \
   -d "$JSON"
Expected outputs
{
 "RowAffected": 5
}

Then, fetch 10 recommended items from Gorse. We can found frontend related repositories are recommended for Bob.

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

Expected outputs:

[
    "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"
]