Configuration Reference

This page provides a reference of configuration helpers available in NRP-based repositories through the oarepo.config module.

configure_generic_parameters

A comprehensive setup helper that initializes a broad set of repository-wide configuration defaults.

It covers core aspects such as site URLs, authentication, security headers, localization, database, search, cache, job backends, file storage, and RDM-specific features.

Use this as a baseline initializer for a NRP repository before applying any of your custom config overrides.

Defined in oarepo/config/generic_parameters.py.

Parameters

The helper reads additional environment/variable flags and exposes many other optional behaviors; consult the implementation for the full list.

Effect

Calling configure_generic_parameters() has a wide-ranging impact on application configuration:

Application & Site URLs

• Defines SITE_UI_URL and SITE_API_URL using either environment-provided values or constructed defaults from host/port.
• Sets APP_ALLOWED_HOSTS to allow local access (0.0.0.0, localhost, 127.0.0.1).

Security

• Constructs the baseline APP_DEFAULT_SECURE_HEADERS dictionary — CSP defaults, HTTPS enforcement, frame options, cookie security, HSTS. Appends the S3 endpoint to default-src when S3 storage is configured. The value is then extended by configure_ui (license badges, Matomo). See Security headers for the full defaults and how to customize them.
• Enables secure cookies (SESSION_COOKIE_SECURE=True) and sets sane Strict-Transport-Security defaults.
• Enables local login and fine-grained security features (registration, password recovery, confirmation) via environment toggles (INVENIO_SECURITY_*).
• Configures rate limits for guest and authenticated users (RATELIMIT_GUEST_USER, RATELIMIT_AUTHENTICATED_USER).

Authentication

• Enables OAuth/autologin redirects (OAUTHCLIENT_AUTO_REDIRECT_TO_EXTERNAL_LOGIN).
• Defines empty OAUTHCLIENT_REMOTE_APPS ready to be populated with external identity providers.
• Sets ACCOUNTS_LOGIN_VIEW_FUNCTION to auto-redirect when single external login is configured.

Database

• Constructs SQLALCHEMY_DATABASE_URI from INVENIO_DATABASE_* environment variables if not provided directly.
• Uses PostgreSQL by default.

Internationalization

• Sets default locale (BABEL_DEFAULT_LOCALE="en") and timezone (Europe/Prague).
• Registers available UI languages from the languages argument into I18N_LANGUAGES.

File Storage & S3

• Defaults to S3-based storage with fallback to local:
  • FILES_REST_STORAGE_FACTORY = "invenio_s3.s3fs_storage_factory"
  • Constructs S3_ENDPOINT_URL, S3_ACCESS_KEY_ID, and S3_SECRET_ACCESS_KEY.
• Adds S3 endpoint to CSP’s default-src.
• Defines FILES_REST_STORAGE_CLASS_LIST and default storage class.
• Sets file serving cache max-age (SEND_FILE_MAX_AGE_DEFAULT = 300).

User Profiles

• Allows editing of profile info (USERPROFILES_READ_ONLY = False).

Search

• Configures OpenSearch connection (SEARCH_INDEX_PREFIX, SEARCH_HOSTS, SEARCH_CLIENT_CONFIG).
• Supports SSL and certificate-based setups through environment variables.

Caching & Background Tasks

• Enables Redis caching (INVENIO_CACHE_TYPE = "redis").
• Constructs Redis URLs for caches, sessions, communities, and Celery results.
• Configures Celery broker (RabbitMQ by default) and Redis result backend.

JSON Schemas & Record Configuration

• Sets RECORDS_REFRESOLVER_CLS, RECORDS_REFRESOLVER_STORE, and JSONSCHEMAS_HOST.
• Optionally imports and sets VOCABULARIES_* configuration classes if oarepo-vocabularies is available.

RDM-Specific Settings

• Enables RDM features (INVENIO_RDM_ENABLED=True).
• Sets defaults for:
  • Persistent identifiers (RDM_PERSISTENT_IDENTIFIERS, RDM_PARENT_PERSISTENT_IDENTIFIERS).
  • User moderation, metadata-only records, file enablement.
  • Archive download support.
  • DOI/DataCite test mode.
• Configures identifier validation schemes for persons, organizations, funders, affiliations, etc. (VOCABULARIES_*_SCHEMES, RDM_RECORDS_*_SCHEMES).

Email

• Sets MAIL_DEFAULT_SENDER (from environment or placeholder).
• Enables MAIL_SUPPRESS_SEND if configured in environment.

Miscellaneous

