EOSC Data Commons Frontend

A web application for searching scientific datasets using natural language queries. This application works with the EOSC Data Commons Search server to help you discover scientific datasets through AI-powered search.

What You Need First

Before using this application, you need to install these programs on your computer:

1. Node.js (version 20 or newer)

   • Download and install from the official website
   • This includes npm (package manager) automatically
   • Development version used: Node.js 24.3.0
   • Minimum required: Node.js 20.x LTS or newer

2. Git

   • Download and install from the official website
   • Needed to download the code

3. EOSC Data Commons MCP server

   • Download and set up the backend server
   • Must be running on port 8000 for this frontend to work

You can check if they're installed by opening Terminal (Mac) or Command Prompt (Windows) and running these commands one by one:

Check Node.js version:

node --version

Check npm version:

npm --version

Check Git version:

git --version

How to Use

Step 1: Download the Code

Open Terminal (Mac) or Command Prompt (Windows) and run these commands one by one:

Clone the repository:

git clone https://github.com/EOSC-Data-Commons/matchmaker.git

Navigate to the project folder:

cd matchmaker

Install dependencies:

npm install

Note

This repository uses a project-level npm config in .npmrc: in-release-age=3. It tells npm to avoid package versions newer than 3 days at installation time, to reduce exposure to very recent malicious package publishes. If your npm version does not support this config, npm may warn and ignore it.

Step 2: Set Up the Backend (EOSC Data Commons search server)

Follow the instructions in the backend README to set up and run the server. The frontend expects the backend to be running on port 8000 by default.

Note

If you are running the backend with Docker and encounter an error of HTTP 401, related to SEARCH_API_KEY=SECRET_KEY_YOU_CAN_USE_IN_FRONTEND_TO_AVOID_SPAM, try removing or commenting out the SEARCH_API_KEY line in your backend .env file. The backend does not require this key unless you want to restrict API access.

Step 3: Start the Frontend

Run this command to start the frontend:

npm run dev

The application will open at http://localhost:5173

Authenticate with GitHub Container Registry (GHCR)

Before pulling images from GHCR, you may need to log in. Use the following command:

docker login ghcr.io

You will be prompted for your GitHub username and a personal access token with appropriate permissions (use as password).

For more details, see the official GitHub documentation:
https://docs.github.com/packages/working-with-a-github-packages-registry/working-with-the-container-registry

Run with Docker (Alternative to Local Node.js)

If you prefer not to install Node.js and npm, you can run the frontend directly using Docker. The backend server must still be running and accessible (see above).

Pull the Docker image

You can pull the latest published image from GitHub Container Registry:

docker pull ghcr.io/eosc-data-commons/matchmaker-frontend:latest

Or pull a specific version (replace <version> with the version you want, e.g., 1.2.3):

docker pull ghcr.io/eosc-data-commons/matchmaker-frontend:<version>

Run the Docker container

To run the frontend container and map it to your local port 5173:

docker run -p 5173:80 ghcr.io/eosc-data-commons/matchmaker-frontend:latest

• The app will be available at http://localhost:5173
• Make sure your backend server is running and accessible to the container (default: http://localhost:8000)

Note

If running backend and frontend in separate containers, you may need to adjust CORS or network settings for them to communicate.

Coordinator server

The matchmaker talks to backend services such as data-player, tool registry and file fetcher through the coordinator server. The messages in between follow the same protobuf as the contract. Matchmaker implements the client side of grpc in TypeScript by grpc-js. To keep the protobuf in sync with the coordinator code base and avoid the contract going out of sync during local development, the coordinator code base (called req-packager for historical reasons) is set as a submodule in the repo.

For a developer, clone the repo by:

git clone --recurse-submodules https://github.com/EOSC-Data-Commons/matchmaker.git

If you already cloned the project and forgot --recurse-submodules, you can combine the git submodule init and git submodule update steps by running git submodule update --init. To also initialize, fetch and checkout any nested submodules, you can use the foolproof git submodule update --init --recursive.

Check https://git-scm.com/book/en/v2/Git-Tools-Submodules for more information for submodule management.

grpc codegen

Generate the TypeScript code that holds grpc related types and functions by:

npx protoc \
  --plugin=./node_modules/.bin/protoc-gen-ts_proto \
  --ts_proto_out=./src/lib/server/generated \
  --ts_proto_opt=outputServices=grpc-js,esModuleInterop=true,env=node,useOptionals=messages \
  --proto_path=./req-packager/proto \
  ./req-packager/proto/coordinator.proto

This will generate a ./src/lib/server/generated/coordinator.ts file that contains all types to be implemented for a client.

data flow

UI frontend pages/FooPage.tsx -- lib/coordinatorApi.ts (implement wrapper of request call of /api/foobar...)

Majorly maintained by @ritwikshanker.

<---->

UI server server.ts -- lib/server/grpcClient.ts (grpc client run on the UI server talk to grpc server deployed by req-packager).

Majorly maintained by @unkcpz

<--HTTP/2-->

a coordinator server runs as a binary (as grpc server) which hides the backend services from UI.

Majorly maintained by @unkcpz as request packager (a.k.a. coordinator under matchmaker context)

File preview

The eye icon on a dataset file opens a preview. Despite living under /api/coordinator/*, GET /api/coordinator/file-preview is implemented in server.ts and is not proxied to the coordinator: the UI server fetches the repository's download URL itself and streams back a capped chunk (64 KB for text and CSV, 25 MB for images and PDFs, with Range passed through so the browser PDF viewer can seek). Previews therefore leave from the server's IP rather than the user's, which is what lets them work at all, since repository download endpoints send no CORS headers.

The proxy only fetches URLs it signed itself. /api/coordinator/files attaches a previewSig to every file it returns (src/lib/server/previewSigning.ts) and the preview route verifies it. This must not be replaced with an in-memory allowlist: production runs pm2 in cluster mode, so the worker that serves /files is usually not the one that serves /file-preview. Signatures last 24 hours; an expired one returns 410 and the UI asks the user to reload, anything unsigned or tampered with returns 403.

A signature proves the server issued the URL, not that the URL is safe to fetch, since /files signs whatever download URL the coordinator returns for a caller-supplied dataset handle. src/lib/server/previewUrlGuard.ts therefore resolves the hostname and requires every resolved address to be public, checked again on each redirect hop, so a name pointing at loopback, RFC1918 or 169.254.169.254 is refused.

Deployment settings

Setting	Why it matters
PREVIEW_URL_SECRET	Signing key. Only needed if the frontend runs as more than one container: the pm2 workers inside a single container agree on a generated key by themselves. Use a random 32+ byte string.
trust proxy	The 100 requests per minute preview limit keys on req.ip. Behind a reverse proxy that is the proxy's address, so every user shares one bucket unless Express is told the real topology. Configure it deliberately, since trusting forwarded headers from an untrusted hop lets a caller forge their source address and evade the limit.

How to Search

1. Open the application in your web browser
2. Type your search in plain English, for example:
   • "data about diabetes research in Europe"
   • "climate change temperature data from 2000 to 2020"
3. Press Enter or click the search button
4. Browse through the results

Need Help?

If something doesn't work:

1. Make sure the backend server is running first
2. Check that Node.js and Git are properly installed
3. Try closing and reopening your terminal/command prompt