eval_752
  • English

      • Backend Configuration Guide

      Last updated: 2026-03-13

      This guide explains which settings still belong in .env, and which runtime controls have moved into the UI and database.

      Environment Variables That Stay in .env

      These values still define bootstrap topology, infrastructure wiring, or build-time behavior. They are not workspace-level controls.

      Core Application Settings

      VariableDefaultPurpose
      APP_NAMEeval_752Service name written into logs and metadata.
      APP_ENVdevelopmentEnvironment label (development, staging, production).
      APP_LOG_LEVELINFODefault backend log level.
      DATABASE_URLrequiredPostgreSQL DSN, for example postgresql+psycopg://user:pass@host:5432/eval752.
      REDIS_URLrequiredRedis connection used by Celery, SSE fan-out, and caches.

      .env values are not recursively expanded. Do not write placeholders such as :${POSTGRES_PASSWORD} inside DATABASE_URL; use the literal password and keep it aligned with POSTGRES_PASSWORD.

      Celery and Worker Topology

      VariableDefaultPurpose
      CELERY_BROKER_URLemptyFalls back to REDIS_URL when unset.
      CELERY_RESULT_BACKENDemptyFalls back to REDIS_URL when unset.
      RUN_RETRY_POLL_INTERVAL_SECONDS30Celery beat interval for runs.retry_stalled.

      Runtime Engine and Feature Flags

      VariableDefaultPurpose
      LITELLM_BACKENDlitellmReserved backend switch for the SDK adapter layer.
      ARENA_ENABLEDtrueEnables the Arena feature surface.

      External Data and Secrets

      VariableDefaultPurpose
      HF_TOKENemptyRequired for private Hugging Face datasets.
      HF_CACHE_DIRemptyCustom Hugging Face cache directory.
      ENCRYPTION_KEYrequired32-byte hex key used to encrypt provider API keys. Generate it with openssl rand -hex 32.

      Docker Compose Convenience Variables

      VariableDefaultPurpose
      POSTGRES_DBeval752Compose database name.
      POSTGRES_USEReval752Compose database user.
      POSTGRES_PASSWORDchange-meCompose database password. Must match the password embedded in DATABASE_URL.

      Frontend Build and Proxy Settings

      VariableDefaultPurpose
      VITE_API_BASE_URL/apiBrowser-side API base URL. /api means the frontend or reverse proxy keeps forwarding.
      BACKEND_ORIGINhttp://backend:8000Used only by the frontend preview proxy to decide where /api/* goes.
      HEALTH_CHECK_TIMEOUT_SECONDS300CI and Compose smoke-test wait window.

      Runtime Controls That Moved into the UI and Database

      These values are now edited through Settings → Workspace runtime controls and persisted in the database. Changes apply to future runs without editing .env.

      UI controlMeaning
      Request timeoutTotal wall-clock timeout for one completion request.
      Max completion tokensPer-item completion ceiling. Empty means provider default behavior.
      Completion retriesCompletion client retry count.
      Completion retry backoffBase retry backoff in seconds.
      Run recovery attemptsMaximum number of automatic recovery attempts for stalled runs.
      Run recovery delayDelay before retrying a stalled run.
      Run recovery batch sizeMaximum stalled runs rescheduled per beat cycle.
      Cancellation check intervalHow often workers re-check cancellation state while processing a run.
      Cancellation cache TTLTTL for cached cancellation state in Redis.
      Use LightEval executorWhether future runs should use the LightEval execution path.

      When the database has no saved override yet, the backend falls back to built-in defaults. These values are no longer exposed in the normal deployment path through .env.example.

      Removed Legacy Variables

      The following variables were removed. If they still appear in .env or the process environment, the backend should fail fast during startup:

      • LITELLM_MODE
      • LITELLM_STUB_FAIL_ONCE
      • LITELLM_STUB_ALWAYS_FAIL
      1. Copy the template: cp .env.example .env
      2. Generate ENCRYPTION_KEY: openssl rand -hex 32
      3. Edit infrastructure values in .env, especially the database password and DATABASE_URL
      4. Start the stack
      5. Use the UI for workspace-level operations:
        • add a real provider in Providers
        • import or build a dataset in Datasets
        • tune runtime policy in Settings

      GitHub Actions and Secrets Guidance

      In CI/CD, these values are usually injected through Secrets or platform configuration:

      • DATABASE_URL
      • REDIS_URL
      • ENCRYPTION_KEY
      • HF_TOKEN if private datasets are required
      • POSTGRES_PASSWORD when Compose is used

      Workspace runtime controls should be persisted through the product UI rather than continuously overridden by CI secrets.

      Keep These Files in Sync

      When configuration changes, update all of the following:

      • backend/src/eval_752/app/config.py
      • .env.example
      • this document

      If a setting moves from environment configuration to a UI-persisted runtime control, also update the Settings page copy and the related acceptance docs.