This document aims to answer questions on how to configure external dependencies and which public interfaces are offered by base-repo in a comprehensive way. It is meant to be used for getting an overview and guidance in addition to the official documentation, which is available at the official base-repo web page.
ℹ️ Note: This document applies to the base-repo version it is shipped with. If you have a specific version running, please refer to
INTERFACE.mdof this particular release.
External dependencies are third-party services that are required for base-repo to work properly or that can be added optionally to provide additional functionality. Typically, external dependencies require
additional software to be installed and configured, before they can be included in the base-repo configuration, which is typically done via the main configuration file application.properties.
A relational database is required by base-repo to store administrative metadata for resources and content information. If not configured properly, base-repo will fail to start.
- H2 In-Memory (driver included, used for testing, not recommended for production) Example
- H2 File-Based (driver included, used for basic Docker setup, not recommended for production) Example
- PostgreSQL (driver included, requires a running PostgreSQL server, used for production) PostgreSQL, Example
ℹ️ Note: Other relational databases, e.g., MariaDB, SQLite, or Oracle, may also work but require additional actions. To allow base-repo to connect, the source code repository must be cloned, an appropriate JDBC driver has to be added to
build.gradleand base-repo has be be compiled. Proper JDBC drivers are typically provided on the database's Web page. Afterwards, the database can be configured inapplication.propertiessimilar to PostgreSQL but with database-specific property naming. Please refer to the driver documentation for details.
Access to the local filesystem is required by base-repo to store and manage uploaded data. base-repo only needs access to a single folder, which can be located on the local hard drive or mounted, e.g., via NFS.
- see
application.propertiesDocumentation1, Documentation2
AMQP-based messaging is an optional feature of base-repo, which allows base-repo to emit messages about creation, modification, and deletion events related to resources and content information. These messages can be received by registered consumers and processed in an asynchronous way.
- RabbitMQ (dependencies included, serves as messaging distributor, requires a running RabbitMQ server) RabbitMQ, Documentation
By default, base-repo offers basic search via RESTful API by example document or certain query parameters. Optionally, enhanced search via a search index can be enabled and used for fine-grained and facetted search operations.
- Elasticsearch (dependencies included, serves as seach index, requires a running Elasticsearch server) [Elasticsearch] (https://www.elastic.co/de/elasticsearch/), Documentation, Example
By default, base-repo itself is open for all kinds of operations, i.e., read and write, where write access should be restricted on the user interface level, e.g., by a password-protected area for critical operations. Optionally, authentication and authorization via JSON Web Tokens (JWT) issued by a Keycloak instance, can be configured.
- Keycloak (dependencies included, serves as identity provider, requires a running Keycloak server) Keycloak, Documentation (TODO), Example
Public Interfaces are used to access base-repo in order to obtain its contents, typically this happens via HTTP/REST. Depending on the interface, special clients or protocols must be used to access a specific public interface.
The default way to access base-repo is via RESTful interfaces. They allow to create, update, and delete resources and content information, as well as upload and download data.
- Scripts
- Graphical frontends (frontend-collection/repo-management.html)
If Enhanced Search is enabled, an additional REST endpoint becomes available, which allows to tunnel search queries to the underlying Elasticsearch instance. The advantage for proxying Elasticsearch access is, that access restrictions enabled via Access Control are included in the query such that only results accessible by the caller are returned.
- Scripts
- Graphical frontends (frontend-collection/elastic-search-base-repo.html)
OAI-PMH is a standardized harvesting protocol that allows to build up external search indices that can be kept up to data by regular harvesting changes from an OAI-PMH source. For base-repo, OAI-PMH functionality can be optionally added via plugin.
ℹ️ Note: Currently, the plugin is only available from an internal repository, which will change in near future. Furthermore, the plugin might not work with the current version of base-repo, but will be revised as soon as it becomes publicly available.
DOIP is a novel protocol to provide generic access to digital resources. Instead of using HTTP-based communication, the protocol acts directly on top of TCP/IP and is therefore mainly relevant for special ecosystems.
ℹ️ Note: Currently, the plugin is only available from an internal repository, which will change in near future. Furthermore, the plugin might not work with the current version of base-repo, but will be revised as soon as it becomes publicly available.