Quick Start
Welcome to Cloacina. This page is a navigation aid — it points you into the right tutorial or reference based on what you want to do. For substance (working code, exhaustive references, conceptual explanations) follow the links below into the dedicated tracks.
Cloacina is an embedded workflow orchestration framework for Rust
(with first-class Python bindings via Cloaca).
It runs inside your application rather than as a separate service,
manages multi-step pipelines with automatic retries and state
persistence, and ships packaged workflows as .cloacina cdylibs.
If you’d like the architectural pitch and the design rationale, read Architecture Overview.
Embedded mode. Start here:
→ Tutorial 01 — Your First Workflow
The full embedded-mode tutorial track is at Workflows → Tutorials. It covers your first workflow, context handling, complex dependency graphs, and error handling.
The full Python tutorial track is at
Python → Tutorials. Same shape
as the Rust track but Pythonic syntax and WorkflowBuilder context
managers.
Service mode. Start here:
→ Tutorial 01 — Deploy a Server
This walks through bootstrap-key handling, tenant provisioning, package upload, and your first execution. Once you have a server running, branch into:
- Migrating to Service Mode — convert an embedded-mode workflow into a packaged cdylib.
- Use cloacina-compiler Locally — build packages on your laptop without the long-running compiler service.
→ Computation Graphs Tutorials
The CG track has its own progression: a single-graph embedded-mode tutorial, accumulator patterns, full reactor pipelines, routing, and the cross-package binding pattern at Tutorial 10 — Cross-Package Reactor Binding.
→ Platform Tutorials + Platform How-To Guides
Highlights:
- Deploy a Server — first deployment, end to end.
- Configure a Multi-Tenant Deployment — multi-tenancy + the operational caveats you must know.
- Production Deployment — TLS, reverse proxy, observability hookup.
- Observe Execution State — Prometheus + OpenTelemetry + structured logs.
- Safely Unload a Package — clean teardown for cross-package deployments.
For lookup-style information rather than learning paths:
- CLI Reference — every
cloacinactlcommand, flag, env var, exit code, config-file schema. - HTTP API Reference — every endpoint, auth model, operational caveats.
package!()Macro Reference — the unified plugin shell.- FFI Vtable Reference — methods 0–8.
- Glossary — every term used in these docs, in one place.
- Troubleshooting — common problems and resolutions.
- GitHub issues — bug reports and feature requests.