6f52bb46cd
Source commit: a43e907efd9d1561c23fe73499478e881f868355 Public tree identity: sha256:453dea30195485dd8939f575a69b39f4bb7acd84c4df23f8aa29b55d044f2673
110 lines
3.5 KiB
Markdown
110 lines
3.5 KiB
Markdown
# Getting started
|
|
|
|
This guide uses the hosted coordinator. For your own coordinator, complete
|
|
[Self-hosting](self-hosting.md) first and then return to the node and run steps.
|
|
|
|
## 1. Install the commands
|
|
|
|
~~~bash
|
|
cargo install --path crates/clusterflux-cli --bin clusterflux
|
|
cargo install --path crates/clusterflux-node --bin clusterflux-node
|
|
cargo install --path crates/clusterflux-dap --bin clusterflux-debug-dap
|
|
~~~
|
|
|
|
Install rootless Podman on each Linux node that will execute container-backed
|
|
environments.
|
|
|
|
## 2. Sign in and create a project
|
|
|
|
~~~bash
|
|
clusterflux login --browser
|
|
clusterflux auth status
|
|
clusterflux project init --new-project my-project --name "My Project" --yes
|
|
clusterflux project select my-project
|
|
~~~
|
|
|
|
The browser flow is owned by the configured Authentik identity provider. The CLI
|
|
stores an opaque Clusterflux session, not provider authorization codes or
|
|
provider tokens.
|
|
|
|
## 3. Enroll and start a node
|
|
|
|
Create a short-lived grant:
|
|
|
|
~~~bash
|
|
clusterflux node enroll --project-id my-project --json
|
|
~~~
|
|
|
|
Generate a node key pair using your normal secret-management tooling. Exchange
|
|
the grant once:
|
|
|
|
~~~bash
|
|
clusterflux node attach --project-id my-project --node workstation --enrollment-grant "$ENROLLMENT_GRANT" --public-key "$NODE_PUBLIC_KEY" --json
|
|
~~~
|
|
|
|
Start the worker from the project directory with its private key supplied
|
|
through protected environment or credential storage:
|
|
|
|
~~~bash
|
|
CLUSTERFLUX_NODE_PRIVATE_KEY="$NODE_PRIVATE_KEY" clusterflux-node --coordinator https://clusterflux.michelpaulissen.com --tenant "$TENANT" --project-id my-project --node workstation --public-key "$NODE_PUBLIC_KEY" --project-root "$PWD" --worker --emit-ready
|
|
~~~
|
|
|
|
The enrollment grant is not needed again. Stop and restart the worker with the
|
|
same key identity. Check server-derived liveness with:
|
|
|
|
~~~bash
|
|
clusterflux node list
|
|
clusterflux node status workstation
|
|
~~~
|
|
|
|
## 4. Inspect and run a bundle
|
|
|
|
A project contains "clusterflux.toml", Rust workflow source, and any declared
|
|
environments under "envs/".
|
|
|
|
~~~bash
|
|
clusterflux bundle inspect --project .
|
|
clusterflux run --project . build
|
|
~~~
|
|
|
|
Choose another entrypoint by replacing "build". Clusterflux rejects an
|
|
oversized or invalid bundle before it creates the virtual process.
|
|
|
|
## 5. Inspect tasks and output
|
|
|
|
~~~bash
|
|
clusterflux process list
|
|
clusterflux process status
|
|
clusterflux task list
|
|
clusterflux logs
|
|
clusterflux artifact list
|
|
~~~
|
|
|
|
A failed task configured with "AwaitOperator" remains visible as awaiting
|
|
action. Restart it as a new attempt under the same logical task identity:
|
|
|
|
~~~bash
|
|
clusterflux task restart <task-id> --process <process-id> --yes
|
|
~~~
|
|
|
|
## 6. Debug in VS Code
|
|
|
|
Open the project in VS Code and start "Clusterflux: Launch Virtual Process".
|
|
Set a breakpoint on a generated probe location and use the normal Threads,
|
|
Stack, Variables, Continue, Pause, and Restart controls.
|
|
|
|
A fully frozen Debug Epoch gives a consistent all-participant view. If a
|
|
participant cannot freeze within five seconds, the adapter reports a partial
|
|
epoch. You may inspect frozen participants, but values across running and frozen
|
|
tasks are not a consistent global snapshot.
|
|
|
|
## 7. Download an artifact
|
|
|
|
~~~bash
|
|
clusterflux artifact list --process <process-id>
|
|
clusterflux artifact download <artifact-id> --to ./output.bin --max-bytes 67108864
|
|
~~~
|
|
|
|
The command opens a scoped, expiring download and verifies the artifact digest.
|
|
It fails if the retaining node is stale, the bytes were garbage collected, the
|
|
digest or size changed, or policy cannot reserve the transfer.
|