Configuration & secrets

Every service reads its configuration from environment variables, and every secret those services need — database credentials, the JWT signing key, provider API keys, storage and LiveKit keys — lives only on the host that runs the service. Nothing sensitive is ever committed to git. This page explains the model: how config lands on a host, where the secrets come from at deploy time, and which secret each service actually uses.

The model in one picture

Two rules follow from this diagram and they are the whole policy:

1. Source control holds code and .env.example only. The example file documents every variable a service expects, with placeholder values. The real .env is never committed and is listed in .gitignore.
2. Secrets enter at deploy time, not commit time. Jenkins pulls the real values from its credential store (or from Bitbucket repository / deployment variables) and writes them into the host's .env as the deploy step runs.

Each host gets a /opt/<service>/.env

Every Python service is started by systemd, and each unit points at a single EnvironmentFile on that host. The service reads its configuration from that file and nothing else — there are no config values hardcoded in the image, and no shared cluster config service.

The systemd units reference the file with EnvironmentFile=, so the values are loaded into the process environment at start. The fleet's templated unit is the only subtle one — a single .env on the host is shared by every worker instance, and the per-worker socket comes from the instance specifier, not from a secret:

# /etc/systemd/system/voxcore@.service (illustrative)
[Service]
Type=simple
EnvironmentFile=/opt/voxcore/.env
Environment=VOXCORE_SOCKET=/tmp/voxcore_%i.sock
ExecStart=/opt/voxcore/scripts/run_worker.sh
Restart=always

How Jenkins injects secrets at deploy time

The deploy stage of the pipeline is the only place real secrets touch a host. On a green build of main, Jenkins connects to each target host, refreshes the code, syncs dependencies, renders the host .env from credentials, then restarts the service. See the pipeline and deployment pages for the full flow; here is just the secret-handling part.

A declarative Jenkinsfile fragment, illustrative only — the real values come from the credential IDs, never from the file:

stage('Deploy Backend') {
  steps {
    withCredentials([
      string(credentialsId: 'ori-jwt-secret',   variable: 'JWT_SECRET'),
      string(credentialsId: 'ori-mongodb-uri',  variable: 'MONGODB_URI'),
      string(credentialsId: 'ori-redis-url',    variable: 'REDIS_URL'),
    ]) {
      sh '''
        ssh deploy@api-host '
          cd /opt/voxbridge &&
          git fetch --all && git checkout "$RELEASE_TAG" &&
          uv sync &&
          umask 077 &&
          cat > /opt/voxbridge/.env <<EOF
MONGODB_URI=${MONGODB_URI}
MONGODB_DB=voxbridge
REDIS_URL=${REDIS_URL}
JWT_SECRET=${JWT_SECRET}
JWT_ALGORITHM=HS256
JWT_EXPIRE_MINUTES=1440
VOXCORE_WSS_BASE_URL=wss://voice.example.com/ws
LOG_LEVEL=INFO
EOF
          systemctl restart voxbridge
        '
      '''
    }
  }
}

Console secrets are build-time, not runtime

The Console is a static single-page app. It has no runtime .env — its configuration is baked into the JavaScript bundle by Vite at build time through VITE_* variables. This is a different and important rule:

• The build reads brand variables (VITE_API_URL, VITE_BRAND_NAME, theme colours, the token storage key, etc.) and substitutes them into dist/ during npm run build.
• The output is served as static files by nginx. There is nothing to inject after the build; whatever was set at build time is permanent in that bundle.
• For Ori's single-brand repo the brand .env is committed at the brand path and the build copies it to the root .env, so the build is simply npm install && npm run build.

The secrets that matter, per service

These are the sensitive values each service needs. Non-secret config (ports, log levels, intervals, sample rates) is covered on the developer configuration page.

The shared VOXCORE_SECRET

VOXCORE_SECRET is the one secret that must be identical on two services: the dialler presents it and the fleet verifies it. When the dialler attaches an answered call to a free fleet worker over POST /attach, the fleet rejects the request unless the secret matches. If you rotate it, rotate it on the fleet hosts and the dialler host in the same window, or attaches will start failing.

Secret → service → where it's set

Rotating secrets safely

Secrets are not set once and forgotten. When you rotate one, do it deliberately and restart the services that read it.

The general rotation procedure:

Where to go next