X-Go Gen-code

Configuration

X-Go applications are configured through environment variables. There are no YAML or TOML config files — just .dot env files and the ENV variable that tells the app which environment it’s running in.

How It Works

At startup, the framework loads environment variables in two passes:

  1. Common values from config/envs/env.dot — shared across all environments
  2. Environment-specific values from config/envs/env.{ENV}.dot — overrides for the current environment

The ENV environment variable (set to dev, prod, or test) determines which environment-specific file is loaded. This variable must be set before the app starts — it is not loaded from any file.

File Structure

config/
└── envs/
    ├── env.dot           # Common values (all environments)
    ├── env.dot.dist      # Template to copy for new setups
    ├── env.dev.dot       # Development overrides (optional)
    └── env.prod.dot      # Production overrides (optional)

The .dist file is committed to version control as a template. Copy it to env.dot and fill in your values. Never commit env.dot — it contains secrets.

The env.dot File

A typical env.dot for a new project:

# Application
APP_NAME=MyApp

# Security
JWT_SECRET_KEY=change-me-to-a-long-random-string
JWT_COOKIE_NAME=jwt_myapp
ADMIN_PASSWORD=change-me

# Database (SQLite for local dev)
DB_DRIVER=sqlite3
DB_NAME=myapp

Environment-Specific Overrides

Create env.dev.dot or env.prod.dot for values that differ per environment:

# config/envs/env.dev.dot
DEBUG_PORT=9235

# config/envs/env.prod.dot
DB_DRIVER=postgres
DB_HOST=db
DB_PORT=5432
DB_USER=myapp
DB_PASS=secret
DB_SSLMODE=require

Setting ENV

The ENV variable must be set externally — in your shell, Docker Compose, or CI environment.

Locally (native):

export ENV=dev
./bin/bird.sh

Via Docker Compose:

services:
  my-app:
    environment:
      - ENV=dev
      - ROOT_DIR=/app

Valid values: dev, prod, test.

Accessing Config in Code

The Config service is injected automatically by the container. Use it to read environment variables:

// Read any env variable
value := this.Config.GetEnvValue(ctx, "MY_VARIABLE")

// Panic if a required variable is missing
value := this.Config.MustGetEnvValue(ctx, "JWT_SECRET_KEY")

// Check the current environment
if this.Config.IsDevEnv() {
    // dev-only behaviour
}
if this.Config.IsProdEnv() {
    // prod-only behaviour
}

Next Steps

First Application
App