Frequently Asked Questions (FAQ)
Below are some of the most commonly asked technical and development questions about the RDMC project, along with their answers. If you want to see the general user FAQ, go to Frequently Asked Questions (FAQ).
Installation & Setup
1. How do I set up the development environment?
Clone the repository, activate your virtual environment, and install all dependencies including dev and docs extras:
git clone https://gitlab.gwdg.de/nfdixcs/a1-architecture/rdmc-prototype.git
venv\Scripts\Activate
python -m pip install ".[dev,docs]"
Then create a .env file from the .env.example before running the project.
2. Where do I find the example .env file?
An example configuration file is available in the repository at .env.example.
3. Do I need to create the .env file before running Docker, and why might the platform fail to start?
Yes. The .env file must be created in the project root before running docker-compose up -d --build.
The most common cause of the platform failing to start or starting incorrectly in Docker is a missing or incomplete .env file. See Containerized Deployment with Docker for the full steps.
4. How do I run the project using Docker?
Make sure Docker is running on your system, then execute the following command in your terminal:
docker-compose up -d --build
5. How do I rebuild the documentation after making changes?
cd docs/0.8.0
make html
If changes do not show up, clean the build cache first:
rmdir /s /q build\doctrees && make html
See Documentation Structure for the layout of the docs folder.
6. How do I run tests and code quality checks?
All tests live in the top-level test folder. Run the whole suite, or a single file, class, or method:
python manage.py test test
python manage.py test test.rdmc.test_core
python manage.py test test.rdmc_metadata.test_metadata
pytest with pytest-django is also configured in pyproject.toml (testpaths = ["test"]), so a plain pytest works as well once the dev extras are installed.
For static analysis, formatting, and type checking (alongside PEP 257 docstrings and Python type hints), run:
mypy rdmc
ruff check rdmc
ruff check --fix rdmc
pylint rdmc
See Testing and Code Quality for details.
7. The server refuses to start with “ADMIN_USERNAME/ADMIN_PASSWORD missing or invalid”. What should I do?
On startup (startup.py), the project runs set_admin_password and exits if the admin credentials are not set. Add both variables to your .env file:
ADMIN_USERNAME=your_secure_admin_id
ADMIN_PASSWORD=your_secure_admin_password
These also form the second layer of the admin panel protection.
8. What environment variables are needed in .env?
Environment variables are read in RDMC_Proto/settings.py, startup.py, and service modules (see .env.example for a template):
Admin & startup (required):
ADMIN_USERNAME,ADMIN_PASSWORD, plus optionalRDMC_LOAD_FIXTURES,GUNICORN_WORKERS,GUNICORN_BIND,GUNICORN_TIMEOUT.Core Django, hosts, database & media:
DEBUG,ALLOWED_HOSTS,TEMPLATE_CACHE,DJANGO_DB_PATH,DJANGO_MEDIA_ROOT,SESSION_COOKIE_SECURE,CSRF_COOKIE_SECURE,CORS_ALLOWED_ORIGINS.Run mode & feature flags:
RDMC_RUN_AS_DEMO,RDMC_RUN_IN_SERVICE,LANDING_VIEW_ENABLED,FEATURE_REE_ENABLED,FEATURE_PUBLISH_ARTIFACT_ENABLED.AcademicCloud OIDC login:
ACADEMIC_CLOUD_ENABLED,ACADEMIC_CLOUD_ID,ACADEMIC_CLOUD_SECRET,ACADEMIC_CLOUD_METADATA_URL,ACADEMIC_CLOUD_SCOPE,ACADEMIC_CLOUD_REDIRECT_URI.External services & repositories:
REE_URL,REE_AUTH_ENABLED,SEARCH_API_BASE_URL,API_TOKEN_DATAVERSE,SERVER_URL_DATAVERSE,PARENT_DATAVERSE,DATAVERSE_ID.Email notifications (repository requests):
EMAIL_HOST,EMAIL_PORT,EMAIL_HOST_USER,EMAIL_HOST_PASSWORD,EMAIL_USE_TLS,DEFAULT_FROM_EMAIL,SITE_URL,REPO_REQUEST_NOTIFY_EMAILS,REPO_REQUEST_NOTIFY_ENABLED.
9. How does Demo mode (IS_DEMO / RDMC_RUN_AS_DEMO) work, and where are custom settings defined?
When RDMC_RUN_AS_DEMO=true is set in .env, IS_DEMO becomes True in RDMC_Proto/settings.py. In demo mode, physical file uploads from a user’s device are disabled (only external links/URLs are allowed), and on the public Demo website (https://rdmc.create.nfdixcs.org/) a scheduled nightly job deletes all data.
Keep RDMC_RUN_AS_DEMO=false for Stable/production or full local development. Custom settings such as MEDIA_ROOT, MANIFEST_FILE_NAME, SCHEMA_FILE_NAME, and IS_DEMO are documented in Settings.
10. How does the two-layer authentication for admin and organizer access work?
Access to the admin panel requires passing two independent verification layers enforced by middleware (admin_organiser_access_middleware and separate_admin_session_middleware):
Layer 1 — Organizer Model Verification: The logged-in user’s name and email from AcademicCloud must match an existing record in the
Organizermodel.Layer 2 — Environment Credentials: The administrator ID and password entered must match
ADMIN_USERNAMEandADMIN_PASSWORDin.env(synced on startup byset_admin_password).
Both layers must succeed before admin access is granted. See Admin Panel Access Protection.
Architecture & Components
11. How is the project structured?
The project is split into 13 components, each with a clear responsibility. The most important ones are:
rdmc— core component: container lifecycle, wizard views, uploadsrdmc_metadata— metadata validation andmanifest.rdmcgenerationrdmc_auth— AcademicCloud OIDC loginrdmc_configuration— configures the RDMC workflow (feature registry, roles)rdmc_publish— publish-related logic (Zenodo, Dataverse, Coscine, ePIC PID)ree_service— the Reusable Execution Environment (REE) workbench and client
See Components Overview for the full component list and Project Structure for terminology, directory layout, and layer mapping.
12. Which component should I modify for a specific feature?
Container or artifact logic, wizard steps →
rdmcMetadata or manifest generation →
rdmc_metadataQuestions, feature flags, roles →
rdmc_configurationPublishing, registry, or PID updates →
rdmc_publishReusable Execution Environment (REE) step →
ree_serviceSigning and sealing →
rdmc_signREST API →
rdmc_workflow_api
13. How do I add or change the questions participants are asked?
Questions are not part of the feature registry. They are database rows scoped to a configuration, in two independent models: Artifact Details Questions (per artifact) and Metadata Questions (per container, mapped to the manifest via manifest_properties). Create or edit them through the admin panel; see Adding and Modifying Questions and Questionnaire Creation Process.
14. How do I add, reorder, or change configurable workflow features and preview steps?
Configurable participant options are driven by FEATURE_REGISTRY in rdmc_configuration/feature_registry.py — adding, reordering, or editing entries automatically updates the edit UI, database persistence, and preview (supporting radio, multiselect, text, depends_on, and togglable options). The preview sidebar steps are defined in WORKFLOW_PREVIEW_STEPS in the same file.
Note that global deployment switches (FEATURE_REE_ENABLED and FEATURE_PUBLISH_ARTIFACT_ENABLED) are controlled via .env in RDMC_Proto/settings.py, whereas FEATURE_REGISTRY controls per-configuration settings. See The Feature Registry and Common Modifications.
15. How does the ree_service component work, and how do I enable or disable it?
ree_service acts as an authenticated proxy between the browser-based REE Workbench (ree_workbench.js) and the external REE REST API (REE_URL, default https://ree.create.nfdixcs.org). It stores the container-to-REE link in ContainerREE (replacing the legacy UnboundREE / BoundREE models) and saves job artifacts back into the container.
Set
REE_AUTH_ENABLED=true(default) for AcademicCloud OAuth, orfalsefor plain HTTP against a local REE instance.Set
FEATURE_REE_ENABLED=falsein.envto disable the feature globally; every endpoint checksrdmc.features.is_active('REE_ENABLED')and returns403when disabled while letting users continue past Step 2.
See REE Service for endpoints and client details.
16. Where is the manifest schema defined and how do I change it?
The JSON schema is the etc/schemas/schema.json file (SCHEMA_FILE_PATH in Settings). The generated file is manifest.rdmc (MANIFEST_FILE_NAME). Before changing the schema, read Manifest JSON Schema and Schema Documentation; the data models that back it are described in RDMC Model Schema.
17. How are resource types (Data, Software, RDMC, RDMC + REE) handled in the backend?
Uploaded resources are tagged with one or more built-in types (or custom types from a configuration):
Data — general research data assets (datasets, tables, measurements, or supporting files).
Software — general software engineering artifacts (source code, scripts, libraries, tools, or executables).
RDMC — intended to connect a previously created Research Data Management Container (RDMC) to the current container.
RDMC + REE — intended to connect a previously created RDMC with a Reusable Execution Environment (REE) to the current container.
In the backend, RDMC and RDMC + REE map to RDMCUpload (UploadKind.RDMC in rdmc/models.py) and are recorded in manifest.rdmc, but neither type currently executes any active backend linking or container-resolution logic. See Workflow and RDMC Model Schema.
18. Where can I find shared helper functions for containers, manifests, and publications?
Reusable utilities are documented in Utility Functions, including GlobalVariables.get_or_create_container_id, GlobalVariables.get_container_detail, get_manifest_paths, get_container_view_context, get_container_metadata, ContainerUploadsHandler.get_target_uploads, view_manifest_content, ManifestValidationService.validate_manifest_content, ProjectVersion.get_active_version_number, build_container_entry, and current_publication / platform_label.
As a rule of thumb in Project Structure, place reusable utilities in helpers/ and complete end-to-end workflows in handlers/.
APIs & Integrations
19. Is there a REST API to create containers without the web UI?
Yes. The RDMC API is available under https://api.nfdixcs.org/rdmc_creation/ with interactive docs at https://api.nfdixcs.org/rdmc_creation/docs/. Every request needs the user’s token from the Personal Dashboard in an Authorization: Token <your_token> header. See RDMC API for the single-request and multi-step flows.
20. How do the single-request and multi-step RDMC API endpoints handle file uploads and errors?
The REST API supports two creation workflows (RDMC API):
Single-Request (``POST /create-full-rdmc/``) — builds and optionally seals a container in one call. If any step fails (such as a bad link, missing file, or invalid metadata), the entire container is rolled back and deleted automatically, so no cleanup is needed (Single Request Creation API).
Multi-Step — executes
/rdmc/init/,/rdmc/<container_id>/upload/, metadata, and seal in sequence using thecontainer_idfrom Step 1 (Multi-Step Creation API).
Sending plain JSON with local file paths only works when the server itself can read those paths. From a remote client, you must send multipart/form-data (with manifest, files, and zipped folder_zip parts) or use the provided Python example clients in etc/rdmc_api_example/.
21. Which external service APIs does the RDMC platform connect to?
The platform integrates with the following service APIs (configured in RDMC_Proto/settings.py):
RDMC Automation API:
https://api.nfdixcs.org/rdmc_creation/(docs:https://api.nfdixcs.org/rdmc_creation/docs/; see RDMC API)REE Service API:
https://ree.create.nfdixcs.org(REE_URL; see REE Service)Metabase / Ontology API:
https://api.nfdixcs.org/metabase(ONTOLOGY_API)Search Portal / Registry Service API:
https://api.nfdixcs.org/registryservice(SEARCH_API_BASE_URL; registration endpointPOST https://api.nfdixcs.org/registryservice/rdmcs, docs:https://api.nfdixcs.org/registryservice/docs; see Search Portal)Zenodo API Microservice:
https://api.nfdixcs.org/zenodo(ZENODO_API_BASE_URL; docs:https://api.nfdixcs.org/zenodo/docs; see Zenodo Integration)Dataverse & ePIC Handle Registry:
SERVER_URL_DATAVERSE(defaulthttps://data.goettingen-research-online.de) andhttps://hdl.handle.net/
22. How does the Zenodo integration work internally?
The RDMC Prototype communicates with a dedicated Zenodo API microservice.
The flow is: OAuth2 authorization → token exchange → file upload → metadata upload.
All calls go to https://api.nfdixcs.org/zenodo.
See Zenodo Integration for endpoint details and code examples.
23. How does the Search Portal registration work?
After publishing, a POST request is sent to https://api.nfdixcs.org/registryservice/rdmcs
with a JSON payload containing the container metadata, PID, and artifact details.
See Search Portal for the full payload structure and field reference.
24. When is the ePIC PID created and updated?
The PID (persistent identifier) is automatically created when the container is sealed and updated when it is published.
It is stored in the manifest.rdmc file and updated via the epic_handler in rdmc_publish/handlers/epic_pid.py.
25. Where is the PID stored?
The PID is saved directly inside the container’s manifest.rdmc file and can also
be viewed at any time via the Handle Registry.
Logging
26. How do I add logging to a new function?
Use the @log_process decorator — it automatically logs start, success, and failure:
import logging
from RDMC_Proto.log_utils import log_process
logger = logging.getLogger('app')
@log_process("My Process Label")
def my_function(request):
...
Always use logging.getLogger('app') — never the django logger for component-level code.
27. Where are log files stored and how long are they kept?
Logs are written to LOG_DIR in daily files (rdmc.YYYY-MM-DD.log).
User-specific logs go into a subfolder named after the user.
Files older than 30 days are automatically deleted on each rotation.
28. Why is my function logging a warning instead of success?
The @log_process decorator logs a warning if the wrapped function returns None.
Make sure your function explicitly returns a value.
Contributing & Issues
32. How do I report a bug or propose a change?
Open an issue on the GitLab issue tracker. Follow the workflow: Create → Assign → Link to Merge Request → Review → Close. Check closed issues first to avoid duplicates. See Open Issues for details.