Gorse

Search the Marketplace for Gorse on Ubuntu 24.04 and choose your VM size.

Attach a network security group (NSG) that allows TCP 22 (SSH) from your management network. Also allow TCP 80 and 443 (the API and dashboard) from the networks and applications that need to reach it.

In production, front port 80 with TLS (see Step 8).

RG="gorse-prod"; LOCATION="eastus"; VM_NAME="gorse-01" IMAGE_URN="sac1647283583153:gorse-ubuntu-24-04:default:latest" SSH_KEY="$(cat ~/.ssh/id_rsa.pub)" az group create --name "$RG" --location "$LOCATION" az network vnet create -g "$RG" --name gorse-vnet --address-prefix 10.90.0.0/16 --subnet-name gorse-subnet --subnet-prefix 10.90.1.0/24 az network nsg create -g "$RG" --name gorse-nsg az network nsg rule create -g "$RG" --nsg-name gorse-nsg --name allow-ssh --priority 100 \
  --source-address-prefixes "<your-mgmt-cidr>" --destination-port-ranges 22 --access Allow --protocol Tcp az network nsg rule create -g "$RG" --nsg-name gorse-nsg --name allow-web --priority 110 \
  --source-address-prefixes "<your-mgmt-cidr>" --destination-port-ranges 80 443 --access Allow --protocol Tcp
# Accept the Marketplace terms once per subscription (required before the first CLI deploy)
az vm image terms accept --urn sac1647283583153:gorse-ubuntu-24-04:default:latest
az vm create -g "$RG" --name "$VM_NAME" --image "$IMAGE_URN" \
  --size Standard_B2s --storage-sku StandardSSD_LRS \
  --admin-username azureuser --ssh-key-values "$SSH_KEY" \
  --vnet-name gorse-vnet --subnet gorse-subnet --nsg gorse-nsg --public-ip-sku Standard

ssh azureuser@<vm-ip>

Gorse listens on loopback 127.0.0.1:8088, and nginx fronts it on port 80. The health endpoint is public, and every other API endpoint requires your key.

sudo systemctl start gorse nginx 2>/dev/null || true
sudo systemctl is-active gorse nginx ss -tln | grep -E ':80 |127.0.0.1:8088' echo "health -> HTTP $(curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1/api/health/ready)"

You should see both services active, the listening sockets, and HTTP 200 from the health endpoint.

Your API key, dashboard password and admin key were generated on this VM's first boot and stored in a root-only file. Read them and keep them secret. Then confirm that the REST API rejects an unauthenticated request and accepts your key.

sudo ls -l /root/gorse-info.txt echo "no key -> HTTP $(curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1/api/users)"
KEY=$(sudo grep '^GORSE_API_KEY=' /root/gorse-info.txt | cut -d= -f2-)
echo "with key -> HTTP $(curl -s -o /dev/null -w '%{http_code}' -H "X-API-Key: $KEY" http://127.0.0.1/api/users)"

The info note is owned root:root with mode 0600.

