jskos-server-ui

A Vue 3 application providing a web-based frontend for jskos-server instances. Browse JSKOS data such as terminologies, concepts, mappings, concordances, or annotations via any compatible JSKOS Server. The application is not tied to a specific instance and can connect to any server at runtime.

Features

• Connect to any jskos-server instance at runtime
• Overview dashboard for terminologies, mappings, concordances, and annotations
• Runtime configuration without rebuilding

Technology

• Vue 3 with Composition API (<script setup>)
• Vite for build tooling
• Pinia for state management
• Vue Router
• cocoda-sdk for all JSKOS Server API communication
• jskos-vue for JSKOS-specific UI components
• Bootstrap 5 and bootstrap-vue-next for basic layout and UI

Project structure

src/
├── components/        # Shared UI components
├── composables/       # Reusable Vue composables
├── router/            # Vue Router configuration
├── stores/            # Pinia stores
├── utils/             # Utility functions
├── views/             # Page-level view components
└── assets/styles/     # Global styles based on Cocoda and Bootstrap
public/
└── config.json        # Runtime configuration
docker/
├── config.json        # Runtime config for Docker deployments
└── nginx.conf         # nginx configuration for the production container

Installation

Requires Node.js 22 or higher.

npm install

Development

npm run dev

Testing

Unit tests use Vitest with happy-dom and @vue/test-utils:

npm test            # Run all tests once
npm run test:watch  # Watch mode
npm run coverage    # Run coverage report

Coverage is reported to Codecov on every CI run.

Build

npm run build

The production build is written to dist/.

Configuration

Runtime configuration is loaded from public/config.json at startup. This file is not bundled into the application and can be replaced at deploy time without rebuilding.

{
  "defaultServer": "http://localhost:3000",
  "footer": {
    "links": [
      { "label": "Imprint", "url": "https://example.org/imprint" },
      { "label": "Privacy", "url": "https://example.org/privacy" },
      { "label": "Accessibility", "url": "https://example.org/accessibility" }
    ]
  }
}

| Property | Type | Description | | --------------- | ------ | ----------------------------------------- | | defaultServer | string | JSKOS Server URL loaded on startup | | footer.links | array | Footer navigation links (label + url) |

Deployment

Docker Compose (recommended for production)

A ready-to-use docker-compose.yml is included in the root of this repository. It starts jskos-server-ui, jskos-server, and MongoDB.

Quick start:

docker compose up -d

The UI is then available at http://localhost:8080, jskos-server at http://localhost:3000.

Configuration:

docker/config.json is mounted into the container at startup. Edit it to configure:

{
  "defaultServer": "http://localhost:3000",
  "footer": {
    "links": [{ "label": "Imprint", "url": "https://example.org/imprint" }]
  }
}

Docker (standalone)

To run only the UI against an existing jskos-server instance:

docker run -p 8080:80 \
  -v /path/to/config.json:/usr/share/nginx/html/config.json:ro \
  ghcr.io/gbv/jskos-server-ui:main

Contributing

Contributions are welcome. Please follow the existing code conventions:

• All code, comments, and commit messages in English
• Use Conventional Commits for commit messages (enforced by commitlint)
• Use cocoda-sdk for all API calls (no direct calls to jskos-server)
• Check jskos-vue and bootstrap-vue-next before writing custom UI components

Releases are automated via semantic-release on every push to main.

Related projects

• jskos-server (backend server this application connects to)
• jskos-vue (Vue 3 component library for JSKOS data)
• cocoda-sdk (JavaScript SDK for JSKOS APIs)

License

MIT, see LICENSE for details.