Configuration

RDepot is configured through static YAML files.

Notation

This page occasionally uses period separators to denote the hierarchy of nested blocks for brevity. Additionally, the two styles of array syntax are used interchangeably.

Breaking changes in 2.0

Property naming convention

Since 2.0, some config properties moved to kebab-case in order to preserve consistency. The properties that have changed are the following:

api_token is now api-token
access_token is now access-token
allowed_characters is now allowed-characters
lifetime_default is now lifetime-default
lifetime_configurable is now lifetime-configurable
localStorage is now local-storage
maxRequestSize is now max-request-size

Make sure to update these if you upgrade.

Declarative mode

Additionally, managing repositories via the application configuration with declarative: false is no longer supported. Please set declarative: true to continue managing repositories via the application configuration.

Repository configuration files

Finally, configuring repositories in the application.yaml file using the repositories property is no longer supported. Every configured repository is expected to have its own configuration file, i.e. MyRepository.repository.yaml inside a directory configured with the additional-repository-configs.paths property. See below for more information. These configuration files use a property naming convention of camelCase instead of kebab-case in order to improve deserialization:

publication-uri is now publicationUri
server-address is now serverAddress
sync-interval is now syncInterval
generate-manuals is now generateManuals

Manager App

It is recommended to create a configuration file to override the default values of the RDepot manager application.

This files should be added to the same folder from where the manager app is run.

You can find up-to-date configuration examples on the Deployment page or in the integration tests of RDepot.

Repositories (declarative mode)

As an alternative to configuring repositories through the interface you can specify them in the configuration. This is also called declarative mode since it disables creating and editing repositories in the web UI and only allows declaring repositories in the application configuration.
This is especially useful for scripted deployments.

declarative: true
additional-repository-configs:
  paths:
  - /opt/rdepot/declared_repositories

In past versions of RDepot (before v2.0.0), repositories could be configured directly in the application.yaml file. However, this has changed and is no longer supported. The property additional-repository-configs.paths is a list of directories which can each contain zero or more repository configuration files.

A repository configuration file has a file name which ends in repository.yaml or repository.yml. We highly suggest to use the following naming convention: <repository-name>.repository.yaml, i.e. a repository with name MyRepository would be configured in the file with name MyRepository.repository.yaml.

The contents of repository configuration files are as follows:

name: MyRepository
publicationUri: http://mydomain.com/repo/MyRepository
serverAddress: http://oa-rdepot-repo:8080/MyRepository
published: false  # true is the default
technology: Python  # R is the default

For example, an R repository may have the following configuration file PublicR.repository.yaml:

name: PublicR
publicationUri: http://mydomain.com/repo/PublicR
serverAddress: http://oa-rdepot-repo:8080/PublicR
published: true
technology: R

For each repository the following fields should be specified:

name: repository name
publicationUri: the external uri of the repository
serverAddress: the internal address which the manager app uses to communicate with the repo server.

Optionally, configure whether the repository should by default be published or not:

published: true if the repository should be automatically published (default) or false if it shouldn’t be published at all

Additionally, configure whether the repository supports R or Python packages:

technology: R if the repository should support R packages (default) or Python if it should support Python packages (a combination of technologies in a single repository is not possible)

In past versions of RDepot (before v2.0.0), configuring repositories with declarative: false (default) did work.
However, to reduce complexity and unexpected behavior, configuring (or declaring) repositories in the configuration now only works when declarative mode is enabled (starting from RDepot v2.0.0).

External repository mirrors

Configuring external repository mirrors is not available in the interface (yet) and only works in tandem with the declarative repository configuration (see above). This is especially useful in the case where the RDepot application is hosted on the only host in the network with internet access, where regular client machines don’t have any external internet access but require external packages from i.e. CRAN or Bioconductor.

Please note that this feature is currently only available for R repositories and not for Python repositories.
Support for external Python repository mirrors is coming in a future release.

Example repository configuration file mirror-multiple.repository.yaml with external repository mirroring enabled:

name: mirror-multiple
publicationUri: http://mydomain.com/repo/mirror-multiple
serverAddress: http://oa-rdepot-repo:8080/mirror-multiple
mirrors:
- name: CRAN
  uri: https://cran.r-project.org
  syncInterval: * * 5 * * *
  type: tarball
  generateManuals: true
  packages:
  - name: ggplot2
    version: 3.3.2
  - name: plotly
    generateManuals: false
