Application Definition#

OpenFactory applications are a particular type of OpenFacotry Assets. They are defined declaratively using YAML.

Each application describes:

which container image to run
how container images are refreshed during deployment
how it integrates into the Unified Namespace (UNS)
how it is configured and deployed
how it is optionally exposed externally

Minimal Example

apps:
  scheduler:
    uuid: "app-scheduler"
    image: ghcr.io/openfactoryio/scheduler:v1.0.0

Schema Overview#

Each application supports the following sections:

uuid — Asset UUID identifier of the application
image — Docker image to run
image_pull_policy — image pull behavior during deployment
runtime_uid — User UID in the runtime
runtime_gid — User GID in the runtim
uns — Unified Namespace metadata
environment — environment variables
storage — storage backend configuration
routing — HTTP exposure configuration
networks — Docker networks
deploy — deployment configuration

UUID#

Each application must define a unique identifier:

uuid: app-scheduler

This value is used by OpenFactory as Asset UUID.

Image#

The Docker image defines the application runtime:

image: ghcr.io/openfactoryio/scheduler:v1.0.3

Image Pull Policy#

The image_pull_policy controls how OpenFactory obtains container images during deployment.

Supported values:

missing — pull the image only if it is not available locally.
always — always pull the image before deployment.

Example:

image: ghcr.io/openfactoryio/scheduler:latest
image_pull_policy: always

This is particularly useful when using mutable image tags such as latest.

Runtime UID and GID#

The UID and GID of the user int he runtime can be configured:

runtime_uid: 1200
runtime_gid: 1210

Both entries (runtime_uid and runtime_gid) must be defined together.

UNS (Unified Namespace)#

The uns section defines how the application is represented in the OpenFactory Unified Namespace.

uns:
  location: building-a
  workcenter: scheduler

The structure must comply with the configured UNSSchema.

Environment Variables#

Environment variables can be passed to the container:

environment:
  - ENV=production
  - LOG_LEVEL=info

Storage#

Applications can mount persistent storage using a configured backend.

Example (NFS):

storage:
  data:
    type: nfs
    server: deskfab.openfactory.com
    remote_path: /nfs/data
    mount_point: /mnt/data
    mount_options:
      - rw
  config:
    type: nfs
    server: deskfab.openfactory.com
    remote_path: /nfs/config
    mount_point: /mnt/config
    mount_options:
      - ro

Multiple storage backends are supported.

Routing (HTTP Exposure)#

Applications can be exposed externally via HTTP.

routing:
  expose: true
  port: 8000
  hostname: dashboard

Hostnames#

When routing is enabled, OpenFactory generates:

a canonical hostname (always present):
```
<uuid>.<base-domain>
```
an optional alias hostname (if available):
```
<hostname>.<base-domain>
```

Example:

scheduler-a1b2.example.com
dashboard.example.com

Networks#

Applications can be connected to one or more Docker networks:

networks:
  - factory-net
  - monitoring-net

All networks must exist prior to deployment.

Deployment#

The deploy section defines how the application is deployed.

deploy:
  replicas: 2

  resources:
    reservations:
      cpus: 0.5
      memory: "512Mi"
    limits:
      cpus: 1.0
      memory: "1Gi"

  placement:
    constraints:
      - node.labels.zone == building-a

Complete Example

apps:
  scheduler:
    uuid: "app-scheduler"
    image: ghcr.io/openfactoryio/scheduler:latest
    image_pull_policy: always
    runtime_uid: 1200
    runtime_gid: 1210

    uns:
      location: building-a
      workcenter: scheduler

    environment:
      - ENV=production

    storage:
      type: nfs
      server: deskfab.openfactory.com
      remote_path: /nfs/deskfab
      mount_point: /mnt
      mount_options:
        - ro

    routing:
      expose: true
      port: 8000
      hostname: dashboard

    networks:
      - factory-net
      - monitoring-net

    deploy:
      replicas: 2

      resources:
        reservations:
          cpus: 0.5
          memory: "512Mi"
        limits:
          cpus: 1.0
          memory: "1Gi"

      placement:
        constraints:
          - node.labels.zone == building-a

Note

Configuration is strictly validated (unknown fields are rejected)
UNS metadata must match the configured schema
Hostnames are normalized and validated to comply with DNS rules
A canonical hostname is always generated when routing is enabled
image_pull_policy: always is recommended when using mutable image tags such as latest.