Skip to main content

Installation

This guide explains how to install and run VCAL Server using Docker or a standalone binary.

VCAL Server requires a valid license file to start. A 30‑day Trial license can be obtained self‑serve via the CLI.

Prerequisites​

  • Linux (x86_64 or aarch64)
  • Docker or standalone binary
  • Optional: Prometheus & Grafana for monitoring

macOS binaries are planned but not yet available.

Option A — Docker (recommended)​

Docker is the fastest way to get started and is the recommended option for evaluation and production.

0. Create a persistent host directory​

mkdir -p ./vcal-data

# If you see "Permission denied" on Linux (container runs as UID 10001):
sudo chown -R 10001:10001 ./vcal-data

This directory will store:

  • cache data
  • snapshots
  • license file

1. Request a 30‑day Trial license​

Run the licensing command inside the image:

docker run --rm -it \
  -v "$(pwd)/vcal-data:/var/lib/vcal" \
  -e VCAL_LICENSE_PATH=/var/lib/vcal/license.json \
  ghcr.io/vcal-project/vcal-server:latest \
  license trial <your_email>

A verification code will be sent to your email.

2. Verify the code and write the license file​

docker run --rm -it \
  -v "$(pwd)/vcal-data:/var/lib/vcal" \
  -e VCAL_LICENSE_PATH=/var/lib/vcal/license.json \
  ghcr.io/vcal-project/vcal-server:latest \
  license verify <code>

The license is written to:

./vcal-data/license.json

You can confirm it exists:

ls -la ./vcal-data && jq . ./vcal-data/license.json

3. Start VCAL Server​

docker run --rm -p 8080:8080 \
  -v "$(pwd)/vcal-data:/var/lib/vcal" \
  -e VCAL_LICENSE_PATH=/var/lib/vcal/license.json \
  -e VCAL_DIMS=768 \
  -e VCAL_CAP_MAX_BYTES=8589934592 \
  -e RUST_LOG=info \
  ghcr.io/vcal-project/vcal-server:latest

The server will refuse to start if the license file is missing or invalid.

4. Health check​

curl -fsS http://localhost:8080/healthz && echo "OK"

Option B — Standalone Binary​

1. Download and unpack​

tar -xzf vcal-server-linux-*.tar.gz
chmod +x vcal-server

# Optional system install:
# sudo install -m 0755 vcal-server /usr/local/bin/vcal-server

2. First start (no license yet)​

export VCAL_DIMS=768   # set dims supported by your app
./vcal-server
# (or `vcal-server` if installed system-wide)

The server will print instructions on how to obtain a trial license.

3. Request a 30‑day Trial license​

Write the license to a user‑writable location:

export VCAL_LICENSE_PATH="$PWD/license.json"
./vcal-server license trial <your_email>

Option B (system‑wide)​

Write the license to /etc/vcal/license.json (requires sudo):

sudo VCAL_PENDING_EMAIL_PATH=/etc/vcal/pending_email.txt \
  ./vcal-server license trial <your_email>

A verification code will be sent to your email.

4. Verify the code and write the license file​

# Option A (no sudo)
./vcal-server license verify <code>

# Option B (system‑wide)
sudo VCAL_PENDING_EMAIL_PATH=/etc/vcal/pending_email.txt \
  ./vcal-server license verify <code>

5. Start VCAL Server​

./vcal-server
# (if you used Option A, keep VCAL_LICENSE_PATH set in the environment)

6. Health check​

curl -fsS http://localhost:8080/healthz && echo "OK"

Alternative (also no sudo)​

You may keep the license in a stable location under your home directory:

export VCAL_LICENSE_PATH="$HOME/.vcal/license.json"
vcal-server license trial <your_email>
vcal-server license verify <code>
vcal-server

This avoids relying on the current working directory.

Growth / Enterprise licenses​

For Growth and Enterprise, you will receive a signed license file.

Mount or place it and start the server with:

-e VCAL_LICENSE_PATH=/var/lib/vcal/license.json

See Licensing for details.

Notes​

  • VCAL Server will not start without a valid license
  • Trial licenses are time‑limited (30 days)
  • Growth and Enterprise licenses are issued on request
  • License files must be readable by the VCAL Server process