- name: Bioconductor-3.12
  uri: https://bioconductor.org/packages/3.12/bioc
  syncInterval: * * 5 * * *
  type: tarball
  generateManuals: false
  packages:
  - name: annotate
    version: 1.68.0
    generateManuals: true
- name: Bioconductor-release
  uri: https://bioconductor.org/packages/release/bioc
  syncInterval: * * 5 * * *
  type: tarball
  packages:
  - name: genefilter

One can configure multiple mirror configurations per repository. The uri parameter needs to be a valid URI where appending src/contrib/PACKAGES to the end of the URI leads to the PACKAGES file of the external repository. The syncInterval is an extended CRON-like expression, see the Spring documentation for more information on the syntax. Currently type is restricted to tarball. We might support source packages and other types in the future.

There are currently two types of package mirroring supported:

mirror a specific version of a package (only once)
mirror the latest version of a package (using the syncInterval)

Database

It is recommended to use a PostgreSQL-compatible database. Other SQL flavours may work but have not been tested.

You can configure access to your database in a db block:

db.driver : the database driver. Since the recommendation is to use postgres, this should be kept at org.postgresql.Driver
db.url : JDBC connection url
db.username: username/role to connect with
db.password: password to connect with

Authentication

The RDepot manager application supports multiple authentication backends. You can select the authentication method to use via the app.authentication field.

Simple Authentication

Users can be defined directly in the configuration file. To do so, select the simple authentication method. You can then define the users under app.simple:

app:
  authentication: simple
  simple:
    users:
      - login: einstein
        password: testpassword
      - login: tesla
        password: testpassword
      - login: galileo
        password: testpassword
      - login: newton
        password: testpassword
      - login: newbie
        password: testpassword
        name: New User

LDAP Authentication

This is no longer available since RDepot v2.0.0. Please use OpenID Connect and configure LDAP federation in your identity provider of choice. An example of this can be found in the RDepot web UI source code.

OAuth 2.0

OAuth 2.0 is the industry-standard protocol for authorization. OAuth 2.0 supports multiple authorization flows. The standard authorization flow applicable for web apps is three-legged (auth provider, client/application and user) and is based around tokens. This removes the need to store passwords and enables a single-sign-on experience.

To configure OAuth 2.0 in the RDepot manager application, the following properties can be set:

oauth2.jwk-set-uri: the endpoint where the provider’s public certificates can be found. This is used during the authorization process.
oauth2.login-field: the name of the OAuth 2.0 claim which holds the login (username) value
app.authentication: should be set to oauth2
app.oauth2.default.admins: array of default admins. For example: [ "admin" , "einstein", "newton" ]

oauth2:
  jwk-set-uri: http://keycloak:8080/realms/rdepot/protocol/openid-connect/certs
  login-field: preferred_username
app:
  authentication: oauth2
  oauth2:
    default:
      admins:
      - einstein

Logging

By default, information about various application events will be logged into the standard output stream of the process.

You can also send the log output to a file via the logging.file setting:

logging:
  file:
    rdepot.log

You can change the log level by using the logging.level.<component> setting, where <component> can be either of:

root: this affects all components
any specific component: e.g. org.springframework.web.filter.CommonsRequestLoggingFilter

A full discussion of all components is out-of-scope for this document.

Storage

storage.implementation: Currently only a single storage implementation is supported: local.
local-storage.max-request: Maximum request size

URL Context Path

Both the RDepot manager application and the RDepot repository application can be configured with a URL context path. To do so, you should add or update the following section in the respective application.yml configuration file. The following example configures a URL context path of /rdepot/app, whereas the default value is /:

server:
  servlet:
    context-path: /rdepot/app  # default is '/'

Package upload file size limit

By default, the file size limit of package uploads (submissions) is 100 MB. One can configure this limit in the application.yml file of the RDepot manager app.

spring:
  servlet:
    multipart:
      max-file-size: 100MB
      max-request-size: 100MB

The RDepot repository app also might need some additional configuration for publishing large packages:

spring:
  servlet:
    multipart:
      max-file-size: 100MB
      max-request-size: 100MB

in the respective application.yml file of the RDepot repository app.

Repository snapshots

RDepot can create snapshots of your repositories for every change that occurs on a repository (new packages, removed packages, etc.). This is handy for restoring previous versions of the repository (a feature that will be expanded on in the future). However, this feature is not complete yet and is disabled by default:

repository-snapshots: false

When set to false (default), the folder /opt/rdepot/generated should be removable by the RDepot process so please keep this in mind when mapping volumes in Docker or Kubernetes.

Disallow package and repository deletion

