HMLR linked-data applications landing site

This repo provides the landing page experience for visitors to landregistry.data.gov.uk. The landing page provides links to the various open data services, and hosts the Qonsole app, which allows users to run SPARQL queries against the linked-data dataset.

Please see the other repositories in the HM Land Registry Open Data project for more details.

For more information about this project visit the wiki.

Contents

• Tech stack
• Developer setup
• Data API
• Running locally
• Testing
• E2E Testing
• Building and publishing
• Releasing
• Dependency maintenance

Tech stack

Layer	Technology
Backend	Ruby on Rails 8.1, served via Puma
Assets	Sprockets asset pipeline + Dart Sass
Templates	HAML
SPARQL UI	Qonsole (qonsole_rails gem)
Error tracking	Sentry
Metrics	Prometheus (prometheus-client, puma-metrics)

This is a server-rendered Rails application with no Node.js build tooling — there is no Vite and no Webpack. Node is present only to run Playwright E2E automations; it plays no part in the application build or asset pipeline.

Developer setup

1. Install Ruby

Use rbenv or asdf to install the version pinned in .ruby-version (currently 3.4.9).

With rbenv:

rbenv install        # reads .ruby-version automatically
gem install bundler

2. Authenticate with the private gem registry

The json_rails_logger, lr_common_styles, and qonsole_rails gems are hosted on the Epimorphics GitHub Package Registry. You need a GitHub Personal Access Token with the read:packages scope.

Configure Bundler with your token:

./bin/bundle config set --local rubygems.pkg.github.com epimorphics:<your-token>

3. Install dependencies

./bin/bundle install

No Node or Yarn installation is required.

4. Environment variables

.env.development contains sensible defaults for local development and is checked in — no copying required. The app will start without any further configuration.

To override a value, create .env.local and set it there. .env.local is gitignored.

Variable	Default	Purpose
API_SERVICE_URL	http://localhost:8888	Backing SPARQL/data API
PORT	3000	Rails server port
SENTRY_ENABLED	false	Enable Sentry error tracking
SENTRY_AUTH_TOKEN	—	Required only for production builds (source map upload)
SENTRY_API_KEY	—	Required only if SENTRY_ENABLED=true

Data API

The app queries a backing data API at API_SERVICE_URL (default http://localhost:8888). To run it locally, install Maven and follow the instructions in the lr-data-api repository, ensuring it listens on port 8888.

Running locally

./bin/rails server -p 3000

The app is served on port 3000 by default. Assets are compiled on the fly by Sprockets in development — no separate build step is needed.

Testing

./bin/rails test

View the coverage report after a test run:

open coverage/index.html

E2E testing

Playwright is used for end-to-end browser automation. Node is required only for this — it is not used in the application build.

Prerequisites: Node 24 via nvm:

nvm install   # reads .nvmrc automatically
nvm use

Install dependencies (yarn uses the yarnPath configuration and will resolve from a locally kept version in .yarn/releases/, no separate corepack step needed):

yarn install

Run against the local server (starts Rails automatically on port 3001):

yarn test:e2e

Run against a remote environment:

E2E_BASE_URL=https://staging.example.com yarn test:e2e

Optional HTTP basic auth for protected environments:

E2E_BASE_URL=https://staging.example.com \
E2E_USERNAME=user \
E2E_PASSWORD=secret \
yarn test:e2e

Interactive UI mode:

yarn test:e2e:ui

Open the last HTML report:

yarn test:e2e:report

The CI workflow (.github/workflows/e2e.yml) is workflow_dispatch only — it does not run automatically on push. Trigger it manually from the Actions tab, supplying the target URL.

Linting

./bin/bundle exec rubocop -a    # Ruby — auto-corrects safe offences

Building and publishing

The Makefile is scoped to the Docker image build and publish pipeline.

make image     # Build the Docker image (requires GitHub token configured)
make publish   # Push to AWS ECR
make vars      # Print all build variables
make tag       # Print the computed image tag
make version   # Print the application version

Variables can be overridden on the command line, e.g.:

STAGE=preprod make publish

Branch-to-environment mapping is defined in deployment.yaml. CI runs publish and deploy automatically on push via .github/workflows/publish-deploy.yml.

Releasing

This repository uses long-lived environment branches (preprod, prod) that are kept as strict fast-forward pointers to tagged commits on dev. CI deploys automatically on push, so promoting an environment is a case of fast-forwarding its branch and pushing.

Key invariant: environment branches always point to a tagged commit on dev's linear history. Direct pushes to environment branches are not permitted.

Standard release

1. Finish work on dev

Merge all feature branches into dev and ensure CI passes.

2. Bump the version and update the changelog

Edit app/lib/version.rb and CHANGELOG.md, then commit and push to dev:

git add app/lib/version.rb CHANGELOG.md
git commit -m "chore: release vx.y.z"
git push origin dev

3. Tag the release commit

git tag vx.y.z
git push origin vx.y.z

4. Promote each environment branch in turn

Fast-forward preprod first, verify the deployment, then repeat for prod:

git checkout preprod
git merge --ff-only vx.y.z
git push origin preprod

CI triggers automatically on push. Verify before promoting the next environment. If --ff-only is refused, the branch has diverged — investigate before proceeding.

git checkout prod
git merge --ff-only vx.y.z
git push origin prod

5. Optionally create a GitHub release

Go to Releases on the repository page, draft a new release from the tag, and publish.

---

Hotfix release

1. Branch off the current production tag

git checkout -b hotfix/vx.y.z vx.y.(z-1)

2. Make the fix, tag it, and push

git add <files>
git commit -m "fix: <description>"
git tag vx.y.z
git push origin hotfix/vx.y.z vx.y.z

3. Bring the fix into dev

Preferred — rebase:

git rebase hotfix/vx.y.z dev
git push --force-with-lease origin dev

Safe fallback — cherry-pick:

git checkout dev
git cherry-pick vx.y.z
git push origin dev

4. Promote environment branches to the hotfix tag

Same as a standard release — fast-forward preprod then prod, verifying each before moving to the next.

5. Clean up the hotfix branch

git branch -d hotfix/vx.y.z
git push origin --delete hotfix/vx.y.z

Dependency maintenance

./bin/bundle update --patch              # Update all gems to latest patch version
./bin/bundle outdated --only-explicit    # Check for outdated gems