Skip to Content

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

NameTypeDefaultDescription
languagessequence of tuples(("cs", _("Czech")),)Sequence of (code, translated-name) pairs to register as available languages.

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).
  • Applies the InvenioRDM security defaults — CSRF protection of the REST API, rate-limit counters shared in Redis, limits on the account forms. See InvenioRDM defaults.

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.
  • Sets SQLALCHEMY_ENGINE_OPTIONS: connections are recycled after an hour, a request waits at most 10 s for a free connection, the session time zone is UTC and the connection is labelled with the host name (application_name).
    • INVENIO_PGBOUNCER_ENABLED=True turns off connection pooling in the application, for deployments where PgBouncer pools instead.
    • INVENIO_SQLALCHEMY_ENGINE_OPTIONS (a JSON object, e.g. {"pool_size": 10, "pool_pre_ping": true}) is merged over these defaults.

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).
  • Configures OpenSearch connection (SEARCH_INDEX_PREFIX, SEARCH_HOSTS, SEARCH_CLIENT_CONFIG).
  • Supports SSL and certificate-based setups through environment variables.
  • INVENIO_OPENSEARCH_TIMEOUT (seconds) raises the search request timeout; the client’s own default of 10 s applies otherwise.

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).

InvenioRDM defaults

A stock InvenioRDM instance takes its instance-wide defaults from invenio_app_rdm.config. NRP repositories do not load that module, because it would bring back the stock RDM record pages that NRP replaces. The defaults a repository should not run without are re-applied instead.

configure_generic_parameters() applies the ones that switch on enforcement or depend on the deployment:

SettingEffect
REST_CSRF_ENABLED = TrueThe REST API rejects POST/PUT/PATCH/DELETE requests made with a browser session unless they carry the CSRF token. Requests authenticated with an access token are exempt.
RATELIMIT_STORAGE_URIRate-limit counters are kept in Redis and shared by all web processes, rather than each process allowing the full limit on its own. Uses Redis database INVENIO_REDIS_RATELIMIT_DB (default 4); set INVENIO_RATELIMIT_STORAGE_URI to use a different server.
ACCOUNTS_LOGIN_RATELIMIT, ACCOUNTS_FORGOT_PASSWORD_EMAIL_RATELIMIT, ACCOUNTS_SEND_CONFIRMATION_RATELIMITBrute-force protection of the local account forms.
ACCESS_CACHEResolved permissions are cached instead of being read from the database on every check.
SQLALCHEMY_ENGINE_OPTIONSDatabase connection pool options, see Database.

The remaining ones are built into the oarepo and oarepo-rdm packages, so they apply even without a helper call:

SettingEffect
RATELIMIT_PER_ENDPOINTTighter limits on the local and external login views.
FILES_REST_PERMISSION_FACTORYDenies the legacy /api/files REST API, which does not honour record permissions. Record files are not affected.
MAX_CONTENT_LENGTH100 MiB limit on form submissions. File uploads are streamed and not affected.
SITEMAP_SECTIONS/sitemap_index_0.xml (advertised in /robots.txt) lists the public records of all models and the public communities. Refreshed daily by configure_cron.
COMMUNITIES_ERROR_HANDLERS, REQUESTS_ERROR_HANDLERSInvalid community visibility or access restrictions are reported as 400 Bad Request, not as a server error.
ACCOUNTS_USER_PREFERENCES_SCHEMA, USERS_RESOURCES_SERVICE_SCHEMAThe notification preferences in the user settings are validated and honoured.
INDEXER_MQ_PUBLISH_KWARGSPublishing to the indexing queue is retried instead of dropping the index update when the message broker is briefly unavailable.
ADMINISTRATION_DISPLAY_VERSIONSThe administration panel shows the installed oarepo and invenio-app-rdm versions.

Each of them can be overridden by a plain assignment later in invenio.cfg.

With CSRF protection on, your own browser code has to send the value of the csrftoken cookie back in the X-CSRFToken header on every modifying request. The HTTP clients exported by @js/oarepo_ui and react-invenio-forms already do; a plain fetch() or a bare axios call does not, and is answered with 400 CSRF token missing or incorrect.

The Redis database used for rate limiting must not be shared with the communities cache (INVENIO_REDIS_COMMUNITIES_CACHE_DB), which is flushed once a day.

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

