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 rebuilds changed Rust sources, manifests, lockfiles, Cargo configuration, and SQL migrations before the runner activates the new backend executable.

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. Projects that bind their socket before startup is complete should also set ProjectProfile::with_backend_ready_path. The runner then waits for a real HTTP response instead of treating the bound TCP socket as ready.

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

Local BTCPay webhooks

Loopback payment URLs use payment-host.internal inside BTCPay. The generated BTCPay service maps this name through Docker's host-gateway, avoiding the upstream entrypoint's override of host.docker.internal with the container bridge gateway. This works with Docker Desktop and Docker Engine without a hard-coded host address. Public payment hosts are preserved.

For an existing local store, update its webhook URL to the new host while preserving the webhook secret, enabled state and event selection. Then use BTCPay's redelivery action for an existing event; never manufacture a settlement notification or mark an invoice paid in the application database. Regeneration keeps the host mapping idempotent. No production webhook URL is changed.

Feature flags

Minimum supported Rust version

ch-rds requires Rust 1.99 or newer.

License

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