Application Configuration & Environment Variables Guide

Foundry adheres to the philosophy of “Convention Over Configuration, Minimalist yet Highly Controllable”. Configuration is logically segmented into two tiers:

1. Static Infrastructure Configuration: Configured via system environment variables, .env files, and the fluent FoundryBuilder API to define network bindings, database connection strings, Redis, JWT secrets, and SMTP relays.
2. Runtime Dynamic Subsystem Configuration: Driven by ConfigSchema within the dynamic configuration center, allowing business administrators to view and adjust operational parameters in real time without restarting the server.

During local development, Foundry automatically loads the project root .env file via dotenvy. In containerized environments like Docker or Kubernetes, it prioritizes operating system environment variables.

Here is the complete reference table of supported environment variables:

Create a .env file in your application root:

# ==============================================================================
# FOUNDRY PLATFORM CONFIGURATION
# ==============================================================================

# 1. Server Listener
HOST=127.0.0.1
PORT=8080

# 2. Database Connection URL (Choose your target engine)
# PostgreSQL:
DATABASE_URL=postgres://postgres:postgrespassword@localhost:5432/foundry
# MySQL (8.0+):
# DATABASE_URL=mysql://root:root@localhost:3306/foundry
# MariaDB (10.5+):
# DATABASE_URL=mariadb://root:root@localhost:3307/foundry
# MongoDB (6.0+):
# DATABASE_URL=mongodb://127.0.0.1:27017/foundry

# 3. Auto-run migrations on startup
AUTO_MIGRATE=true

# 4. Optional Redis Cache
REDIS_URL=redis://127.0.0.1:6379

# 5. JWT Secret Key
JWT_SECRET=super_secret_jwt_key_for_my_production_app_2026

# 6. Optional SMTP Email Service
# SMTP_HOST=smtp.gmail.com
# SMTP_PORT=587
# SMTP_USER=notifications@my-domain.com
# SMTP_PASS=your_app_specific_password
# SMTP_FROM=Foundry Platform <notifications@my-domain.com>

# 7. Logging directives
RUST_LOG=info,my_app=debug,foundry=debug,foundry_engine=debug

In addition to environment variables, you can override settings programmatically using the fluent methods on FoundryApp::builder():

use foundry::prelude::*;
use std::path::PathBuf;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // 1. Load baseline config from environment variables
    let base_config = FoundryConfig::from_env();

    // 2. Assemble and override settings via fluent builder
    let app = FoundryApp::builder()
        .config(base_config)
        .host("0.0.0.0")
        .port(8080)
        .db_pool_size(50)
        .jwt_expiry_hours(72)
        .auto_migrate(true)
        .with_external_systems_dir(PathBuf::from("./external_systems"))
        .with_admin_spa_dir(PathBuf::from("./static/admin"))
        .register_subsystem(crate::systems::ShopSubsystem)
        .build()
        .await?;

    // 3. Start serving traffic
    app.run().await?;
    Ok(())
}

In enterprise applications, operational parameters often need to be modified in real time (e.g., registration toggles, daily raffle limits, customer support IDs, or unpaid order timeout thresholds). If these parameters are stored in static environment variables, changing them requires rebuilding containers or restarting instances.

Foundry provides the Dynamic Subsystem Configuration Center:

• Schema-Driven: Define configuration keys, labels, types (string, number, boolean, json), and validation rules.
• Hot-Reloading: Changes committed in the Admin Console are persisted immediately and read dynamically by business services with zero downtime.

POST /api/v1/admin/s/{system_slug}/configs/schema
Authorization: Bearer <ADMIN_JWT_TOKEN>
Content-Type: application/json

{
  "key": "order_auto_close_minutes",
  "label": "Unpaid Order Timeout (Minutes)",
  "field_type": "number",
  "default_value": "30",
  "description": "Orders left unpaid beyond this threshold are automatically cancelled.",
  "is_required": true
}

Access the latest configuration snapshot via Database::configs():

use foundry::prelude::*;

pub async fn check_order_timeout(ctx: &SystemContext, db: &Database) -> AppResult<i64> {
    // 1. Fetch aggregated key-value config map for current subsystem
    let configs = db.configs().get_aggregated(&ctx.system_slug).await?;

    // 2. Read specific key with a fallback default value
    let timeout_minutes: i64 = configs
        .get("order_auto_close_minutes")
        .and_then(|v| v.as_i64())
        .unwrap_or(30);

    info!(%timeout_minutes, "Active order timeout loaded");
    Ok(timeout_minutes)
}

GET /api/v1/s/{system_slug}/configs

PUT /api/v1/s/{system_slug}/configs
Authorization: Bearer <ADMIN_JWT_TOKEN>
Content-Type: application/json

{
  "configs": {
    "order_auto_close_minutes": 45,
    "enable_flash_sale": false
  }
}

1. [Critical] Rotate JWT Secret: Generate a cryptographically secure random string with at least 32 bytes:

   openssl rand -base64 48

2. [Critical] Tune Connection Pool Size (db_pool_size): Ensure instances * db_pool_size < database_max_connections.
3. [Recommended] Lower Driver Logging Verbosity: Suppress database and transport debug logs in production:

   RUST_LOG="warn,my_app=info,foundry=info,foundry_engine=info"

4. [Optional] Configure SMTP Relay: Enable 2FA login codes and email binding for administrative accounts.