Configuration & Environment Variables

Relevant source files

The following files were used as context for generating this wiki page:

• src/env.ts
• README.md
• docker-compose.prod.yml
• src/app.ts
• stt/src/main.rs
• src/deploy.ts
• src/utils/writeToLog.ts

Configuration for the Discord Live Translator is managed primarily through environment variables. This approach allows for flexible deployment, especially when using Docker. The system uses the @t3-oss/env-core library to validate and type-check environment variables at runtime, ensuring that the application starts with a valid configuration.

A .env file is the primary method for setting these variables during local development or self-hosting with Docker. The application is composed of several services, each with its own configuration needs, which are orchestrated using docker-compose.

Environment Variable Loading and Validation

The project ensures type-safe access to environment variables by processing them through a validation schema upon application startup. This is handled in src/env.ts.

The process uses dotenv to load variables from a .env file into process.env. Then, @t3-oss/env-core with a zod schema validates, parses, and exports the typed variables for use throughout the application. If a required server-side variable is missing, the application will fail to start.

Sources: src/env.ts:4-8

This diagram illustrates the flow of loading and validating environment variables.

Zod Schema Definition

The core of the validation is the Zod schema, which defines the expected type for each variable.

// src/env.ts:10-23
const env = createEnv({
  clientPrefix: 'PUBLIC_',
  client: {},
  server: {
    BOT_TOKEN: z.string(),
    CLIENT_ID: z.string().optional(),
    GUILD_ID: z.string().optional(),
    LOG_PATH: z.string().optional(),
    POSTHOG_API_KEY: z.string().optional(),
    POSTHOG_HOST: z.string().optional().default('https://app.posthog.com'),
    REDIS_URL: z.string().optional(),
    STT_HOST: z.string(),
    TRANSLATION_HOST: z.string(),
    HEARTBEAT_URL: z.string().url()
  },
  runtimeEnv: process.env
});

Sources: src/env.ts:10-23

Core Application Variables

These variables are defined in src/env.ts and are used by the main bot application.

Variable	Required	Description	Default Value
BOT_TOKEN	Yes	The Discord bot token.
CLIENT_ID	No	The Discord application's client ID. Required for deploying slash commands.
GUILD_ID	No	If set, slash commands are automatically deployed to this specific guild on startup.
LOG_PATH	No	An absolute or relative path to a file where logs will be appended.
POSTHOG_API_KEY	No	API key for PostHog telemetry.
POSTHOG_HOST	No	The host for the PostHog instance.	https://app.posthog.com
REDIS_URL	No	The connection URL for the Redis instance.
STT_HOST	Yes	The URL for the Speech-to-Text (STT) service.
TRANSLATION_HOST	Yes	The URL for the LibreTranslate service.
HEARTBEAT_URL	Yes	A URL to which a POST request is sent every minute as a health check.

Sources: src/env.ts:13-21, README.md:21-22, src/app.ts:58-60, src/utils/writeToLog.ts:11-15

Docker Deployment Configuration

The docker-compose.prod.yml file defines the multi-container setup for production. It orchestrates the main bot, the Speech-to-Text (STT) service, a LibreTranslate instance, and a Redis database. Environment variables are crucial for linking these services.

This diagram shows the services defined in the Docker Compose file and how they are configured.

Service Definitions

bot service

The main application container. It depends on all other services to be running.

# docker-compose.prod.yml:4-15
services:
  bot:
    image: ghcr.io/wotschofsky/discord-live-translator
    restart: always
    env_file: .env
    environment:
      - REDIS_URL=redis://redis:6379
      - STT_HOST=http://stt:8000
      - TRANSLATION_HOST=http://libretranslate:5000
    depends_on:
      - stt
      - libretranslate
      - redis

• env_file: .env: Loads variables like BOT_TOKEN and CLIENT_ID from a local .env file.
• environment: Sets specific variables to connect to other Docker services by their service name (e.g., http://stt:8000).

Sources: docker-compose.prod.yml:4-15, README.md:21-22

stt service

The custom Speech-to-Text service built in Rust. It requires a MODEL_PATH environment variable to be set within its own environment to locate the Whisper model. This variable is not set in the docker-compose.prod.yml but is expected by the service's code.

// stt/src/main.rs:10-15
lazy_static! {
    static ref WHISPER: WhisperContext = WhisperContext::new_with_params(
        env::var("MODEL_PATH")
            .expect("MODEL_PATH is not set in env")
            .as_str(),
        WhisperContextParameters::default()
    )
    .expect("failed to load model");
}

Sources: stt/src/main.rs:10-15, stt/src/main.rs:49-52

libretranslate service

The translation service. The LT_LOAD_ONLY variable is used to restrict which language models are loaded into memory, saving resources.

# docker-compose.prod.yml:23-28
  libretranslate:
    image: libretranslate/libretranslate:v1.3.11
    restart: always
    environment:
      - LT_LOAD_ONLY=de,en,es,fr,it

Sources: docker-compose.prod.yml:23-28

Slash Command Deployment

Environment variables CLIENT_ID and GUILD_ID control how slash commands are deployed to Discord.

Automatic Guild Command Deployment

If both CLIENT_ID and GUILD_ID are provided as environment variables, the application will automatically register/update the slash commands for that specific guild every time the bot starts. This is useful for development and testing on a single server.

The following diagram shows the logic flow on application startup.

Manual Global Command Deployment

For production, commands can be deployed globally using a script. This is a one-time action. The pnpm run deploy script executes src/deploy.ts, which requires BOT_TOKEN and CLIENT_ID to be set in the environment.

// src/deploy.ts:4-6
if (!env.CLIENT_ID) {
  throw new Error('CLIENT_ID is not set!');
}

This script calls initGlobalCommands, which sends the command definitions to Discord's global endpoint.

Sources: src/deploy.ts:4-6, README.md:28-30, package.json:11