NameTypeDefaultDescription
codestr"myrepo"Short repository identifier used in internal theme names, URLs, and build integration.
namestr_('My Repository')Translated display name for the repository, used in UI titles and metadata.
descriptionstr""Human-readable description of the repository displayed in various templates and metadata.
use_default_frontpageboolFalseIf True, uses the standard default front page layout instead of a custom one.
show_frontpage_introboolTrueControls whether the front-page introduction (hero/intro section) is displayed.
analyticsboolFalseEnables analytics integration. Set to "matomo" to enable Matomo tracking (requires additional environment vars).
cspCSP | NoneNoneOptional Content-Security-Policy additions, declared as a config.CSP instance. Merged with the APP_DEFAULT_SECURE_HEADERS baseline via CSP.apply_defaults() following CSP’s fallback rules, so adding e.g. connect_src doesn’t drop the existing default-src sources. See Security headers.

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.

The schedule covers every job a stock InvenioRDM instance runs, with one exception: usage statistics are not copied into the record search documents (reindex-stats), because NRP record models do not index them.

Defined in oarepo/config/cron.py.

Parameters

NameTypeDefaultDescription
file_integrity_check_daysint | NoneNoneTurns on periodic fixity checking: the checksum of every stored file is re-computed once per this many days, spread over hourly batches, and a daily e-mail reports missing or corrupted files. Off by default.
**extra_cron_itemsdict[str, Any]{}Extra Celery beat entries to merge into the default schedule (e.g., additional periodic jobs). An entry with the name of a default job replaces it.

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
  • Lifting expired embargoes: daily at 00:00 UTC
  • Expiring requests past their expiration date (e.g. community invitations): daily at 00:03 UTC
  • Purging discarded drafts: every 60 minutes
  • Deleting old job logs (older than JOBS_LOGGING_RETENTION_DAYS, 90 by default): daily at 00:05 UTC
  • Sitemap refresh: daily at 02:00 UTC
  • User e-mail domain statistics: every 4 hours
  • Community collections size: hourly — only when COMMUNITIES_COLLECTIONS_ENABLED = True is set earlier in invenio.cfg

With file_integrity_check_days set, two more jobs are added:

  • File checksum verification: an hourly batch, sized so that all files are covered once per the given number of days
  • File integrity report: daily at 07:00 UTC, e-mailed to APP_RDM_ADMIN_EMAIL_RECIPIENT (set INVENIO_APP_RDM_ADMIN_EMAIL_RECIPIENT in the environment)

Fixity checking reads every file back from the storage. Before enabling it on an S3 deployment, make sure that this traffic is acceptable and try it on a test instance first: files uploaded in multiple parts may carry a checksum that cannot be re-computed, and would then be reported as corrupted.

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 }, ) # verify the checksum of every file twice a year config.configure_cron(file_integrity_check_days=180)

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

NameTypeDefaultDescription
enableboolTrueWhether to enable registration of statistics event receivers and related analytics features.
count_preview_downloadsboolTrueWhether a file fetched by the in-page file previewer counts as a download. With False, opening a record page that previews a file no longer adds to its download count.

Effect

  • Sets STATS_REGISTER_RECEIVERS to control activation of statistics event receivers.
  • Sets RDM_STATS_EXCLUDE_PREVIEW_FILE_DOWNLOAD_EVENTS to the inverse of count_preview_downloads.
  • 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) # Do not count file previews as downloads config.configure_stats(count_preview_downloads=False)

configure_files

Set the file upload limits of a record, and the file-related toggles.

Defined in oarepo/config/files.py.

Parameters

NameTypeDefaultDescription
max_file_sizeint1 * 10**9 (1 GB)Maximum size of a single uploaded file, in bytes.
max_files_countint100Maximum number of files per record.
max_total_sizeint5 * 10**9 (5 GB)Maximum combined size of all files of a record, in bytes.
allow_metadata_only_recordsboolTrueWith False, a record cannot be published without at least one file.
allow_empty_filesbool | NoneNoneWhether zero-byte files are accepted. Defaults to the value of allow_metadata_only_records, so that requiring files cannot be satisfied by an empty one.
file_modification_grace_periodtimedeltatimedelta(days=45)How long after publication the files of a record can still be modified without creating a new version.
allow_immediate_file_modificationboolTrueLets record owners unlock and edit their published files themselves within the grace period; administrators can do so at any time.
allow_immediate_quota_increaseboolTrueLets users raise the storage quota of a draft from their additional allowance (“Manage storage” in the file uploader).
max_additional_quota_sizeint0Additional quota, in bytes, that may be granted on top of max_total_size.
allow_archive_downloadboolTrueWhether all files of a record can be downloaded at once as a ZIP archive (“Download all”).
max_archive_download_sizeint | NoneNoneLargest total size of a record’s files, in bytes, for which “Download all” is still offered. None means no limit.

