Deployment
Audience and Use
This page is for teams deploying Locus in development, staging, and production environments.
Use it to:
- Select an operating model by environment.
- Apply release checks before rollout.
- Keep runtime behavior consistent across deployment targets.
For prerequisite tooling and baseline readiness checks, see Environment Setup.
Supported Runtime Modes
- Embedded/local development mode.
- Remote SurrealDB mode.
- Hybrid host mode where gateway and MCP share the same underlying Locus behavior.
Environment Matrix
| Environment | Storage Mode | Host Profile | Primary Goal |
|---|---|---|---|
| Local Development | In-memory or embedded Surreal | single-process | fast iteration and debugging |
| CI Validation | In-memory plus deterministic fixtures | test-only jobs | regression detection and compatibility checks |
| Staging | Remote SurrealDB with isolated tenant space | gateway plus mcp parity checks | release verification and migration rehearsal |
| Production | Remote SurrealDB with restricted access | managed gateway and mcp deployments | reliability, auditability, and scale |
Build Prerequisites
- Rust toolchain (stable).
- cargo available in PATH.
- Optional: SurrealDB endpoint for integration environments.
Platform and Runtime Support
| Area | Baseline |
|---|---|
| Rust | Stable toolchain |
| Host OS | Linux, macOS, Windows (WSL2 recommended) |
| Container runtime | Docker Engine or compatible runtime |
| Storage | In-memory, SurrealDB v3 |
| Docs build | mdbook, mdbook-mermaid |
Build Commands
From repository root:
cargo check --workspace --examples
cargo test -p locus-core-rs --lib
cargo test -p locus-sdk
Packaging
Core package helper:
./locus-core-rs/build-package.sh
Publish preflight helper:
./locus-core-rs/publish-crates.sh
Configuration Guidance
- Keep environment-specific endpoint credentials out of repository files.
- Set explicit session/tenant scoping in host integrations.
- Prefer pinned model/provider settings for repeatable production behavior.
- Separate development and production provider endpoints.
- Use explicit tenant/session scoping in host runtime configs.
These controls reduce configuration drift and support predictable operations during upgrades.
Host Deployment Profiles
-
MCP host profile: MCP prioritizes tool contract stability and strict parser and validator checks in smoke tests.
-
Gateway host profile: Gateway prioritizes stable HTTP and gRPC mapping to SDK primitives with health checks and retrieval policy observability.
Release Readiness Checklist
- Workspace compile and tests pass.
- Example binaries compile and execute in CI smoke path.
- Integration hosts confirm SDK contract compatibility.
- Changelog and migration notes updated.
- Versioning and compatibility policy reviewed for this release.
- Security checklist validated for secrets and logging hygiene.
Releases that do not meet this checklist should not be promoted to production.
Release Gates by Environment
Local Development Gate
- Workspace compile succeeds.
- Targeted crate tests pass for changed modules.
- At least one example path executes without contract errors.
CI Validation Gate
- Workspace test matrix passes.
- Lint and docs build complete in CI.
- No parser or validator regressions in changed paths.
Staging Gate
- Gateway and MCP parity checks pass against the same dataset.
- Retrieval path distribution stays within expected baseline variance.
- Rollback procedure is rehearsed and time-bounded.
Production Promotion Gate
- Staging sign-off is recorded.
- Observability alerts and dashboards are active.
- Release note includes compatibility and rollback instructions.