Ordyn

Appearance

Cache Nodes ​

A cache node stores Ordyn-managed files close to endpoints so large downloads do not have to load via low bandwidth connections.

A cache node:

  • stores files that Ordyn uploads to it
  • serves endpoint downloads
  • keeps selected artifacts cached through prestaging rules
  • removes retention-managed files when they expire
  • supports upload windows and optional bandwidth limits for cache synchronization

Cache nodes work together with Edge services. Edge services keep endpoint and service-client connections alive. Cache nodes handle file storage and download delivery.

Requirements ​

Before installing a cache node, prepare:

  • a DNS name for the cache node, for example ordyn-cache.example.com
  • TLS Certificate for the DNS name
  • Traefik for public HTTPS routing
  • network access from the Ordyn server to the cache-node ip
  • enough disk capacity for packages, OS images, agent releases, etc.
  • Docker installation
  • Cosign installation
  • Traefik installation

Installation ​

Checkout the cache deployment folder from the Ordyn compose repository:

bash
apt install git
if [ ! -d /opt/ordyn-compose/.git ]; then
  git clone --filter=blob:none --sparse https://github.com/ordyn-project/compose.git /opt/ordyn-compose
fi
cd /opt/ordyn-compose
git sparse-checkout add cache

Create the cache environment file:

bash
cd /opt/ordyn-compose/cache
cp .env.example .env

Set these values in .env:

dotenv
SERVICE_DOMAIN=ordyn-cache.example.com
BACKEND_SOURCE_RANGE=172.17.0.0/16

SERVICE_DOMAIN is the public DNS name routed by Traefik and used by the cache node. BACKEND_SOURCE_RANGE restricts management routes; set it to the source range used by the Ordyn API host.

Start the container:

bash
cd /opt/ordyn-compose/cache
docker compose pull
python3 /opt/cosign-docker-verify/verify.py

Continue with docker compose up -d only when the cache image verifies successfully and no failed verification message appears.

bash
docker compose up -d

On first start, the cache node creates a pending local state and prints a remote bootstrap token in the container logs:

bash
docker compose logs cache

Copy the remote bootstrap token. The token is used once when the cache node is created in Ordyn.

Create The Cache Node In Ordyn ​

Open Administration > Services, select the Cache tab, and select Add cache node.

Enter:

  • Name: optional display name
  • Host: the DNS name only, for example ordyn-cache.example.com
  • Remote bootstrap token: the token shown by the pending cache container
  • Enabled: whether Ordyn should use the cache node for routing and synchronization
  • Retention: how long retention-managed files should stay cached
  • Allowed windows: optional upload windows and bandwidth limits

If no allowed windows are configured, cache uploads are allowed at any time.

After saving, Ordyn verifies the host, authenticates with the bootstrap token, and configures the remote cache node.

The cache node detail page should show: Bridge connected

Sync Windows And Retention ​

Sync windows control when Ordyn may upload files to the cache node.

Each window can define:

  • weekdays
  • start time
  • end time
  • optional bandwidth limit in MiB/s

Empty windows mean uploads are always allowed. If a window closes while a file is uploading, the current file finishes.

Retention controls when ordinary cached files become removable. Files protected by prestaging rules stay cached until the matching rule is changed or removed.

Prestaging ​

Prestaging rules keep matching artifacts cached on a cache node and protected from retention pruning.

Use prestaging when a site should already have files before endpoints need them, for example:

  • frequently installed packages
  • current agent releases
  • OS images used by local provisioning
  • files for a specific folder or software product

The Prestaging tab shows configured rules. Admins can add, edit, disable, or delete rules.

File Management ​

The Files tab lists files tracked by the cache node.

Admins with permission can delete selected cache-node files. Files that are still required by retention or prestaging policy may be automatically synchronized again.

Day-To-Day Operations ​

Disabling a cache node keeps the entry but prevents routing and bridge reconnects for that node.

Deleting a cache node removes the Ordyn entry and attempts to reset the remote cache node. If the remote reset cannot be completed, the UI shows a warning.

Reconfiguration ​

Use Reconfigure existing cache node only after the remote cache node has been reset and is pending again.

Typical cases:

  • the cache host was rebuilt
  • the persistent state file was removed
  • the cache node was reset outside Ordyn
  • the cache entry should point to a different cache host

When reconfiguring, paste the remote bootstrap token shown by the pending cache node.

For normal edits on the same host, leave Reconfigure existing cache node disabled and leave the bootstrap token field empty.

Security Guidance ​

  • Expose file download and upload routes only through HTTPS.
  • Restrict the management route to the Ordyn server.
  • Treat the remote bootstrap token as a secret.
  • Size the cache filesystem for expected package, OS image, and artifact usage.
  • Disable or delete a cache node when its host is decommissioned.

Cache nodes serve signed downloads. Even if the node is compromised an attacher will be unable to modify files in a way that is acceptable to the ordyn-agent.

Endpoint agents also enforce HTTPS, redirect, timeout, free-space, exact-size, and checksum rules before publishing a downloaded file. See Agent Runtime Limits.