Configuration

Gen-X has two configuration layers that operate independently. The first controls the generator itself — where output goes, which environment loads, and how Gen-X connects to its internal project graph. The second controls the generated application once it is running — its database, JWT secrets, and port assignments. This page covers both.

Two Configuration Layers

📝 Note: Changing a value in Gen-X’s env.dot has no effect on the generated application’s runtime behaviour — and vice versa. The two layers share the same file naming convention but are loaded by completely separate processes.

Layer 1: The Generator

The ENV Variable

The ENV variable is the single most important configuration setting for Gen-X. It must be set before any go run main.go command.

ENV=dev go run main.go depict seed-vault

Valid values are dev, prod, and test. During initial setup and day-to-day development, always use dev. The variable is not read from any file — it must be present in the shell environment at the time the command runs.

💡 Tip: Add a shell alias so you never forget the ENV prefix: alias depict='ENV=dev go run main.go depict'. Then you can run depict seed-vault directly.

Configuration Files

Gen-X reads its configuration from .dot files loaded in two passes at startup: common values first, then environment-specific overrides.

config/
└── envs/
    ├── env.dot           # Common values (all environments)
    ├── env.dot.dist      # Template — copy this to env.dot to get started
    ├── env.dev.dot       # Development overrides (optional)
    └── env.prod.dot      # Production overrides (optional)

Bootstrap a new setup by copying the distributed template:

cp config/env.dot.dist config/env.dot

⚠️ Warning: Never commit config/env.dot to version control — it contains your local secrets and database credentials. Only env.dot.dist is committed. Add config/env.dot to .gitignore if it is not already listed.

Environment-Specific Overrides

Create env.dev.dot or env.prod.dot for values that differ between environments. Override files are applied on top of env.dot after the common pass.

# config/envs/env.dev.dot
DEBUG_PORT=9235
GEN_X_DB_DRIVER=sqlite3
GEN_X_DB_NAME=gen_x_dev

# config/envs/env.prod.dot
GEN_X_DB_DRIVER=postgres
GEN_X_DB_HOST=db
GEN_X_DB_PORT=5432
GEN_X_DB_USER=gen_x
GEN_X_DB_PASS=secret
GEN_X_DB_SSLMODE=require

Layer 2: The Generated Application

Every app Gen-X produces uses the same X-Go .dot file configuration system. On the first generator run, a config/env.dot.dist template is seeded in the output directory. Copy it to config/env.dot and fill in your values before starting the app.

For a full reference of how configuration works inside the generated app — including all standard variables and the full two-pass loading sequence — see the X-Go framework documentation: Configuration.

Accessing Config in Code

Within any Maestro or service in the generated app, configuration values are available via the injected Config service.

// 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() {
    // development-only behaviour
}

MustGetEnvValue is the recommended form for variables your application cannot start without. It fails loudly at boot time rather than silently returning an empty string at runtime.

Setting ENV

The ENV variable must be set externally — in your shell, Docker Compose, or CI environment. It is never read from a .dot file.

Native Shell

export ENV=dev && ./bin/bird.sh

Docker Compose

services:
  seed-vault:
    environment:
      - ENV=dev
      - ROOT_DIR=/app

CI

ENV=test go test ./tests/...

Next Steps

• Daily Workflow — The recommended daily development loop with Gen-X
• Developer Setup — Full environment setup reference including TDD configuration
• Architecture Overview — How the generation pipeline works from depiction script to compiled output