Docker Deployment Guide

Run the FrameworX runtime inside Docker with built-in HTTP probes for container orchestration.

Reference → Runtime → Installation → Deployment → Docker

New in 10.1.5. Docker deployment is a supported production path for the .NET 10 runtime, with /health and /ready HTTP probes for Kubernetes and cloud orchestrators.

Location under review. Final placement pending the next doc pass.

The 10.1.5 runtime ships on .NET 10 and runs as a long-lived container process. Container orchestrators poll the HTTP endpoints exposed by the runtime and route traffic based on their responses.

This page covers image preparation, the runtime configuration needed inside a container, and the HTTP probe contract consumed by Kubernetes, Docker Swarm, and cloud marketplace images.

Runtime Requirements

.NET 10 runtime (the 10.1.5 runtime targets net10.0).
Linux or Windows container host. Both official .NET 10 base images work.
Writable volume for the solution folder, log folder, and Historian storage.
Exposed TCP port for the runtime HTTP endpoint. Default port is 3101 for the runtime service.
Network reachability to any connected PLCs, databases, MQTT brokers, and tRPC clients.

Image Layout

Place the runtime binaries under the container path /app/FactoryStudio and the solution under a mounted volume, for example /solutions/<SolutionName>. Log files go to /app/FactoryStudio/Logs.

HTTP Probes

The runtime exposes two probe endpoints on the same HTTP port as the main service. Both return a JSON body with snake_case fields.

Endpoint	Purpose	Success	Failure
`GET /health`	Liveness probe. Reports process health.	HTTP 200 with `status: healthy` or `status: starting`.	HTTP 503 with `status: unhealthy` and a `reason` field.
`GET /ready`	Readiness probe. Reports whether the runtime accepts traffic.	HTTP 200 with `is_ready: true`.	HTTP 503 with `is_ready: false` (starting, restarting, or unhealthy).

Response Body

{
  "status": "healthy",
  "reason": "",
  "version": "10.1.5.2010",
  "solution_name": "Plant1",
  "started_at_utc": "2026-04-19T13:22:10Z",
  "uptime_seconds": 3420,
  "is_ready": true,
  "module_statuses": {
    "Kernel": "ok",
    "Device": "ok",
    "Alarm": "ok",
    "Historian": "ok"
  }
}

Status Values

status	Meaning
`starting`	Process is up, modules not yet initialized. `/health` returns 200, `/ready` returns 503.
`healthy`	Runtime fully initialized and serving traffic. Both endpoints return 200.
`unhealthy`	A critical module failed or the health provider raised an exception. Both endpoints return 503.

The probe endpoints bypass the file-request block toggle. They answer even when IsFileRequestDisabled is set for the runtime HTTP server.

Dockerfile Example

FROM mcr.microsoft.com/dotnet/runtime:10.0

WORKDIR /app

COPY ./FactoryStudio /app/FactoryStudio
COPY ./Solution /solutions/Plant1

EXPOSE 3101

HEALTHCHECK --interval=10s --timeout=3s --start-period=30s --retries=3 \
  CMD curl --fail http://localhost:3101/health || exit 1

ENTRYPOINT ["dotnet", "/app/FactoryStudio/bin/net10.0/TStartup.dll", "/solution:/solutions/Plant1.tproj"]

Adjust the ENTRYPOINT to match the runtime service bundled in your image. The HEALTHCHECK directive lets Docker restart the container when the runtime reports unhealthy.

Kubernetes Manifest

Kubernetes maps the FrameworX probes to its liveness and readiness checks.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: frameworx-runtime
spec:
  replicas: 1
  template:
    spec:
      containers:
      - name: runtime
        image: tatsoft/frameworx-runtime:10.1.5
        ports:
        - containerPort: 3101
        readinessProbe:
          httpGet:
            path: /ready
            port: 3101
          initialDelaySeconds: 10
          periodSeconds: 5
        livenessProbe:
          httpGet:
            path: /health
            port: 3101
          initialDelaySeconds: 30
          periodSeconds: 15
          failureThreshold: 3

Kubernetes removes the pod from the Service endpoint list whenever /ready returns 503, then restarts it when /health fails failureThreshold consecutive probes.

Persistent Volumes

Path	Purpose	Mount Type
`/solutions`	Solution files (`.tproj`) and embedded datasets.	Persistent volume.
`/app/FactoryStudio/Logs`	Runtime trace logs.	Persistent volume or a log-forwarding sidecar.
`/app/FactoryStudio/Historian`	Built-in Historian storage when the solution uses it.	Persistent volume with IOPS matching your retention load.
`/app/FactoryStudio/certs`	PFX files for HTTPS. See TLS and SSL Configuration.	Secret-backed volume.

Cloud Marketplace Images

Tatsoft publishes prebuilt runtime images for Azure, AWS, and GCP marketplaces. Marketplace images ship with:

The same /health and /ready probe contract.
Environment variables for the solution path, HTTP port, and license activation.
A default non-root user and a minimal base image.

Point your orchestrator at the marketplace image tag for your target runtime version, mount a solution volume, and expose the HTTP port. No repackaging is required.

Troubleshooting

Symptom	Likely Cause	Next Step
`/ready` stuck on 503.	A module failed during initialization.	Read `module_statuses` in the JSON body. Check `/app/FactoryStudio/Logs`.
`/health` returns `status: starting` for longer than the start period.	The runtime is stuck loading the solution or waiting for a connection.	Raise Kubernetes `initialDelaySeconds`, or check PLC and database reachability from the pod.
Probe returns HTTP 404.	The runtime is older than 10.1.5 or the HTTP port is not the runtime port.	Confirm image tag is 10.1.5 or later. Confirm the mapped port is the tRPC HTTP port.

In this section...

The root page @parent could not be found in space FrameworX 10.1.

Page tree