# Quick Start

This guide walks you through the quickest way to setup a recommender system for GitHub repositories. Make sure you have installed 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 All-in-one node via Playground

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

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

# Option 2: Setup Gorse Cluster via Docker Compose

There is an example docker-compose.yml (opens new window) consists of a master node, a server node and a worker node, a Redis instance, and a MySQL instance.

# Create a new directory
mkdir gorse
cd gorse

# Download docker-compose.yml and config.tom
wget https://raw.githubusercontent.com/zhenghaoz/gorse/master/docker/docker-compose.yml
wget https://raw.githubusercontent.com/zhenghaoz/gorse/master/docker/config.toml
  • 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
  • Download the SQL file github.sql (opens 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 Type Description
star A user "starred" a repository in GitHub
read A user read a repository in GitRec (opens new window)
like A user "liked" a repository in GitRec (opens 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"]
  • Restart the master node to apply imported data.
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.

  • 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. The next page lists the available methods in Gorse.
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
}
  • 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"
]

A complete example to build a recommender system is discussed in GitRec, The Live Demo, which is useful to learn Gorse.