• Defines rate limits and quota defaults (APP_RDM_DEPOSIT_FORM_QUOTA, FILES_REST_DEFAULT_QUOTA_SIZE).
• Sets SECRET_KEY from environment.
• Provides DASHBOARD_RECORD_CREATE_URL placeholder (to be customized).
• Clears default Invenio record routes and endpoints (since NRP provides replacements).

Environment-driven

The helper relies heavily on load_configuration_variables() to pull all INVENIO_* prefixed environment variables (or values from an equivalent .env/variable store).
All discovered values are injected into the caller scope via set_constants_in_caller().

Example

from invenio_i18n import lazy_gettext as _
from oarepo import config
 
config.configure_generic_parameters(
    languages=(("en", _("English")), ("cs", _("Czech"))),
)

configure_ui

Configures UI branding, theming, and build-time integration for an NRP or InvenioRDM-based repository.
This helper establishes the front-end metadata, asset pipeline defaults, theme template layout, and optional analytics integration.

Defined in oarepo/config/ui.py.

Parameters

Effects

Calling configure_ui() populates numerous UI- and frontend-related configuration constants:

Theming & Templates

• Defines the application theme chain (APP_THEME) including the repository code, oarepo, and semantic-ui layers.
• Points to a custom INSTANCE_THEME_FILE (./less/theme.less) for repository-specific LESS theme overrides.
• Configures all core page templates (e.g., BASE_TEMPLATE, HEADER_TEMPLATE, FOOTER_TEMPLATE, FRONTPAGE_TEMPLATE, SETTINGS_TEMPLATE, etc.).
• Ensures template load order avoids Invenio issues by explicitly setting SETTINGS_TEMPLATE and HEADER_TEMPLATE.
• Enables SEARCH_UI_SEARCH_TEMPLATE for InvenioRDM-style search results.

Branding & Identity

• Sets THEME_SITENAME, THEME_FRONTPAGE_TITLE, and REPOSITORY_NAME based on name parameter.
• Defines REPOSITORY_DESCRIPTION for use in metadata and templates.
• Configures THEME_LOGO, optional THEME_FRONTPAGE_LOGO, and intro visibility (THEME_SHOW_FRONTPAGE_INTRO_SECTION).
• THEME_FRONTPAGE toggles whether the default front page is used.

Analytics Integration

