User Interface
short description
code
https://codebase.helmholtz.cloud/hmc/hmc-public/unhide/development/ui
🚧 under construction 🚧
about this documentation
This guide walks you through setting up the unhide-ui project on your local machine for development.
What is this project?
unhide-ui is the web interface for the Helmholtz Knowledge Graph (HKG). It lets users search and browse research entities — datasets, persons, institutions, software, events, instruments, documents, and data catalogs — that are indexed in an OpenSearch cluster.
It is a Next.js application written in TypeScript, with a built-in API layer that communicates with OpenSearch.
Prerequisites
Before you begin, make sure you have the following installed:
| Tool | Version | Notes |
|---|---|---|
| Node.js | 22+ | Check with node -v |
| pnpm | 10.25.0 | This project requires pnpm — do not use npm or yarn |
To install pnpm:
npm install -g pnpm@10.25.0
1. Clone the repository
git clone https://codebase.helmholtz.cloud/hmc/hmc-public/unhide/development/ui.git
cd ui
2. Install dependencies
pnpm install
3. Set up environment variables
The app requires environment variables to connect to the OpenSearch backend and other services. These are not committed to the repository.
Copy the example file and fill in the values:
cp .env.example .env.development.local
Then open .env.development.local and set the values. Reach out to a team member to obtain the actual values.
| Variable | Description |
|---|---|
NEXT_PRIVATE_OPENSEARCH_URL | URL of the OpenSearch cluster |
NEXT_PRIVATE_OPENSEARCH_USERNAME | OpenSearch username (optional if no auth) |
NEXT_PRIVATE_OPENSEARCH_PASSWORD | OpenSearch password (optional if no auth) |
NEXT_PUBLIC_QLEVER_URL | Public URL of the QLever SPARQL endpoint |
NEXT_PRIVATE_QLEVER_URL | Private URL of the QLever SPARQL endpoint |
NEXT_PUBLIC_SPARQL_URL | Public SPARQL endpoint URL |
NEXT_API_URL | Base URL for internal API calls |
NEXT_PUBLIC_DOC_URL | URL of the external documentation site |
NEXT_PUBLIC_BAD_DATA_PREFIX | URL prefix used to flag records with data quality issues |
NEXT_PUBLIC_SHOW_BANNER | Set to true to show the announcement banner, false to hide it |
Note: Variables prefixed with
NEXT_PUBLIC_are exposed to the browser. Variables prefixed withNEXT_PRIVATE_remain server-side only and are never sent to the client.
4. Run the development server
pnpm run dev
The app will be available at http://localhost:3000.
You can verify the API is running by visiting http://localhost:3000/api/health.
Available scripts
| Command | Description |
|---|---|
pnpm run dev | Start the development server with hot reload |
pnpm build | Create a production build |
pnpm start | Start the production server (requires a build first) |
pnpm test | Run all tests once |
pnpm test:watch | Run tests in watch mode |
pnpm lint | Run ESLint and auto-fix issues |
pnpm check | Run ESLint, TypeScript type-check, and Prettier check together |
pnpm prettier | Check and auto-format all files with Prettier |
Running with Docker
A Dockerfile and docker-compose.yaml are provided for containerised deployment.
docker compose up
The app will be available on port 3000.
For production Kubernetes deployment, refer to the project documentation site.
Next steps
- Read the Architecture Overview to understand how the codebase is structured.
- Read the API Reference to understand the available endpoints.
- Read the Contributing Guide before making changes.