Effect

  • Sets the backend limits RDM_FILES_DEFAULT_MAX_FILE_SIZE, RDM_FILES_DEFAULT_QUOTA_SIZE, RDM_RECORDS_MAX_FILES_COUNT and RDM_FILES_DEFAULT_MAX_ADDITIONAL_QUOTA_SIZE, their FILES_REST_* fallbacks, and the matching deposit form quota APP_RDM_DEPOSIT_FORM_QUOTA.
  • Sets RDM_ALLOW_METADATA_ONLY_RECORDS and RECORDS_RESOURCES_ALLOW_EMPTY_FILES.
  • Sets RDM_FILE_MODIFICATION_PERIOD, RDM_IMMEDIATE_FILE_MODIFICATION_ENABLED and RDM_IMMEDIATE_QUOTA_INCREASE_ENABLED, with their policies.
  • Sets RDM_ARCHIVE_DOWNLOAD_ENABLED and RECORDS_RESOURCES_ARCHIVE_DOWNLOAD_MAX_SIZE.

The “Download all” archive is assembled on the fly by a web worker, which stays busy for the whole download. If your repository accepts large files, set max_archive_download_size; larger records then only offer per-file downloads.

Example

from oarepo import config config.configure_files( max_file_size=50 * 10**9, # 50 GB per file max_total_size=50 * 10**9, # 50 GB per record allow_metadata_only_records=False, max_archive_download_size=5 * 10**9, # "Download all" up to 5 GB )

configure_oai

Announce the repository over OAI-PMH, the protocol aggregators and other repositories use to harvest records, and tune the paging of its list responses.

Call it after configure_ui, which provides the default repository name and contact.

Defined in oarepo/config/oai.py.

Parameters

NameTypeDefaultDescription
repository_namestr | NoneNoneName announced in the Identify response. Defaults to the name given to configure_ui.
admin_emailslist[str] | str | NoneNoneAdministrative contact announced in the Identify response. Defaults to the support_contact given to configure_ui, if that is an e-mail address.
page_sizeint50Number of records per ListRecords / ListIdentifiers / ListSets page.
resumption_token_expire_timeint120How long, in seconds, a harvester may wait before asking for the next page.

Effect

  • Sets OAISERVER_REPOSITORY_NAME, OAISERVER_PAGE_SIZE and OAISERVER_RESUMPTION_TOKEN_EXPIRE_TIME.
  • Sets OAISERVER_ADMIN_EMAILS when a contact is known.

Without configure_oai(), or without a contact, the repository announces the placeholder address info@inveniosoftware.org as its administrator. Pass admin_emails, or give configure_ui an e-mail address as support_contact.

Example

from oarepo import config config.configure_oai( repository_name="My NRP Repository", admin_emails=["repository@example.org"], )

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

NameTypeDefaultDescription
codestr—Unique identifier for the vocabulary type (e.g., "licenses", "languages").
**kwargsdict[str, Any]{}Arbitrary metadata for the vocabulary, such as loader configuration, schema, or labels.

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

NameTypeDefaultDescription
communities_roleslist[dict]None (uses built-in defaults)Optional custom role definitions. If omitted, defaults to the built-in ordered list of "owner", "curator", and "member" roles. Each role dictionary can include fields such as name, title, description, is_owner, can_manage, and can_manage_roles.

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

NameTypeDefaultDescription
namestr—Unique identifier for the workflow (e.g., "default", "individual").
titlestr—Translated display name for the workflow, shown in UI and metadata.
permissions_classstr—Dotted import path to the permission policy class that defines who can perform actions in this workflow.
requests_classstr—Dotted import path to the request policy class that defines what types of requests (review, deletion, versioning) are supported.

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:

invenio.cfg (defaults set by configure_generic_parameters)
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:

invenio.cfg
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:

invenio.cfg
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"

You only need to extend CSP when the browser talks to an additional origin — external vocabulary autocomplete endpoints, analytics providers, embedded media, additional CDNs, and so on. If the call goes through your repository backend instead, no CSP change is needed and cross-origin restrictions do not apply.

Last updated on