Skip to main content

Deployment and Delivery

VCAL Semantic Cache is delivered by request as an optional module within a scoped AI Cost Firewall deployment. There is no public self-service download or installation channel.

This guide applies after VCAL has supplied the agreed artifact, license, and deployment details. Use the filenames, image references, checksums, ports, and capacity settings supplied with your package when they differ from the examples below.

Delivery package​

Depending on the agreed architecture, VCAL can provide:

  • an archived Docker container image;
  • a standalone Linux binary archive;
  • a signed license file and, where required, its verification public key;
  • SHA-256 checksums and release signatures;
  • an SBOM, OpenAPI definition, and Grafana dashboard;
  • deployment-specific configuration and support instructions.

Do not obtain production artifacts from an unofficial mirror or an old public release link. Contact VCAL if an artifact must be reissued or access must be renewed.

Prerequisites​

  • A scoped AI Cost Firewall or broader VCAL deployment
  • Linux x86_64 or aarch64 matching the supplied artifact
  • Docker for a container deployment, or a compatible Linux host for a binary deployment
  • The signed license and verification material supplied by VCAL
  • A persistent data directory with sufficient capacity
  • Optional Prometheus and Grafana integration
  • curl, jq, and sha256sum for verification and diagnostics

Verify supplied artifacts​

Compare the artifact with the checksum supplied in the same delivery package:

sha256sum -c <artifact>.sha256

If a signature is supplied, verify it using the release-signing public key provided by VCAL. The release-signing key is separate from the runtime license-verification key.

Container deployment​

Load the supplied image archive​

docker load -i <vcal-semantic-cache-image>.tar
docker image ls | grep vcal

Record the exact image name and immutable tag reported by docker load; use that value as <provided-image:tag> below.

Prepare persistent storage​

sudo mkdir -p /opt/vcal-semantic-cache/data /etc/vcal
sudo chown -R 10001:10001 /opt/vcal-semantic-cache/data

Place the supplied license and public key at the paths agreed for the deployment. Keep both files read-only and outside source control.

Start the container​

docker run -d \
  --name vcal-semantic-cache \
  --restart unless-stopped \
  -p 127.0.0.1:8084:8084 \
  --memory=2g \
  -v /opt/vcal-semantic-cache/data:/var/lib/vcal \
  -v /etc/vcal/license.json:/etc/vcal/license.json:ro \
  -v /etc/vcal/ed25519.pk.b64:/etc/vcal/ed25519.pk.b64:ro \
  --env-file /opt/vcal-semantic-cache/.env \
  -e VCAL_LICENSE_PATH=/etc/vcal/license.json \
  -e VCAL_LICENSE_PUBKEY_FILE=/etc/vcal/ed25519.pk.b64 \
  -e VCAL_DATA_DIR=/var/lib/vcal/data \
  <provided-image:tag>

Use the capacity, vector-dimension, authentication, persistence, and port settings agreed for the deployment. The values in the supplied .env file take precedence over generic examples in this documentation.

Verify health and readiness​

curl -fsS http://127.0.0.1:8084/healthz && echo "health OK"
curl -fsS \
  -H "X-VCAL-Key: <app_key>" \
  http://127.0.0.1:8084/readyz && echo "ready OK"

Standalone binary deployment​

Use this option only when VCAL has supplied a binary compatible with the target host.

Unpack and verify​

tar -xzf <vcal-semantic-cache-binary>.tar.gz
chmod 0755 vcal-server
./vcal-server --version

Prepare runtime paths​

sudo install -m 0755 vcal-server /usr/local/bin/vcal-server
sudo mkdir -p /var/lib/vcal/data /etc/vcal

Configure the service account, license paths, data directory, API keys, and environment according to the supplied deployment manifest. Run the process under a service manager such as systemd; do not run a production instance from an interactive shell.

Verify the service​

curl -fsS http://127.0.0.1:8084/healthz && echo "health OK"

Production requirements​

  • Keep the artifact, checksum, signature, SBOM, and deployment manifest together for auditability.
  • Use the exact immutable version supplied by VCAL.
  • Do not publish or redistribute the supplied container or binary.
  • Mount licenses and verification keys read-only.
  • Keep API keys and license material outside repositories and container images.
  • Persist the configured data directory on durable storage.
  • Set capacity below the effective container or host memory limit.
  • Test snapshot creation, restart recovery, graceful shutdown, and monitoring before production traffic.
  • Coordinate upgrades and replacement artifacts through the VCAL deployment contact.

Next steps​