e4e73e245a
Source commit: 5ee549dd5fddc98e4ee5054679bb0ac405c82529 Public tree identity: sha256:61b170dbdd26d350b8aff072e1792d38afd76bac7881bd42f271864d9662a6d4
111 lines
3.6 KiB
Markdown
111 lines
3.6 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 select your hosted project
|
|
|
|
~~~bash
|
|
clusterflux login --browser
|
|
clusterflux auth status
|
|
clusterflux project list
|
|
clusterflux project select <hosted-project-id>
|
|
~~~
|
|
|
|
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. Hosted login creates or links the account's single project;
|
|
additional project creation is rejected by hosted admission policy.
|
|
|
|
## 3. Enroll and start a node
|
|
|
|
Create a short-lived grant:
|
|
|
|
~~~bash
|
|
clusterflux node enroll --project-id <hosted-project-id> --json
|
|
~~~
|
|
|
|
Generate a node key pair using your normal secret-management tooling. Exchange
|
|
the grant once:
|
|
|
|
~~~bash
|
|
clusterflux node attach --project-id <hosted-project-id> --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 <hosted-project-id> --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.
|