This guide uses autumn-web and
HarvestPlugin. For a plain Axum service, read Chapter 2, then take the fork: The first workflow on plain Axum.
The fastest path: cargo dev
If you just want to see a durable workflow run, you do not need a database, a
compose.yaml, or Docker. From a clone of this repository, with only the Rust
toolchain installed:
cargo dev
That starts an ephemeral PostgreSQL, applies the engine's migrations, runs a
worker, and serves the management API and the Vantage dashboard. It prints the
dashboard URL and one curl that starts a sample workflow — an activity, a
durable timer, another activity — so you can watch a real execution progress in
the UI, step by step through its append-only history. Ctrl-C stops it and
removes everything it created: no leftover processes, no leftover data
directories.
Note the flip side of that last sentence: because the storage is thrown away on
exit, a cargo dev run cannot show you a workflow surviving a restart. To
watch that — the property the durable timer exists to demonstrate — point the
runtime at a database of your own, which it will never delete:
HARVEST_DEV_DATABASE_URL=postgres://me@localhost:5432/harvest_dev cargo dev
me is a placeholder, not a literal role — this DSN doesn't work copied
verbatim. This URI connects over TCP (not a Unix socket), so peer
authentication never applies here regardless of your pg_hba.conf; point it
at a role that's allowed to connect over TCP on this address (trust, or a
password in the DSN itself). Copied as-is against an ordinary
password-authenticated Postgres it fails immediately with Postgres's own
fe_sendauth: no password supplied, which names neither
HARVEST_DEV_DATABASE_URL nor this doc. For a fresh install using the default
postgres role: postgres://postgres:<password>@localhost:5432/harvest_dev.
Start the sample, kill the process while the timer is counting down, and start it again: the engine replays the first activity from history rather than re-running it.
The cluster it starts is real PostgreSQL running the engine's real schema and real migrations, so what you see is exactly what you would get in production. The dev runtime automates the database lifecycle, not the database.
A few things worth knowing:
-
It is development-only, and it enforces that. It refuses to start against anything it cannot show to be a local database: a non-loopback host, a DSN demanding TLS, or a known hosted-Postgres endpoint are all rejected outright. Its banner says it is not for production on every start.
-
It refuses to run as
root— when provisioning its own cluster. PostgreSQL will not run as root, by design, socargo dev's default, managed-cluster path checks for that up front and stops before creating anything. This is a real situation, not a hypothetical: Docker devcontainers, many CI base images, and some cloud sandboxes default to a root shell. The check is scoped to provisioning, so it does not apply once there is nothing to provision: pointcargo devat a database you already have withHARVEST_DEV_DATABASE_URL(below) and it runs fine as root. So does the bring-your-own-Postgres path below, andexamples/quickstart's owndocker compose+cargo run -p quickstartsteps — none of them askcargo devto provision anything. -
It does not need Postgres installed.
cargo devenables thedev-runtime-managedfeature, which downloads a platform-matched PostgreSQL build into a per-user cache the first time you run it (about 30 MB, once). If you already have Postgres installed, it uses that and never touches the network — and you can build the lighter tier explicitly:Shellcargo run -p autumn-harvest-plugin --features dev-runtime --bin harvest-dev -
Bring your own database if you would rather:
ShellHARVEST_DEV_DATABASE_URL=postgres://me@localhost:5432/harvest_dev cargo dev(
meis a placeholder for your own role — see the caveat above.) It still goes through the same safety gate, and it is left exactly as it is on exit — the dev runtime only ever deletes storage it created itself. -
On Windows the whole path is pure Rust (no libpq, no OpenSSL). Provisioning finds a standard EnterpriseDB install under
C:\Program Files\PostgreSQL\<version>\bin, and the managed tier downloads a Windows build.
harvest-dev --help lists the rest (--port, --session-root,
--allow-suspicious-database-name).
Everything from here on builds the same skeleton by hand, against a Postgres you provide, because that is what your own project will look like.
Bring your own Postgres
Shortcut:
harvest new <name>scaffolds this entire skeleton — aCargo.toml, a runnable#[workflow]/#[activity]pair withHarvestPluginwiring, acompose.yamlPostgres, anautumn.toml, and a README whose three-command path reaches one durable execution. It is pure local file generation (no database, no network) and names everything after<name>. The rest of this chapter builds the skeleton by hand so you can see each moving part; reach forharvest newonce you know what it emits.
Create a new Cargo project that depends on the engine, the Autumn plugin, and the web framework:
# Cargo.toml
[package]
name = "harvest-tutorial"
version = "0.1.0"
edition = "2021"
[dependencies]
autumn-harvest = "0.11"
autumn-harvest-plugin = "0.11"
autumn-web = "0.11"
serde = { version = "1", features = ["derive"] }
serde_json = "1"
tracing = "0.1"
Add the boilerplate main.rs — at this point we register zero workflows and
zero activities, just to confirm the plugin mounts cleanly:
// src/main.rs
use autumn_harvest::prelude::*;
use autumn_harvest_plugin::HarvestPlugin;
#[autumn_web::main]
async fn main() {
autumn_web::app()
.plugin(
HarvestPlugin::new()
.worker(WorkerConfig::default())
.api("/api/harvest"),
)
.run()
.await;
}
Drop in a Postgres compose.yaml next to your Cargo.toml (the
quickstart's compose file is a good
starting point) and an autumn.toml that points the framework at it:
# autumn.toml
[database]
url = "postgres://postgres:postgres@localhost:5432/autumn_harvest"
Bring it up:
docker compose up -d
AUTUMN_PROFILE=dev cargo run
HarvestPlugin registers its migrations with Autumn, which applies them
before any startup hook runs. Under AUTUMN_PROFILE=dev pending migrations are
applied automatically, so you don't need diesel-cli for the dev loop. (Outside
dev, pending migrations are only reported — run autumn migrate in your
deploy pipeline first. See Chapter 10.) The app will start
on http://localhost:3000. Hit the health endpoint to confirm the plugin
mounted:
curl -s http://localhost:3000/api/harvest/health | jq .