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
| Name | Type | Default | Description |
|---|---|---|---|
| languages | sequence 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_URLandSITE_API_URLusing either environment-provided values or constructed defaults from host/port. - Sets
APP_ALLOWED_HOSTSto allow local access (0.0.0.0,localhost,127.0.0.1).
Security
- Constructs the baseline
APP_DEFAULT_SECURE_HEADERSdictionary — CSP defaults, HTTPS enforcement, frame options, cookie security, HSTS. Appends the S3 endpoint todefault-srcwhen S3 storage is configured. The value is then extended byconfigure_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 saneStrict-Transport-Securitydefaults. - 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_APPSready to be populated with external identity providers. - Sets
ACCOUNTS_LOGIN_VIEW_FUNCTIONto auto-redirect when single external login is configured.
Database
- Constructs
SQLALCHEMY_DATABASE_URIfromINVENIO_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=Trueturns 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
languagesargument intoI18N_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, andS3_SECRET_ACCESS_KEY.
- Adds S3 endpoint to CSP’s
default-src. - Defines
FILES_REST_STORAGE_CLASS_LISTand 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.
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, andJSONSCHEMAS_HOST. - Optionally imports and sets
VOCABULARIES_*configuration classes ifoarepo-vocabulariesis 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.
- Persistent identifiers (
- Configures identifier validation schemes for persons, organizations, funders, affiliations, etc. (
VOCABULARIES_*_SCHEMES,RDM_RECORDS_*_SCHEMES).
- Sets
MAIL_DEFAULT_SENDER(from environment or placeholder). - Enables
MAIL_SUPPRESS_SENDif configured in environment.
Miscellaneous
- Defines rate limits and quota defaults (
APP_RDM_DEPOSIT_FORM_QUOTA,FILES_REST_DEFAULT_QUOTA_SIZE). - Sets
SECRET_KEYfrom environment. - Provides
DASHBOARD_RECORD_CREATE_URLplaceholder (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:
| Setting | Effect |
|---|---|
REST_CSRF_ENABLED = True | The 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_URI | Rate-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_RATELIMIT | Brute-force protection of the local account forms. |
ACCESS_CACHE | Resolved permissions are cached instead of being read from the database on every check. |
SQLALCHEMY_ENGINE_OPTIONS | Database 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:
| Setting | Effect |
|---|---|
RATELIMIT_PER_ENDPOINT | Tighter limits on the local and external login views. |
FILES_REST_PERMISSION_FACTORY | Denies the legacy /api/files REST API, which does not honour record permissions. Record files are not affected. |
MAX_CONTENT_LENGTH | 100 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_HANDLERS | Invalid community visibility or access restrictions are reported as 400 Bad Request, not as a server error. |
ACCOUNTS_USER_PREFERENCES_SCHEMA, USERS_RESOURCES_SERVICE_SCHEMA | The notification preferences in the user settings are validated and honoured. |
INDEXER_MQ_PUBLISH_KWARGS | Publishing to the indexing queue is retried instead of dropping the index update when the message broker is briefly unavailable. |
ADMINISTRATION_DISPLAY_VERSIONS | The 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
| Name | Type | Default | Description |
|---|---|---|---|
code | str | "myrepo" | Short repository identifier used in internal theme names, URLs, and build integration. |
name | str | _('My Repository') | Translated display name for the repository, used in UI titles and metadata. |
description | str | "" | Human-readable description of the repository displayed in various templates and metadata. |
use_default_frontpage | bool | False | If True, uses the standard default front page layout instead of a custom one. |
show_frontpage_intro | bool | True | Controls whether the front-page introduction (hero/intro section) is displayed. |
analytics | bool | False | Enables analytics integration. Set to "matomo" to enable Matomo tracking (requires additional environment vars). |
csp | CSP | None | None | Optional 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, andsemantic-uilayers. - 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_TEMPLATEandHEADER_TEMPLATE. - Enables
SEARCH_UI_SEARCH_TEMPLATEfor InvenioRDM-style search results.
Branding & Identity
- Sets
THEME_SITENAME,THEME_FRONTPAGE_TITLE, andREPOSITORY_NAMEbased onnameparameter. - Defines
REPOSITORY_DESCRIPTIONfor use in metadata and templates. - Configures
THEME_LOGO, optionalTHEME_FRONTPAGE_LOGO, and intro visibility (THEME_SHOW_FRONTPAGE_INTRO_SECTION). THEME_FRONTPAGEtoggles 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_URLandINVENIO_MATOMO_ANALYTICS_SITE_IDfrom environment. - Appends the Matomo endpoint URL to
default-srcofAPP_DEFAULT_SECURE_HEADERS’sContent-Security-Policy(the helper also always appendshttps://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
| Name | Type | Default | Description |
|---|---|---|---|
| file_integrity_check_days | int | None | None | Turns 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_items | dict[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 = Trueis set earlier ininvenio.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(setINVENIO_APP_RDM_ADMIN_EMAIL_RECIPIENTin 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
| Name | Type | Default | Description |
|---|---|---|---|
| enable | bool | True | Whether to enable registration of statistics event receivers and related analytics features. |
| count_preview_downloads | bool | True | Whether 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_RECEIVERSto control activation of statistics event receivers. - Sets
RDM_STATS_EXCLUDE_PREVIEW_FILE_DOWNLOAD_EVENTSto the inverse ofcount_preview_downloads. - Imports and applies default
STATS_EVENTS,STATS_AGGREGATIONS,STATS_QUERIES, andSTATS_PERMISSION_FACTORYfrominvenio_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
| Name | Type | Default | Description |
|---|---|---|---|
| max_file_size | int | 1 * 10**9 (1 GB) | Maximum size of a single uploaded file, in bytes. |
| max_files_count | int | 100 | Maximum number of files per record. |
| max_total_size | int | 5 * 10**9 (5 GB) | Maximum combined size of all files of a record, in bytes. |
| allow_metadata_only_records | bool | True | With False, a record cannot be published without at least one file. |
| allow_empty_files | bool | None | None | Whether 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_period | timedelta | timedelta(days=45) | How long after publication the files of a record can still be modified without creating a new version. |
| allow_immediate_file_modification | bool | True | Lets record owners unlock and edit their published files themselves within the grace period; administrators can do so at any time. |
| allow_immediate_quota_increase | bool | True | Lets users raise the storage quota of a draft from their additional allowance (“Manage storage” in the file uploader). |
| max_additional_quota_size | int | 0 | Additional quota, in bytes, that may be granted on top of max_total_size. |
| allow_archive_download | bool | True | Whether all files of a record can be downloaded at once as a ZIP archive (“Download all”). |
| max_archive_download_size | int | None | None | Largest 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_COUNTandRDM_FILES_DEFAULT_MAX_ADDITIONAL_QUOTA_SIZE, theirFILES_REST_*fallbacks, and the matching deposit form quotaAPP_RDM_DEPOSIT_FORM_QUOTA. - Sets
RDM_ALLOW_METADATA_ONLY_RECORDSandRECORDS_RESOURCES_ALLOW_EMPTY_FILES. - Sets
RDM_FILE_MODIFICATION_PERIOD,RDM_IMMEDIATE_FILE_MODIFICATION_ENABLEDandRDM_IMMEDIATE_QUOTA_INCREASE_ENABLED, with their policies. - Sets
RDM_ARCHIVE_DOWNLOAD_ENABLEDandRECORDS_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
| Name | Type | Default | Description |
|---|---|---|---|
| repository_name | str | None | None | Name announced in the Identify response. Defaults to the name given to configure_ui. |
| admin_emails | list[str] | str | None | None | Administrative contact announced in the Identify response. Defaults to the support_contact given to configure_ui, if that is an e-mail address. |
| page_size | int | 50 | Number of records per ListRecords / ListIdentifiers / ListSets page. |
| resumption_token_expire_time | int | 120 | How long, in seconds, a harvester may wait before asking for the next page. |
Effect
- Sets
OAISERVER_REPOSITORY_NAME,OAISERVER_PAGE_SIZEandOAISERVER_RESUMPTION_TOKEN_EXPIRE_TIME. - Sets
OAISERVER_ADMIN_EMAILSwhen 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
| Name | Type | Default | Description |
|---|---|---|---|
| code | str | — | Unique identifier for the vocabulary type (e.g., "licenses", "languages"). |
| **kwargs | dict[str, Any] | {} | Arbitrary metadata for the vocabulary, such as loader configuration, schema, or labels. |
Effect
- Updates the
INVENIO_VOCABULARY_TYPE_METADATAdictionary in the caller’s configuration with a new entry keyed bycode. - 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
| Name | Type | Default | Description |
|---|---|---|---|
| communities_roles | list[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:Truecan_manage:Truecan_manage_roles:["owner", "curator", "member"]
-
curator
name:"curator"title:_('Curator')description:_('Can curate records.')can_manage:Truecan_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 = FalseCOMMUNITIES_PERMISSION_POLICY = DefaultCommunitiesPermissionPolicy- A custom permission policy extending
CommunityPermissionPolicy, grantingAdministrationandSystemProcessprivileges for core actions. - If
oarepo_communitiesis installed, integrates thePrimaryCommunityRolegenerator for finer-grained role control.
- A custom permission policy extending
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
| Name | Type | Default | Description |
|---|---|---|---|
| name | str | — | Unique identifier for the workflow (e.g., "default", "individual"). |
| title | str | — | Translated display name for the workflow, shown in UI and metadata. |
| permissions_class | str | — | Dotted import path to the permission policy class that defines who can perform actions in this workflow. |
| requests_class | str | — | 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
WORKFLOWSdictionary in the caller’s configuration. - Each workflow entry maps the
nameto a dictionary containingtitle,permissions_class, andrequests_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:
configure_generic_parameterssets the baseline — a full security-header dictionary with the CSP, HTTPS enforcement, cookie, and HSTS defaults listed below, plus theS3_ENDPOINT_URLappended todefault-srcwhen S3 storage is used.configure_uithen extends the value prepared byconfigure_generic_parameters— it appendshttps://licensebuttons.net/todefault-srcso license badge images load, and, whenanalytics="matomo"is used on a non-local deployment, appends the Matomo endpoint URL fromINVENIO_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-srcforscript-src-elem/script-src-attr,style-srcforstyle-src-elem/style-src-attr,child-srcforframe-src/worker-src, otherwisedefault-src). This is what letscsp=CSP(connect_src=["https://api.example.org"])add to the existingdefault-srcsources instead of replacing them. base_uri,form_action,frame_ancestors,report_tonever inheritdefault-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
CSPclass 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"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.