ch-rds

ch-rds resolves runtime resources and starts conventional local services when an application uses loopback endpoints.

More information is available in the API documentation.

High-level features

• Typed loaders for web listeners, MariaDB, and SpacetimeDB
• Explicit production behavior with no local fallback
• Conventional .env, .env.local, and services.env discovery
• Health-gated, protocol-verified Docker Compose startup for loopback resources
• Optional frontend/backend development process orchestration

Usage

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let runtime = ch_rds::Runtime::bootstrap()?;
    let bind_addr = runtime
        .load(ch_rds::WebBind::builder().addr("127.0.0.1:8080"))
        .await?;

    println!("{bind_addr}");
    Ok(())
}

Runtime resolves configured remote endpoints directly. Production mode rejects local fallbacks. ENV_FILE selects one explicit dotenv file, while PORT overrides only the port of the fallback listener address.

Conventional layouts auto-discover MariaDB and SpacetimeDB; builders cover custom stacks. Protocol-level readiness is checked only after Docker reports the service healthy. One locked service restart remains available for a previously healthy but persistently broken endpoint; containers are not restarted while their first initialization is still in progress. SpacetimeDB updates publish in place to preserve data and identity.

Local stacks use the active Docker context on Windows, macOS, and Linux. When Docker Desktop is installed on Windows or macOS, ch-rds can start it through the official Docker Desktop CLI. Linux daemon lifecycle remains under the host service manager.

Development runner

The dev feature provides ProjectProfile and run_project. Vite owns frontend hot-module replacement; Watchexec restarts the backend when Rust sources, manifests, lockfiles, Cargo configuration, or SQL migrations change.

Use watch --no-backend-reload when working on a separately tested, compile-heavy Rust dependency. The runner starts the same backend command once and keeps Vite hot-module replacement active, but does not rebuild the backend again until the runner is restarted.

Projects with cold backend builds longer than the five-minute default can set ProjectProfile::with_backend_ready_timeout without adding another CLI mode.

Profiles can register expensive browser assets with ProjectProfile::with_optional_public_asset. They are skipped by default and can be enabled explicitly for a run with --with-optional-assets (the --editor alias is available for editor-oriented projects).

cargo install watchexec-cli --version 2.5.1 --locked

Feature flags

Minimum supported Rust version

ch-rds requires Rust 1.97 or newer.

License

Licensed under the Sustainable Use License 1.0. See LICENSE.md.