Artificial Intelligence (AI) AWS

Gorse Recommender Engine on AWS User Guide

| Product: Gorse on AWS

Overview

This guide covers deploying and operating Gorse on AWS using cloudimg's pre-configured Amazon Machine Image. Gorse is an open source recommender system engine written in Go. You feed it users, items and feedback through a clean REST API and it returns personalized recommendations, with popular and latest non personalized fallbacks, all served from a single self contained process.

The image installs Gorse as the official single all in one gorse-in-one binary (master, server and worker in one process), backed by an embedded SQLite data and cache store on the instance disk, so there is no Redis and no separate database to run. The engine binds loopback only (127.0.0.1:8088) and nginx is the sole network facing surface, reverse proxying HTTP on port 80 and ready for you to add your TLS certificate. It is a CPU only engine with no GPU requirement.

Secure by default. Gorse ships upstream with an empty API key and empty dashboard credentials, which leaves both the REST API and the admin dashboard wide open. This image never boots in that state: a unique API key, dashboard password and admin key are generated on each instance's first boot and written to a root only file, and the engine is started only after those secrets are in place. There are no shared or default credentials and nothing usable is baked into the image. On first boot the appliance also refreshes itself to the newest Gorse release, so every launch runs current software.

The recommended security group for this listing opens port 22 (SSH) and port 80 (HTTP) only. Restrict both to your own trusted network, and place TLS in front of the engine before exposing it to the public internet.

Connecting to your instance

Connect over SSH as the default login user for your operating system variant, using the EC2 key pair you selected at launch:

OS variant SSH login user Example
Ubuntu 24.04 LTS ubuntu ssh -i your-key.pem ubuntu@<instance-public-ip>

The web dashboard is reached over HTTP at http://<instance-public-ip>/ and the REST API at http://<instance-public-ip>/api/.

Prerequisites

  • An AWS account with permission to launch EC2 instances and subscribe to AWS Marketplace products
  • An EC2 key pair for administrative SSH access
  • A security group allowing inbound TCP 80 (HTTP) from the networks that should reach the service, and 22 (SSH) from your management network only
  • A recommended instance type of m5.large or larger

Step 1: Launch from the AWS Marketplace

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

Step 2: Launch from the AWS CLI

Launch the image from the command line, restricting access with a security group of your own. Replace the placeholder values with your own before running:

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>/

Step 3: Retrieve your per instance secrets

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 shown redacted here):

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.

Step 4: Sign in to the dashboard

Browse to http://<instance-public-ip>/. You are redirected to the Gorse dashboard login.

The Gorse dashboard login page with the Gorse logo, a Welcome to Gorse dashboard heading, and Username and Password fields with a Login button

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.

The Gorse dashboard Overview showing stat cards for Users, Items, Feedback, Positive Feedback and Negative Feedback, a Recommendation Performance chart, and a Non personalized Recommendations panel, with a left sidebar of Overview, Tasks, Cluster, Users, Items, Advance, RecFlow and Settings

Step 5: Verify the deployment

Over SSH on the instance, confirm 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 self updates 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 call reads 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).

Step 6: Browse your data in the dashboard

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

The Gorse dashboard Items view listing items in a table with ID, Categories, Hidden, Timestamp, Labels and Description columns, a search box, and per row view and delete actions

Step 7: Use the REST API from your application

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.

Step 8: Monitor background training tasks

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

The Gorse dashboard Tasks view listing All Tasks including Load Dataset, Generate recommendation and Collect Garbage in Cache, each marked Complete with a green progress bar and start and finish timestamps

Step 9: Enable TLS for production

The engine is fronted by nginx 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 enabling TLS, update your security group to allow 443, redirect 80 to HTTPS, and update the URLs your applications use.

Security notes

  • The API key, dashboard password and admin key are generated per instance on first boot and stored only in /root/gorse-info.txt (mode 0600, owned by root). Rotate them by regenerating the values in /etc/gorse/config.toml and restarting gorse.service.
  • Gorse binds loopback only (127.0.0.1:8088); nginx on port 80 is the sole network facing surface. Keep the security group restricted to the networks that need access, and place TLS in front before exposing the service publicly.
  • The image ships with no data and no usable credential. The engine will not start until first boot has written per instance secrets.
  • Keep the instance patched. The dashboard footer links to the Gorse documentation and API reference.

Support

cloudimg provides 24/7 technical support for this product by email and live chat. Our engineers help with deployment, securing the API, enabling a real domain and CA signed certificate, integrating your application through the REST API and client libraries, and recommender tuning.

  • Email: support@cloudimg.co.uk
  • Live chat: available 24/7