Deployment Operations and Configuration

10. Deployment, Operations, and Configuration

The repository ships a complete, if intentionally minimal, operational envelope: a Dockerfile and docker-compose.yml for local evaluation, a Makefile and CI workflow for linting and testing, and configuration surfaced entirely through environment variables read by a small Settings class in config.py. Figure 10 places the reference deployment against the production replacement points the documentation identifies for each of its components.

flowchart LR
    subgraph Ref["Reference Deployment (this repository)"]
        R1["Docker container\n(non-root, read-only fs)"]
        R2["Single static API key"]
        R3["In-memory FHIR store"]
        R4["In-process audit chain"]
        R5["Dev-chain consent contracts"]
    end
    subgraph Prod["Production Replacement (documentation-specified)"]
        P1["Orchestrated, autoscaled containers"]
        P2["OIDC / OAuth2 + key rotation"]
        P3["Durable, conformance-tested FHIR backend"]
        P4["Externally-anchored durable audit sink"]
        P5["Audited, multisig-governed permissioned chain"]
    end
    R1 -.->|replace| P1
    R2 -.->|replace| P2
    R3 -.->|replace| P3
    R4 -.->|replace| P4
    R5 -.->|replace| P5

Loading

Figure 10. The reference Docker Compose deployment on the left; the production-grade components the documentation specifies as required replacements on the right.

10.1 Container Hardening

The deployment guide notes several concrete hardening choices already applied to the reference container: it runs without root privileges, drops Linux capabilities, uses a read-only root filesystem, and exposes a single port (8080). These are inexpensive, high-value defaults that reduce the blast radius of a successful application-layer compromise, and their presence in an "alpha, educational" project is a useful signal of the engineering discipline applied elsewhere in the codebase.

10.2 Configuration Surface

Table 7. Configuration variables read by Settings

Variable	Purpose	Default
MEDINTELOS_APP_NAME	Service name reported in health checks and OpenAPI metadata	MedIntelOS
MEDINTELOS_ENVIRONMENT	Runtime environment label	development
MEDINTELOS_API_KEY	Reference API credential	Unsafe development value
MEDINTELOS_FHIR_BASE_URL	Base URL advertised in FHIR metadata	http://localhost:8080
MEDINTELOS_REQUIRE_API_KEY	Enables or disables the API-key boundary	true
MEDINTELOS_MAX_RESOURCE_BYTES	HTTP request-body size limit enforced by middleware	1,000,000

Settings.validate() is invoked at application-factory time and enforces the production-mode guard mentioned in Section 9.3: a non-development environment must not run with the built-in development API key, and any replacement key must be at least 24 characters. This validation runs before the FastAPI app is constructed, which means a misconfigured production deployment fails fast at startup rather than silently accepting an unsafe credential at request time.

10.3 Contract Deployment Sequence

The README specifies a fixed four-step sequence for deploying the consent layer:

flowchart LR
    S1["1. Deploy MedIntelOSAuditLedger\nwith the zero address"] --> S2["2. Deploy MedIntelOSConsentManager\nwith the ledger address"]
    S2 --> S3["3. Call setConsentManager\non the ledger"]
    S3 --> S4["4. Register and independently\nverify institution identities"]

Loading

The ordering matters: the audit ledger must exist before the consent manager can be told to log into it, and the ledger must in turn be told which consent-manager address is authorized to write to it, closing a circular dependency in a specific, replayable order. docs/DEPLOYMENT.md further recommends pinning compiler and dependency hashes, running static analysis, commissioning an independent audit, defining an upgrade and pause strategy, using a multisig administrator, and testing key loss before any contract deployment beyond a development chain.

10.4 Continuous Integration

The GitHub Actions workflow referenced by the README badge runs Python linting (ruff) and the test suite (pytest) on every change, with contract tests — the Hardhat/Viem suite in contract-tests/ — executed in a separate CI job appropriate to their different toolchain. mypy is available as an additional, stricter static-typing check invoked through the project's quality-check commands (ruff check ., pytest, mypy src/medintelos) but is described as available rather than gating, leaving type-strictness as a developer-invoked check rather than a hard CI requirement.

---

Previous: ← Security Architecture and Threat Model · Next: Validation Strategy and Evidentiary Gaps →