Environment Configuration

Relevant source files

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

• sea-orm-pro/src/config.rs
• sea-orm-pro/src/parser.rs
• src/controllers/admin.rs
• README.md
• pro_admin/config.toml
• pro_admin/dashboard.toml
• examples/axum_example/api/src/lib.rs

Environment Configuration in SeaORM Pro facilitates the customization and behavior of the admin panel across different stages of deployment. The system primarily utilizes .env files for infrastructure-level settings (such as database connections) and a structured set of .toml configuration files located in the pro_admin directory to define the UI, dashboard charts, and table behaviors.

The configuration architecture is designed to handle different runtime environments. In production, configurations are typically cached for performance, whereas in development/debug modes, the system reloads configuration files from the disk on every request to allow for rapid iteration.

Sources: src/controllers/admin.rs:18-28, README.md:10-18, sea-orm-pro/src/parser.rs:17-48

Core Configuration Components

The system aggregates multiple configuration sources into a single JsonCfg structure. This structure serves as the comprehensive schema for the admin panel's frontend.

Configuration Structure Diagram

The following diagram illustrates how different configuration modules are aggregated into the central configuration object.

Key Configuration Files

The configuration is split across several files within the pro_admin root folder:

File	Purpose	Relevant File Path
config.toml	Defines the site theme (logo, title), navbar options, and main menu titles.	pro_admin/config.toml
dashboard.toml	Configures the info cards and data visualization charts shown on the main dashboard.	pro_admin/dashboard.toml
raw_tables/*.toml	Individual configuration for standard database tables, including visibility and editor permissions.	sea-orm-pro/src/parser.rs:30-38
composite_tables/*.toml	Definitions for complex views involving parent-child relationships between tables.	sea-orm-pro/src/parser.rs:40-48

Infrastructure and Database Settings

Infrastructure-level configuration is managed via environment variables, typically stored in a .env file at the project root. The primary variable is DATABASE_URL, which determines the database dialect and connection string.

Database Connection Configuration

SeaORM Pro supports multiple backends. The backend must be enabled both in the environment variable and as a feature in Cargo.toml.

# Example .env configuration
DATABASE_URL="sqlite://db.sqlite?mode=rwc"

Sources: README.md:10-18, examples/axum_example/api/src/lib.rs:43-45

Compilation Features

To target specific databases, the corresponding sqlx feature must be enabled:

• sqlx-mysql
• sqlx-postgres
• sqlx-sqlite (Default)

Sources: README.md:22-27, Cargo.toml:43-47

Data Loading Logic

The ConfigParser is responsible for traversing the configuration directory and deserializing TOML files into Rust structures.

Loading Sequence

1. Site Config: Loads config.toml or falls back to a hardcoded default.
2. Dashboard: Loads dashboard.toml.
3. Raw Tables: Iterates through the raw_tables directory and maps filenames to RawTableCfg.
4. Composite Tables: Iterates through the composite_tables directory and maps filenames to CompositeTableCfg.

Environment-Specific Handling

The system differentiates between Production and other environments (Development/Debug) when serving configuration through the API.

Config Controller Logic

The /admin/config endpoint behavior changes based on the environment:

• Production: Uses a lazy_static cached version of the configuration loaded once at startup.
• Debug/Development: Re-parses the configuration files from the disk on every request, allowing developers to see changes without restarting the server.

// src/controllers/admin.rs:18-28
pub async fn config(State(ctx): State<AppContext>) -> Result<Response> {
    if ctx.environment == Environment::Production {
        // Release: load config from the disk once and then return the cached config afterwards
        format::json(&*CONFIG)
    } else {
        // Debug: load config from disk on every request
        let config = ConfigParser::new()
            .load_config(CONFIG_ROOT)
            .map_err(Into::<Box<dyn std::error::Error + Send + Sync>>::into)?;
        format::json(config)
    }
}

Sources: src/controllers/admin.rs:18-28, examples/axum_example/api/src/lib.rs:207-211

Dashboard and UI Configuration

The DashboardCfg structure defines the layout of the admin home page. It supports a grid system using "rows" and "columns" with specific "spans" (up to 24 units).

Chart Configuration Options

Charts are defined within columns and require specific keys to fetch data from the backend.

Option	Type	Description
chart	String	Unique key for the data fetching endpoint.
kind	String	Type of chart (e.g., "line", "pie").
timescale	String	Time unit for the X-axis (e.g., "day", "month").
span	u32	Width in the grid (e.g., 12 for half-width, 24 for full).

Sources: sea-orm-pro/src/config.rs:104-118, pro_admin/dashboard.toml:35-86

Summary

Environment Configuration in SeaORM Pro provides a robust mechanism for decoupling UI layout and database connectivity from the core application logic. By utilizing .env for infrastructure and TOML for UI definitions, the system allows for flexible deployments while maintaining developer productivity through environment-aware configuration reloading.