Configuration

Relevant source files

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

• src/config.rs
• src/cli.rs
• docs-site/config.toml
• snipdoc.yml
• loco-new/tests/templates/asset.rs
• DEVELOPMENT.md

Loco utilizes an environment-aware configuration system that allows developers to define application behavior across different stages such as development, testing, and production. The system is designed around the principle of "Convention Over Configuration," providing sensible defaults for local development while requiring explicit settings for production environments. Configuration is typically managed through YAML files located in a central config/ directory.

The configuration architecture is strongly typed and extensible, allowing for core framework settings (database, server, workers) and custom application-specific settings. It integrates deeply with the Loco CLI, enabling features like automatic database migrations and environment-specific middleware stacks.

Sources: src/config.rs:25-30, README.md:34-36, src/cli.rs:480-485

Core Configuration Architecture

The central data structure for application settings is the Config struct. It aggregates several sub-modules responsible for different parts of the system.

Configuration Loading Flow

Loco loads configuration based on the active environment (e.g., development, test, production). It looks for files in the config/ folder following a specific precedence order:

1. {environment}.local.yaml (Overrides)
2. {environment}.yaml (Base environment config)

The configuration files support dynamic values via Tera templating, allowing environment variables to be injected at runtime using the get_env helper.

Sources: src/config.rs:56-78, src/config.rs:645-675

Configuration Components

The following table summarizes the primary configuration blocks available in the Config structure.

Block	Description	Key Fields
logger	Configures the tracing-based logging stack.	enable, level, format, pretty_backtrace
server	Defines web server behavior and binding.	binding, port, host, middlewares
database	Manages SeaORM connection pool and migrations.	uri, auto_migrate, max_connections
queue	Configures background job queue providers.	kind (Redis, Postgres, Sqlite), uri
auth	Manages authentication providers (e.g., JWT).	jwt.secret, jwt.expiration
workers	Sets the execution mode for background tasks.	mode (BackgroundQueue, ForegroundBlocking, etc.)
scheduler	Defines recurring job configurations.	jobs, run, schedule

Sources: src/config.rs:59-78, docs-site/config.toml:191-205

Detailed Section: Server and Middleware

The server block defines how the application interacts with the network and which middlewares are active. Middlewares can be toggled per environment, which is common for features like payload compression or request logging.

Static Assets Configuration

Loco supports different strategies for serving assets, which are reflected in the configuration:

• Serverside: Serves assets from a local folder (e.g., assets/static).
• Clientside: Optimized for SPA frameworks, often pointing to a frontend/dist directory with a fallback to index.html.

Detailed Section: Database Management

The database configuration block manages the lifecycle of the DB connection and schema.

Connection and Pool Settings

Loco provides granular control over the connection pool:

• connect_timeout: Duration to wait for a connection.
• auto_migrate: If true, runs pending migrations on startup.
• dangerously_truncate: Clears tables on startup (primarily used in test.yaml).

// Example database configuration
database:
  uri: {{ get_env(name="DATABASE_URL", default="sqlite://db.sqlite?mode=rwc") }}
  enable_logging: true
  min_connections: 1
  max_connections: 5
  auto_migrate: true
  dangerously_truncate: false

Sources: src/config.rs:163-186, src/config.rs:218-225

CLI Interaction with Configuration

The Loco CLI provides commands to validate and inspect the active configuration. This is crucial for debugging environment-specific issues.

Command	Purpose
cargo loco doctor	Validates configuration and connectivity (DB, Redis).
cargo loco doctor --config	Prints the full resolved configuration object to stdout.
cargo loco middleware --config	Displays the active middleware stack and its settings.

Sources: src/cli.rs:94-105, src/cli.rs:495-505, snipdoc.yml:104-110

Conclusion

The Loco configuration system provides a robust framework for managing application settings through environment-specific YAML files. By leveraging Tera templates for environment variable injection and a strongly-typed Rust structure for internal access, it ensures that configuration is both flexible for DevOps and safe for developers. The deep integration with the CLI and middleware stack allows the framework to adapt its behavior seamlessly from a local development environment to a high-scale production deployment.

Sources: src/config.rs:25-35, src/cli.rs:480-490