Server installation#

The runtime service is the long-lived HTTP API used for session-based processing. Install the server extras when MoDaCor needs to accept files over time, reuse cached session state, or be driven by an instrument control system.

For a released package:

pip install "modacor[server]"

For a source checkout:

pip install -e ".[server]"

Some pipelines need additional optional extras. Install them alongside server when the pipeline uses those modules:

  • plotting for runtime Plotly visualization sinks.

  • attenuation for detector-efficiency and attenuator corrections backed by attenuation coefficients.

  • masks for mask morphology helpers.

For example:

pip install -e ".[server,plotting,attenuation,masks]"

Start a local service#

Use the CLI entry point for local notebooks and trusted single-user workflows:

modacor serve --host 127.0.0.1 --port 8000

The service exposes:

  • GET /v1/health for liveness.

  • GET /v1/readiness for runtime readiness and high-level session metrics.

  • GET /docs for FastAPI’s generated interactive endpoint browser.

Start a restricted service#

Use the restricted runtime policy for network-facing or containerized services. It disables arbitrary pipeline YAML paths, disables filesystem module discovery, disables arbitrary custom IO class imports, and requires source/sink paths to stay under configured roots.

modacor serve \
  --host 0.0.0.0 \
  --port 8000 \
  --runtime-policy restricted \
  --read-root /srv/modacor/pipelines \
  --read-root /data \
  --write-root /srv/modacor/output \
  --max-sessions 8 \
  --max-pipeline-yaml-bytes 262144 \
  --max-buffer-upload-bytes 104857600

The runtime service does not provide its own authentication or TLS termination. Put network-facing deployments behind the facility’s authenticated proxy or service mesh.

Create a session from the CLI#

Once the server is running, modacor session commands call the HTTP API:

modacor session --url http://127.0.0.1:8000 create \
  --session-id i22-saxs \
  --name "I22 SAXS" \
  --pipeline-yaml-path /srv/modacor/pipelines/I22_SAXS_solids_operando.yaml \
  --trace

modacor session --url http://127.0.0.1:8000 set-source \
  --session-id i22-saxs \
  --ref sample \
  --type hdf \
  --location /data/current_sample_modacor.nxs

modacor session --url http://127.0.0.1:8000 process \
  --session-id i22-saxs \
  --mode full \
  --run-name first-sample

For a restricted service, submit pipeline.yaml_text through the REST API or run session creation from a trusted local deployment that permits pipeline_yaml_path.

The endpoint shapes, state machine, partial-rerun behavior, and error payloads are documented in Runtime Service API.