• If analytics="matomo" and the deployment is not local, adds Matomo tracking:
  • MATOMO_ANALYTICS_TEMPLATE = "oarepo_ui/matomo_analytics.html"
  • Reads INVENIO_MATOMO_ANALYTICS_URL and INVENIO_MATOMO_ANALYTICS_SITE_ID from environment.
  • Appends the Matomo endpoint URL to default-src of APP_DEFAULT_SECURE_HEADERS’s Content-Security-Policy (the helper also always appends https://licensebuttons.net/ for license badge images). See Security headers.

Frontend Build Configuration

• Configures frontend build pipeline defaults:
  • JAVASCRIPT_PACKAGES_MANAGER = "pnpm"
  • ASSETS_BUILDER = "rspack"
  • WEBPACKEXT_NPM_PKG_CLS = "pynpm:PNPMPackage"
  • WEBPACKEXT_PROJECT = "oarepo_ui.webpack:project"
• These ensure compatibility with the NRP/RDM Rspack + pnpm-based build s

Example

config.configure_ui(
    code="myrepo",
    name=_("My NRP Repository"),
    description=_("My NRP-based repository for research data."),
    analytics="matomo",
    use_default_frontpage=False,
    show_frontpage_intro=True,
    csp=config.CSP(
        connect_src=["https://api.example.org"],
    ),
)

configure_cron

Register default Celery beat schedules for background tasks such as indexing, session cleanup, statistics processing, and cache invalidation.
Additional cron definitions can be provided via keyword arguments.

Defined in oarepo/config/cron.py.

Parameters

Effect

Defines the CELERY_BEAT_SCHEDULE constant in the caller’s module.
The schedule includes default periodic jobs for:

• Record indexing queue management: every 10 seconds
• Session cleanup: every 60 minutes
• IP deletion: every 6 hours
• Statistics event processing: hourly at minutes 25 and 55
• Statistics aggregation: hourly at minute 0
• Community cache clearing: daily at 01:00 UTC
• Expired access token cleanup: daily at 00:04 UTC

Any extra cron items passed as keyword arguments are merged into the schedule before being set.

Example

from oarepo import config
from datetime import timedelta
from celery.schedules import crontab
 
config.configure_cron(
    my_custom_task={
        "task": "my_package.tasks.cleanup_temp",
        "schedule": crontab(minute=30, hour=3),  # every day at 03:30 UTC
    },
)

configure_stats

Enable and initialize repository & record-level statistics collection and aggregation features provided by invenio-stats.
This helper activates event receivers and imports default event, aggregation, and query definitions from invenio-app-rdm.

Defined in oarepo/config/stats.py.

Parameters

Effect

• Sets STATS_REGISTER_RECEIVERS to control activation of statistics event receivers.
• Imports and applies default STATS_EVENTS, STATS_AGGREGATIONS, STATS_QUERIES, and STATS_PERMISSION_FACTORY from invenio_app_rdm.config.
• Makes these constants available to the caller, so that the repository inherits the default InvenioRDM statistics setup.

Example

from oarepo import config
 
# Enable statistics collection and aggregation
config.configure_stats()
 
# Disable all statistics receivers (e.g., in development)
config.configure_stats(enable=False)

configure_vocabulary

Register or extend controlled vocabularies used in the repository.
Each vocabulary is identified by a short code and associated metadata parameters that describe its configuration or source.
Be consistent with your vocabularies defined in app_data folder.

Defined in oarepo/config/vocabulary.py.

Parameters

Effect

• Updates the INVENIO_VOCABULARY_TYPE_METADATA dictionary in the caller’s configuration with a new entry keyed by code.
• Makes vocabulary type metadata available at runtime for vocabulary registration and CLI loading.
• Supports multiple calls to incrementally register several vocabularies.

Example

from oarepo import config
 
config.configure_vocabulary(
    "licenses",
    pid_type="lic",
    hierarchical=True,
    name={"en": "Licenses", "cs": "Licence"},
)

configure_communities

Configure community-related settings, role definitions, and permission policies for Invenio Communities integration.
Defines how community membership and CRUD permissions are structured within the repository.

Defined in oarepo/config/communities.py.

Parameters

Default role definitions

If communities_roles is not provided, the following default roles are applied:

• owner

  • name: "owner"
  • title: _('Community owner')
  • description: _('Can manage community.')
  • is_owner: True
  • can_manage: True
  • can_manage_roles: ["owner", "curator", "member"]

• curator

  • name: "curator"
  • title: _('Curator')
  • description: _('Can curate records.')
  • can_manage: True
  • can_manage_roles: ["member"]

• member

  • name: "member"
  • title: _('Member')
  • description: _('Community member with read permissions.')

Effect

Sets the following constants in the caller module:

• COMMUNITIES_REGISTER_UI_BLUEPRINT = False
• COMMUNITIES_PERMISSION_POLICY = DefaultCommunitiesPermissionPolicy
  • A custom permission policy extending CommunityPermissionPolicy, granting Administration and SystemProcess privileges for core actions.
  • If oarepo_communities is installed, integrates the PrimaryCommunityRole generator for finer-grained role control.
• COMMUNITIES_ROLES — list of role dictionaries (ordered by importance).

Example

from invenio_i18n import lazy_gettext as _
from oarepo import config
 
config.configure_communities(
    communities_roles=[
        dict(
            name="root",
            title=_("Root administrator"),
            description=_("Can administer community."),
            is_owner=True,
            can_manage=True,
            can_manage_roles=["root", "librarian", "reader"],
        ),
        dict(
            name="librarian",
            title=_("Librarian"),
            description=_("Can curate community records."),
            can_manage=True,
            can_manage_roles=["reader"],
        ),
        dict(
            name="reader",
            title=_("Reader"),
            description=_("Can read community records."),
         ),
    ]
)
 

register_workflow

Register a workflow with its display name, permission policy, and request policy.
Workflows define how deposits are handled in the repository, including approval processes, permissions, and request types.

Defined in oarepo/config/workflows.py.

Parameters

Effect

• Registers a new workflow in the WORKFLOWS dictionary in the caller’s configuration.
• Each workflow entry maps the name to a dictionary containing title, permissions_class, and requests_class.
• Makes the workflow available for use in community or individual deposit configurations.
• Supports different approval processes: community workflows with curator/owner approval, or simpler individual workflows.

Example

from invenio_i18n import lazy_gettext as _
from oarepo import config
 
# Full workflow for community deposits:
# requires approval from curators/owners before publishing
# and supports review, versioning, and deletion requests.
config.register_workflow(
     "default",
     _("Default workflow"),
     "common.workflows.default.DefaultWorkflowPermissions",
     "common.workflows.default.DefaultWorkflowRequests",
)
 
 
# Simple workflow for individual deposits:
# fewer rules, no full approval process like in communities,
# mostly basic permissions for creating and managing records.
config.register_workflow(
     "individual",
     _("Individual deposition workflow"),
     "common.workflows.individual.IndividualDepositionWorkflowPermissions",
     "oarepo_workflows.requests.policy.WorkflowRequestPolicy",
)

Common configuration topics

The helpers above are the building blocks; this section expands on a few cross-cutting configuration values they manage, so you can adjust them safely when needed.

Security headers (APP_DEFAULT_SECURE_HEADERS)

NRP repositories configure HTTP security headers through the standard Invenio APP_DEFAULT_SECURE_HEADERS variable. Invenio applies these headers to every response it serves.

Two of the configuration helpers collaborate to build the dictionary:

1. configure_generic_parameters sets the baseline — a full security-header dictionary with the CSP, HTTPS enforcement, cookie, and HSTS defaults listed below, plus the S3_ENDPOINT_URL appended to default-src when S3 storage is used.
2. configure_ui then extends the value prepared by configure_generic_parameters — it appends https://licensebuttons.net/ to default-src so license badge images load, and, when analytics="matomo" is used on a non-local deployment, appends the Matomo endpoint URL from INVENIO_MATOMO_ANALYTICS_URL.

The baseline produced by configure_generic_parameters() looks like this:

APP_DEFAULT_SECURE_HEADERS = {
    "content_security_policy": {
        "default-src": [
            "'self'",
            "fonts.googleapis.com",  # for fonts
            "*.gstatic.com",         # for fonts
            "data:",                 # for fonts
            "'unsafe-inline'",       # for inline scripts and styles
            "blob:",                 # for pdf preview
        ],
        "script-src": [
            "'self'",
            "blob:",
            "'wasm-unsafe-eval'",    # checksum Web Worker (hash-wasm) for multipart uploads
        ],
    },
    "content_security_policy_report_only": False,
    "content_security_policy_report_uri": None,
    "force_file_save": False,
    "force_https": True,
    "force_https_permanent": False,
    "frame_options": "sameorigin",
    "frame_options_allow_from": None,
    "session_cookie_http_only": True,
    "session_cookie_secure": True,
    "strict_transport_security": True,
    "strict_transport_security_include_subdomains": True,
    "strict_transport_security_max_age": 31556926,  # one year, in seconds
    "strict_transport_security_preload": False,
}

Customizing the CSP

Do not edit APP_DEFAULT_SECURE_HEADERS by hand for routine CSP changes — pass a config.CSP instance to configure_ui() via its csp= argument instead. The helper merges your directives with the already-configured defaults, following the CSP specification’s own fallback rules, so you don’t accidentally drop sources the application still needs:

from oarepo import config
 
config.configure_generic_parameters()
 
config.configure_ui(
    code="myrepo",
    name=_("My NRP Repository"),
    csp=config.CSP(
        # let the deposit form call an external vocabulary API from the browser
        connect_src=["https://api.example.org"],
        # allow embedding this repository in an iframe on the same origin
        frame_ancestors=["'self'"],
    ),
)

CSP is a dataclass with one field per directive — default_src, script_src, script_src_elem, script_src_attr, style_src, style_src_elem, style_src_attr, img_src, font_src, connect_src, object_src, media_src, frame_src, frame_ancestors, child_src, worker_src, manifest_src, prefetch_src, form_action, base_uri, report_to — plus report_uri and report_only for Flask-Talisman’s reporting options. Each directive field takes a list of sources.

When configure_ui() applies your CSP, it resolves each directive against whatever was already configured:

• A directive you set is merged with the sources already configured for it, or — if none — with the sources of the directive it would fall back to (script-src for script-src-elem/script-src-attr, style-src for style-src-elem/style-src-attr, child-src for frame-src/worker-src, otherwise default-src). This is what lets csp=CSP(connect_src=["https://api.example.org"]) add to the existing default-src sources instead of replacing them.
• base_uri, form_action, frame_ancestors, report_to never inherit default-src, matching the CSP spec — setting one only adds the sources you pass in.
• A directive you leave unset keeps whatever was already configured, unchanged — including directives the CSP class does not model (e.g. upgrade-insecure-requests).
• Your sources come first in the merged source list, followed by the inherited ones, deduplicated.

A report_uri you set overrides one already configured in APP_DEFAULT_SECURE_HEADERS["content_security_policy_report_uri"]; if you don’t set one, the configured value is kept as-is. report_only=True switches the policy to report-only mode (violations are logged, not blocked) and requires a report_uri — either on the CSP instance or already configured, otherwise apply_defaults() raises ValueError.

For non-CSP keys (force_https, frame_options, strict_transport_security_*, etc.), no helper API exists — override them after both helpers, before set_constants_in_caller publishes the value:

config.configure_generic_parameters()
config.configure_ui(code="myrepo", name=_("My NRP Repository"))
 
# non-CSP overrides come after both helpers
APP_DEFAULT_SECURE_HEADERS["frame_options"] = "deny"