Quick Start#
A guided tutorial through the FERRY institutional workflow.
This tutorial walks through the complete lifecycle of an analysis: from installation through to downloading results. It is designed for someone evaluating FERRY for the first time.
Before you begin#
Verify the platform is running and accessible at
https://localhost.Ensure at least one data resource is registered. The Data Resources administrator guide covers the full workflow. For evaluation, the
demo-surveillanceresource is registered automatically during installation.Create evaluation persona accounts:
make seed-demo
This creates three accounts and prints their credentials. You will need all three to complete the tutorial.
Step 1 — Log in as the Researcher#
Open https://localhost in your browser and log in with the Researcher credentials printed by make seed-demo.
The Researcher is the person who creates analyses. A researcher does not have the authority to approve bundles, release outputs, or manage the platform — they can create projects, build analysis bundles, run validation, and submit work for review.
When you log in, the homepage displays quick actions relevant to a researcher: Create Project and View Bundles. This is the responsibility-oriented UI — what you see depends on your role.
Step 2 — Accept Platform Terms#
Before you can use the platform, you must accept the current version of the platform terms of service.
If terms have been published by the administrator, you will be redirected to the terms page on your first action. Read the terms and click Accept.
Acceptance is permanently recorded. You will not be asked again unless the institution publishes an updated version.
Step 3 — Create a Project#
A Project is a permission boundary and collaboration space. It groups related analyses and controls which data resources they may access.
Click Create Project, give it a name (for example, “COVID-19 Seroprevalence Analysis”), and add a brief description. You are automatically added as the first project member.
The project appears in your Projects list. Other users can be added later by someone with the project.members.manage capability.
Step 4 — Configure Project Resources#
A project needs data resources to analyse. Click into your project and navigate to the Resources tab.
The platform has pre-seeded data resources from manifests. Select the one that matches your intended analysis and attach it to the project.
Before attaching, you may be prompted to accept the dataset terms of service if the resource has published terms. Dataset terms are set by the data owner and are separate from the platform terms you accepted earlier.
Attaching a resource tells the platform: “this project is authorised to analyse this dataset.” The actual data never leaves the institution’s secure storage — the platform records the authorisation, not the data itself.
Step 5 — Import the Example Analysis#
Navigate to the Bundles tab and click Create Bundle.
An Analysis Bundle describes what to run, which execution environment to use, and which resources to access. It is a researcher artefact — you own it and control it until you submit for review.
Select an execution environment from the catalogue. The available environments (Python 3.13, Python 3.14, Conda) are curated by the institution. Each represents a guaranteed runtime contract.
Upload the example analysis files. You can use an analysis template from examples/analyses/ if one is available, or prepare your own ZIP archive with an entry point script.
Configure the entry point, interpreter, and CLI arguments. The bundle workspace saves your progress automatically.
Step 6 — Run Validation (Advisory)#
Before submitting for review, you can run an operational Validation check.
Validation executes your bundle against representative datasets — structurally identical to the governed data but containing no sensitive information. It answers one question: does the analysis code execute successfully?
Click Run Validation in the bundle workspace. The worker polls for pending validation requests, launches an isolated container, runs your analysis against representative data, and reports the results.
Validation is advisory. You can submit without validating. But if validation succeeds, you have confidence the analysis will run in production.
A Validated indicator appears on the bundle to record this check. If you modify the bundle after validation, the indicator changes to warn that the bundle has changed.
Step 7 — Submit for Review#
When you are ready, click Submit for Review.
Submission transitions the bundle from DRAFT to SUBMITTED status. No further edits are permitted — the bundle is now an immutable artefact awaiting institutional governance.
Submission triggers a Build. The worker processes the bundle: if the build strategy is Institutional, it uses the curated template for the selected execution environment; if Custom Build, it uses the Dockerfile in your bundle. The resulting Execution Image is cached for reuse.
Submitting also sends an email notification to project members with review capability, alerting them that a bundle is waiting.
Step 8 — Log in as the Moderator#
Log out of the Researcher account and log in with the Moderator credentials.
The Moderator is the person who governs what enters and leaves the institution. A moderator can review bundles and output sets but cannot release outputs or manage the platform.
The homepage now shows different quick actions: review-related tasks take priority.
Step 9 — Review and Approve the Bundle#
Navigate to the project and find the submitted bundle under Bundles Pending Review.
Inspect the bundle details: the declared execution environment, the data resources it requests, the entry point, and the build strategy. The bundle is immutable at this point — what you see is exactly what will execute.
Click Approve to transition the bundle to APPROVED_FOR_EXECUTION status. This is the first stage of the two-stage governance gate. It means: this analysis is authorised to execute against governed data.
You may also Reject a bundle (with a reason) or Supersede it (when a newer version replaces an older approved one).
Step 10 — Log in as the Researcher and Request Execution#
Log out of the Moderator and log back in as the Researcher.
Navigate to your approved bundle. You can now create an Execution Request — an instruction to execute this specific bundle with specific parameters.
Click Request Execution. This creates a PENDING execution request. The worker picks it up, resolves the data resource endpoints, launches an isolated container, executes the analysis, and captures the outputs.
The execution status progresses: PENDING → RUNNING → COMPLETED (or FAILED). During execution, the analysis runs in a container with:
no network access
read-only data mounts
non-root user
configurable timeout
After completion, an Output Set is created in PENDING_REVIEW status. The researcher cannot access the outputs yet — they must pass governance first.
Step 11 — Review and Approve the Output Set#
Log in as the Moderator again.
Navigate to the Output Sets Pending Review section. You can inspect individual output files and execution metadata to verify the results are appropriate for release.
Click Approve to transition the Output Set to APPROVED status. This is the second governance gate: these outputs are safe to release.
Step 12 — Release the Output#
Still as the Moderator (or as a Maintainer, who has additional release capability), click Release.
Release transitions the Output Set to RELEASED status and creates a Release Package — a ZIP archive containing the output files and execution metadata. This is the sole delivery mechanism for research results.
The researcher is notified by email that results are available.
Step 13 — Download the Results#
Log in as the Researcher for the final step.
Navigate to the execution request. The Download button is now active. Download the Release Package ZIP.
The ZIP contains:
All output files from the analysis
execution_metadata.json— metadata about the execution (request details, file listing)
Summary#
You have completed the full FERRY institutional workflow:
Prepare → Validate → Submit → Review → Execute → Review → Release → Download
This is the governed research pipeline. Every transition is recorded in the audit ledger, attributable to the authenticated actor who performed it.
Next steps#
Researcher Guide — detailed researcher workflows
Moderator Guide — review and governance tasks
Architecture — system design and concepts