An unauthenticated call to /api/users returns 401. The same call with your X-API-Key header returns 200, because the engine enforces the key on every /api/* endpoint except the public health checks.

Load your API key into a shell variable, then send Gorse a few users, items and feedback events. Items carry categories and a timestamp. Feedback records that a user starred an item.

Gorse serves the latest items straight from the store. It returns per-user recommendations, falling back to the latest items until the collaborative filtering model has trained on your feedback.

KEY=$(sudo grep '^GORSE_API_KEY=' /root/gorse-info.txt | cut -d= -f2-) H1="X-API-Key: $KEY"; H2="Content-Type: application/json";
TS=$(date -u +%Y-%m-%dT%H:%M:%SZ)
curl -s -X POST http://127.0.0.1/api/users -H "$H1" -H "$H2" \
  --data '[{"UserId":"alice","Labels":{}},{"UserId":"bob","Labels":{}}]' >/dev/null
curl -s -X POST http://127.0.0.1/api/items -H "$H1" -H "$H2" --data "[ {\"ItemId\":\"movie_inception\",\"Categories\":[\"scifi\"],\"Timestamp\":\"$TS\",\"Labels\":{}}, {\"ItemId\":\"movie_matrix\",\"Categories\":[\"scifi\"],\"Timestamp\":\"$TS\",\"Labels\":{}}, {\"ItemId\":\"movie_coco\",\"Categories\":[\"animation\"],\"Timestamp\":\"$TS\",\"Labels\":{}}]" >/dev/null
curl -s -X POST http://127.0.0.1/api/feedback -H "$H1" -H "$H2" --data "[ {\"FeedbackType\":\"star\",\"UserId\":\"alice\",\"ItemId\":\"movie_inception\",\"Timestamp\":\"$TS\"}, {\"FeedbackType\":\"star\",\"UserId\":\"alice\",\"ItemId\":\"movie_matrix\",\"Timestamp\":\"$TS\"}, {\"FeedbackType\":\"star\",\"UserId\":\"bob\",\"ItemId\":\"movie_inception\",\"Timestamp\":\"$TS\"}]" >/dev/null echo "latest items: $(curl -s -H "$H1" 'http://127.0.0.1/api/latest?n=5' | jq -r '[.[].Id] | join(", ")')" echo "recommend for alice: $(curl -s -H "$H1" 'http://127.0.0.1/api/recommend/alice?n=5' | jq -r 'join(", ")')"

GET /api/latest returns the items you just inserted, and GET /api/recommend/alice returns a non-empty list of recommended item IDs.

As more feedback accumulates, Gorse's background tasks train the collaborative filtering model. The personalized recommendations then become tailored to each user's history.

Gorse ships a web dashboard for inspecting your data, recommendations and background tasks. It is served on the same port as the API and is protected by the per-VM dashboard login. Confirm that it is reachable and requires authentication.

echo "login page -> HTTP $(curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1/login)"
echo "dashboard -> HTTP $(curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1/)"

The login page returns 200. A request to the dashboard root returns 302, which redirects an unauthenticated visitor to the login form.

In a browser, open http://<vm-ip>/ and sign in as admin with the GORSE_DASHBOARD_PASSWORD value from /root/gorse-info.txt.

Once you are signed in, the Overview page summarizes how many users, items and feedback events the recommender knows about, with recommendation performance over time.

The Items page lists the catalogue the recommender serves, with each item's categories, timestamp and labels.

The Users page lists the users known to the recommender. Each row links through to that user's personalized recommendations.

nginx fronts the API and dashboard on port 80 and is ready for TLS. Point a DNS record at the VM, then obtain a certificate with certbot and let certbot configure nginx for port 443.

sudo apt-get update && sudo apt-get install -y certbot python3-certbot-nginx
sudo certbot --nginx -d your-domain.example.com

After the certificate is issued, restrict the NSG so that only 443 (and 22 from your management network) is reachable. Then use the API and dashboard over https://your-domain.example.com/.

• Find the Gorse listing in AWS Marketplace. Choose Continue to Subscribe, then Continue to Configuration, then Continue to Launch.
• Select the Ubuntu 24.04 delivery option, your Region, an instance type (m5.large or larger) and your EC2 key pair.
• For the security group, allow inbound 80 from your users and restrict 22 to your management network.
• Launch the instance. When it is running, browse to http://<instance-public-ip>/.

Launch the image from the command line, restricting access with a security group of your own. Replace the example AMI ID, key name and security group ID with your own values before you run the command:

aws ec2 run-instances \
  --image-id <ami-id-from-listing> \
  --instance-type m5.large \
  --key-name my-key \
  --security-group-ids sg-yourgroup \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=gorse}]'
# when the instance is running, browse to http://<public-ip>/

Gorse's REST API requires an API key, and the dashboard requires a login. Both, plus an admin key and the resolved URLs, are generated uniquely on this instance's first boot and written to a root-only file. Retrieve them over SSH:

sudo cat /root/gorse-info.txt

The file lists the values your applications and operators need. Secrets are redacted in this example:

GORSE_API_KEY=<redacted> GORSE_ADMIN_API_KEY=<redacted> GORSE_DASHBOARD_USER=admin GORSE_DASHBOARD_PASSWORD=<redacted> GORSE_URL=http://<instance-public-ip>/ GORSE_API_URL=http://<instance-public-ip>/api/

Keep this file secret. No two instances share these values, and none is baked into the image.

Browse to http://<instance-public-ip>/. Gorse redirects you to the dashboard login.

Sign in with the username admin and the GORSE_DASHBOARD_PASSWORD from your info file. The Overview opens, with live counts of users, items and feedback, a recommendation performance chart, and non-personalized recommendation lists.

Over SSH on the instance, confirm that the services are up, the engine is the expected version, the health endpoint is ready, and the API key is enforced.

Both services are active:

systemctl is-active gorse.service nginx.service

active active

The engine is the pinned Gorse release. Each instance also updates itself to the newest release on first boot:

/usr/local/bin/gorse-in-one --version

Version: 0.5.11 API version: v0.2.7 Go version: go1.26.4 OS/Arch: linux/amd64

The health endpoint reports the data and cache stores connected:

curl -s http://127.0.0.1/api/health/ready

{ "Ready": true, "DataStoreConnected": true, "CacheStoreConnected": true }

The REST API rejects an unauthenticated request (401) and accepts your per-instance key. The following calls read the latest items back. Substitute the GORSE_API_KEY from your info file for <your-api-key>:

curl -s -o /dev/null -w 'unauthenticated: %{http_code}\n' http://127.0.0.1/api/latest
curl -s -H "X-API-Key: <your-api-key>" "http://127.0.0.1/api/latest?n=5"

unauthenticated: 401 [{"Id":"demo_item_5","Score":...},{"Id":"demo_item_4","Score":...}, ... ]

On a freshly launched instance, the datastore is empty until you insert your own data (Step 7).

Use the dashboard's Items, Users and Advance views to browse and search the data you have loaded, inspect individual records, and review recommendations.

Your application talks to Gorse over the REST API, passing your key in the X-API-Key header. Insert users, items and feedback, then request recommendations.

Replace YOUR_API_KEY with your GORSE_API_KEY and <instance-public-ip> with your instance address:

# insert an item curl -s -X POST "http://<public-ip>/api/items" \
  -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '[{"ItemId":"item_42","IsHidden":false,"Categories":["news"],"Timestamp":"2026-07-24T00:00:00Z","Labels":{},"Comment":"example"}]'
# record positive feedback from a user curl -s -X POST "http://<public-ip>/api/feedback" \
  -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '[{"FeedbackType":"star","UserId":"user_1","ItemId":"item_42","Timestamp":"2026-07-24T00:00:00Z","Value":1}]'
# get recommendations for a user curl -s -H "X-API-Key: YOUR_API_KEY" "http://<public-ip>/api/recommend/user_1?n=10"

Gorse serves collaborative filtering and content-aware recommendations, item-to-item and user-to-user neighbors, session-based recommendations, and latest and popular non-personalized lists.

Personalized results appear once the background training tasks have run over your data.

The Tasks view shows Gorse's background jobs, with their status, timing and progress. The jobs include loading the dataset, generating recommendations and cache maintenance.

nginx fronts the engine on port 80 and is ready for your certificate. For a production deployment, point a domain name at the instance and add a CA-signed certificate, for example with the ACME client of your choice:

# point http://<your-domain> at this instance first, then obtain a certificate
sudo certbot --nginx -d <your-domain>

After you enable TLS, update your security group to allow 443 and redirect 80 to HTTPS. Then update the URLs your applications use.