Getting Started

16. Getting Started

This page walks through running MedIntelOS locally for study or evaluation purposes, following the operational envelope described in Deployment, Operations, and Configuration. It is written for a reader who wants to explore the codebase hands-on rather than only read about it.

flowchart LR
    C1["Clone repository"] --> C2["Configure .env\n(development API key)"]
    C2 --> C3["docker compose up\n(or local Python venv)"]
    C3 --> C4["Call /fhir/R5/metadata\nto confirm the service is live"]
    C4 --> C5["Exercise FHIR CRUD,\nCDS Hooks, and CDSS endpoints"]
    C5 --> C6["Run pytest + ruff\nto reproduce CI locally"]
    C6 --> C7["Optionally: compile & test\nSolidity contracts via Hardhat"]

Loading

Figure 14. The local evaluation workflow, from cloning the repository through exercising the API and reproducing CI checks.

16.1 Prerequisites

• Docker and Docker Compose, for the containerized path described in Deployment, Operations, and Configuration, Section 10.1.
• Alternatively, a local Python environment matching the version pinned in the repository's packaging metadata, for running the FastAPI service directly.
• Node.js and a package manager (npm or pnpm), only if you intend to compile or test the Solidity consent contracts via Hardhat.

16.2 Running the API

The reference container is intentionally hardened by default — non-root, read-only root filesystem, dropped Linux capabilities, and a single exposed port (8080), as described in Deployment, Operations, and Configuration, Section 10.1. After bringing the service up, /fhir/R5/metadata is the fastest way to confirm it is live: it returns a CapabilityStatement generated from the same route table that implements it, so a successful response is also a statement of exactly what the running instance supports.

Every other route requires the X-API-Key header described in Security Architecture and Threat Model, Section 9.3. In development mode this is a static, documented value; Settings.validate() will refuse to start in a non-development environment unless that value has been replaced with a credential of at least 24 characters.

16.3 Exercising the FHIR, CDS Hooks, and CDSS Endpoints

The FHIR R5 Interoperability Layer page's example interaction (Section 4.4) is a good first call: creating a synthetic Patient resource exercises the authentication boundary, resource-type validation, version assignment, and audit emission in a single request. From there, /cds-services lists the available CDS Hooks services, and a patient-view call against synthetic vitals and labs will exercise the scoring pipeline described in The Clinical Decision Support Subsystem.

16.4 Reproducing CI Locally

Table 10. Local commands mirroring the CI workflow

Command	Purpose
ruff check .	Python linting, run as its own CI job
pytest	Python unit and API test suite (FHIR, CDSS, federated, audit, auth)
mypy src/medintelos	Optional, stricter static type checking (available, not gating)
Hardhat/Viem test suite (contract-tests/)	Solidity consent and audit-ledger contract tests, run as a separate CI job

16.5 Working With the Consent Contracts

If exploring the Solidity layer, follow the four-step deployment order described in Deployment, Operations, and Configuration, Section 10.3, on a local development chain only. The documentation is explicit that any deployment beyond a development chain should first go through static analysis, an independent audit, and a defined upgrade/pause strategy — none of which are substitutes for the Hardhat test suite, but all of which sit beyond what running the tests locally can establish.

16.6 A Reminder Before You Start

Every synthetic example in examples/ and throughout this wiki uses fabricated data. Per the project's own data rules, no real patient data, protected health information, or production credentials should ever be entered into a running instance of this reference implementation, on-chain or off.

---

Previous: ← Frequently Asked Questions · Next: API Reference Summary →