Configuration

A self-hosted stack is configured with environment variables. Some are read by compose.yml and passed to the containers, the rest are read by the server, the cluster daemon or the deploy CLI directly. This page lists them with their defaults.

How to set variables

The deploy CLI keeps the stack's variables in the env object of ~/.volt-deploy/app-config.json and hands them to docker compose on every start. To change one, edit that object and apply it:

curl -fsSL https://raw.githubusercontent.com/voltlabs-research/volt/main/packages/apps/desktop/scripts/deploy.sh | bash -s -- --update --force

This works for the stack variables below, the ones compose.yml reads. The compose file passes a fixed list of variables to each container, so any other server or daemon variable needs a compose override file.

Variables the compose file doesn't pass

Write the extra variables in an override file, for example ~/.volt-deploy/compose.override.yml:

services:
  volt-server:
    environment:
      GITHUB_CLIENT_ID: "<client id>"
      GITHUB_CLIENT_SECRET: "<client secret>"
      GITHUB_CALLBACK_URL: "https://volt.example.org/api/auth/github/callback"
  cluster-daemon:
    environment:
      VOLT_DUCKDB_MEMORY_LIMIT_MB: "8192"

Then run compose yourself with the values the CLI uses, read from app-config.json (this needs jq):

cd ~/.volt-deploy
eval "$(jq -r '.env | to_entries[] | "export \(.key)=\(.value | @sh)"' app-config.json)"
export TEAM_CLUSTER_ID="$(jq -r '.bootstrap.teamClusterId' app-config.json)"
export DAEMON_PASS="$(jq -r '.bootstrap.daemonPassword' app-config.json)"
export VOLT_SOURCE_DIR="$(find "$PWD/downloads/voltlabs-research/volt" -mindepth 1 -maxdepth 1 -type d | head -n 1)"

docker compose -f compose.yml -f compose.override.yml --profile enrolled up -d

Add -f compose.images.yml before the override if you use prebuilt images, and leave out --profile enrolled on a server-only deployment.

Stack variables

Read by compose.yml. The CLI writes SECRET_KEY, SSH_KEY, WEB_PORT, SERVER_PORT, DEPLOYMENT_MODE, CLIENT_HOST and SERVER_ENDPOINT into app-config.json, and sets TEAM_CLUSTER_ID, DAEMON_PASS and VOLT_SOURCE_DIR itself on every start.

CLIENT_HOST and SERVER_ENDPOINT contain the ports, so update them when you change WEB_PORT or SERVER_PORT.

The compose file fixes the rest of what the containers need: the server listens on 0.0.0.0:8000 with SERVER_DATA_DIR=/var/lib/volt-server; the daemon runs with NODE_ENV=production, VOLT_CLOUD_URL=http://volt-server:8000, DAEMON_DATA_DIR=/var/lib/volt-daemon and BUCKET_PREFIX=cluster-.

Server

Sign-in providers

A provider appears on the sign-in page once its client ID is set. Register <SERVER_ENDPOINT>/api/auth/<provider>/callback as the callback URL with the provider.

The compose file doesn't pass these, so set them in an override file.

Cluster daemon

These apply to the daemon in the stack and to daemons on enrolled machines.

In the stack, the compose file passes only DAEMON_HEAP_MB among the tuning variables; set the others in an override file.

Web client build variables

The web client reads these when it's built, not at run time. The stack's client image sets neither: it uses the server of the origin it's served from.

Deploy script and CLI

Read by deploy.sh and the deploy CLI on the host. Set them on the bash side of the pipe, for example curl ... | VOLT_DEPLOY_DIR=/srv/volt bash.

The CLI always installs the source of the latest release of voltlabs-research/volt; VOLT_REPO_URL only changes where the script downloads the CLI and the compose file from.

Deployment modes

DEPLOYMENT_MODE tells the server whether it serves one person or many, and the client adapts its interface to it.

In local mode the client hides what only makes sense with other people:

• My Team and Manage Roles in the navigation, and Authentication and Sessions in the settings.
• The team switcher, the Team actions menu (Create team, Join existing team) and Invite members in the header.
• The user menu with Account Settings and Sign Out.
• Profile and Delete Account in the general settings.
• Have an invite code? during onboarding.
• Who else is online, in the jobs status, on whiteboards and in the canvas.

local is meant for the single-user stacks the browser and the desktop app provision, where the local account exists. Run a self-hosted server in cloud mode, as the CLI does, even though compose.yml alone defaults to local.

To see a server's mode, ask it:

curl -s http://localhost:8100/api/system/config
# {"status":"success","data":{"mode":"cloud"}}

Ports

Volumes

Back up the three named volumes together with ~/.volt-deploy/app-config.json. The volumes hold the data, and app-config.json holds the secrets needed to read the credentials stored in it.