By default, users with the appropriate role are able to delete packages and repositories. However, in some situations, preservation of these resources is necessary at all times. In order to enforce preservation of these resources and to avoid any accidental deletions, a global configuration option is available to either allow (default value) or disallow package and repository deletion.

To disallow package deletion, set global property deleting.packages.enabled to false:

deleting:
  packages:
    enabled: false  # default is true

To disallow repository deletion, set global property deleting.repositories.enabled to false:

deleting:
  repositories:
    enabled: false  # default is true

Disallow replacing packages

By default, users are able to re-upload existing packages while optionally replacing the existing package in the process. However, in some situations, a certain instance of a package should remain unaltered at all times for reproducibility reasons. In order to enforce reproducibility and to avoid any accidental package replacements, a global configuration option is available to either allow (default value) or disallow replacing packages.

To disallow replacing packages, set global property replacing.packages.enabled to false:

replacing:
  packages:
    enabled: false  # default is true

Default user settings

As an administrator, one can configure the default user settings globally. Currently, these settings contain:

language: the default language in API responses and in the web UI
theme: the default theme in the web UI
page-size: the default page size when using the API list resources and in the tables in the web UI
supported-languages: the list of languages that a user can select as their default in the web UI
supported-themes: the list of themes that a user can select as their default in the web UI

The default configuration is currently the following:

default-user-configuration:
  language: en-US
  theme: light
  page-size: 10
  supported-languages:
  - en-US
  - pl-PL
  supported-themes:
  - light
  - dark

Sensitive Configuration

You can override sensitive configuration with environment variables.

E.g. api-token.secret can be overridden with API_TOKEN_SECRET.

Refer to the spring boot documentation on externalized configuration to learn more.

RDepot Web UI

It is recommended to use environment variables to override the default values of the RDepot web UI application.

You can find up-to-date configuration examples on the Deployment page or in the RDepot web UI source code.

Authentication

The RDepot web UI application supports multiple authentication backends. You can select the allowed authentication method to use via environment variables.

Please note that the authentication method in the web UI should match the authorization method in the RDepot manager app configuration.

Simple Authentication

If authentication is handled by the RDepot manager app, using the pre-defined users in the application configuration, then the following environment variables should be set: VITE_LOGIN_SIMPLE=true and VITE_LOGIN_OIDC=false.

OpenID Connect

OpenID Connect is a modern authentication protocol based on the OAuth 2.0 standard. OIDC supports multiple authentication flows. The standard authentication flow applicable for web apps is three-legged (auth provider, client/application and user) and is based around tokens. This removes the need to store passwords and enables a single-sign-on experience.

To configure OIDC in the RDepot web UI application, the following environment variables should be set:

VITE_LOGIN_SIMPLE: should be set to false
VITE_LOGIN_OIDC: should be set to true
VITE_OIDC_AUTHORITY: the URL of the OIDC provider
VITE_OIDC_CLIENT_ID: your client application’s identifier as registered with the OIDC provider
VITE_OIDC_REDIRECT_URI: the redirect URI of your client application to receive a response from the OIDC provider
VITE_OIDC_POST_LOGOUT_REDIRECT_URI: the URL to be used for logging out of the OpenID session (i.e. the end_session_endpoint)
VITE_OIDC_RESPONSE_TYPE: the type of response desired from the OIDC provider (default is code)
VITE_OIDC_SCOPE: the scope(s) being requested from the OIDC provider (default is openid)

VITE_LOGIN_SIMPLE=false
VITE_LOGIN_OIDC=true
VITE_OIDC_AUTHORITY=http://localhost/keycloak/realms/rdepot
VITE_OIDC_CLIENT_ID=rdepot
VITE_OIDC_REDIRECT_URI=http://localhost/auth
VITE_OIDC_POST_LOGOUT_REDIRECT_URI=http://localhost/logout
VITE_OIDC_RESPONSE_TYPE=code
VITE_OIDC_SCOPE=openid

URL Context Path

The RDepot web UI application can be configured with a URL context path. To do so, you should set the environment variable VITE_URL_PREFIX. The following example configures a URL context path of /rdepot/ui, whereas the default value is /: VITE_URL_PREFIX=/rdepot/ui.

Server Address

The public server address of the RDepot manager app should be set using the VITE_SERVER_ADDRESS environment variable.

Developer Mode

For additional notifications and messages, developer mode can be enabled. Please make sure that this mode is disabled in a production environment.

Enabling developer mode can be done by setting the environment variable VITE_DEV_MODE to true (default is false).