Deployment and Packaging

    This guide describes the deployment assets that exist in the repository today and how to read their intended scope.

    Packaging posture today

    The current packaging assets are intentionally baseline-oriented:

    • systemd scaffolds target the shared byteor-runtime entrypoint,
    • container baselines exist for byteor-runtime, byteor-edgeplane, byteor-actiongraph, and byteor-dataguard,
    • the same environment and path conventions are reused across the enterprise binaries.

    Treat these assets as the canonical starting point for operator bring-up, not as a fully productized installer stack.

    Systemd deployment

    The repository currently ships these systemd assets:

    Deployment shapeFiles
    SingleRingsystemd/byteor-runtime.service, systemd/byteor-runtime.env.example
    LaneGraph single-processsystemd/byteor-runtime-lanegraph.env.example
    LaneGraph multi-processsystemd/byteor-runtime-mp-supervisor.service, systemd/byteor-runtime-role@.service, systemd/byteor-runtime-mp.env.example

    Important scope note: the checked-in systemd units are for the shared runtime CLI. They are still the best reference even when you need a product-specific unit, because the path, tuning, and scheduler conventions are the same.

    Use systemd when:

    • the host owns /run/byteor and /dev/shm,
    • you want the runtime posture to follow the standard tuning presets,
    • you need long-lived service management rather than ad hoc container runs.

    Container deployment

    The container baselines live under packaging/container/:

    ContainerfileBinary
    Containerfilebyteor-runtime
    Containerfile.edgeplanebyteor-edgeplane
    Containerfile.actiongraphbyteor-actiongraph
    Containerfile.dataguardbyteor-dataguard

    The build context must be the repo root because the containerfiles copy the sibling indexbus, byteor, and byteor-enterprise workspaces together.

    All runtime containers still need the same fundamental mounts and conventions:

    • a spec mounted at /etc/byteor/spec.kv,
    • a writable runtime directory mounted at /run/byteor,
    • a suitable shared-memory backing such as /dev/shm.

    Use containers when:

    • you need a product-specific binary image,
    • you want to package the enterprise runtime with cluster-native supervision,
    • you already have a separate mechanism for CPU, SHM, and memory-lock policy.

    Environment variable conventions

    The shared conventions come from byteor-core plus the checked-in systemd examples.

    VariableMeaning
    BYTEOR_SPECdefault spec path used by packaging scaffolds
    BYTEOR_LANE_PATHSingleRing lane-path mapping file
    BYTEOR_SHM_DIRLaneGraph shared-memory directory
    BYTEOR_WAITwait preset such as spin or backoff
    BYTEOR_MLOCKALLmemory-lock preset
    BYTEOR_PINpinning preset
    BYTEOR_SCHEDscheduler preset
    SHM_PARENTshared-memory parent used by runtime tooling

    Current default paths are aligned around the standard host layout:

    • /etc/byteor/spec.kv
    • /run/byteor
    • /dev/shm

    The runtime will derive deterministic service paths under /run/byteor when possible. That is why the shipped scaffolds converge on names like single_ring.shm instead of per-run temporary mappings.

    Choosing the right deployment baseline

    If you need...Prefer...
    a host-native long-running servicesystemd scaffolds plus the runtime env examples
    a product-specific image boundarythe container baselines
    the fastest local proof of a spec or rule changecargo run -p <binary> -- ... with the same env conventions
    controlled promotion from proof run to steady statebounded run --sp or --adapter-max-messages before unbounded service mode

    Use operator-flow.md alongside this guide so packaging choices and incident handling stay aligned.

    Provenance
    Need the canonical source?
    Use the public hub to orient yourself, then jump to repo-owned docs or rustdoc when you need contract-level detail.
    Source-of-truth modelRepo docs index