Skip to content

Cache Nodes ​

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

Use cache nodes for endpoint downloads, prestaging frequently needed files, and public download links. Upload windows and bandwidth limits let you plan synchronization around site connectivity.

File protection ​

Cache nodes store encrypted copies for managed file transfers. Ordyn supplies decryption keys separately to authorized devices and browsers, which decrypt and verify the files locally. The cache node does not receive those keys.

Public download links and files served directly to network-boot clients use signed plaintext copies. A file can have both an encrypted copy and a signed plaintext copy on the same cache; allow disk space for both when those uses overlap.

Pinning and prestaging prepare encrypted copies.

Filesystem transfers ​

The endpoint filesystem explorer uploads and downloads directly between the browser and the assigned cache node. Browser networks must be able to reach the cache host over HTTPS.

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, Ordyn 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, retrieve the remote bootstrap token from 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.

Preserve the cache data when updating the host. A reset deployment must be registered again. Update the Ordyn server and cache-node containers in the same maintenance window to keep their versions compatible.

Create The Cache Node In Ordyn ​

Under Administration > Services > Cache, create a cache node using its DNS hostname and remote bootstrap token. Enter the hostname without https://.

Choose the retention period and, if needed, upload windows and bandwidth limits. Confirm that the node shows 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.

Jobs waiting for folder files respect these windows. Folder preparation has a 15-minute allowance that excludes time waiting for cache transfers or malware scans. The job's overall timeout still applies.

Retention controls when ordinary cached files become removable. Files protected by prestaging rules stay cached until the matching rule is changed or removed. Published downloads also protect the file content they require, independently of manual pins and prestaging rules.

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 Ordyn releases
  • OS images used by local provisioning
  • files for a specific folder or software product

Configure rules under the cache node’s Prestaging tab.

File Management ​

The Files tab lists files tracked by the cache node.

Delete cached files from this page when space needs to be reclaimed. Files required by published downloads cannot be evicted until those downloads are withdrawn or retargeted and the change has reached the cache. 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 stops new endpoint routing and synchronization. Published downloads are withdrawn when the change reaches the cache; an unreachable cache can continue serving its last applied links until their explicit expiry.

Delete the node’s published downloads and wait for the cache to apply the change before deleting the node. Deleting a cache node removes the Ordyn entry and attempts to reset the remote cache node. Check the result before reusing the host.

Reconfiguration ​

After rebuilding or resetting a cache host, use Reconfigure existing cache node with the new remote bootstrap token. Reconfigure only when the remote node is pending registration. Keep this option disabled for normal edits on the same host.

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.

Published downloads are available to anyone with the URL. Publish only files intended for that audience.

See Agent Runtime Limits for endpoint download requirements.