michel/clusterflux-public
1
0
Fork 0
Code Issues Pull requests Projects Releases 21 Packages Wiki Activity Actions

Publish Clusterflux 45bbc21

Browse source
This commit is contained in:
Michel Paulissen 2026-07-20 11:08:26 +02:00
parent eb1077f380
commit 3f88254c70
28 changed files with 896 additions and 167 deletions
Download patch file Download diff file Expand all files Collapse all files

26
docs/releases.md → docs/contributing/releases.md
View file

@ -1,5 +1,29 @@
# Release candidates
This is a contributor and release-engineering procedure, not an end-user setup
path. Publication is a three-stage transaction:
1. `candidate` builds immutable archives and a manifest with paths relative to
the manifest directory.
2. `live-test` downloads that exact candidate in a clean job, deploys it, and
records the full 25-check production-shaped acceptance result plus deployment,
runtime configuration, and proxy configuration identities.
3. `final` downloads the candidate and evidence in another clean job, verifies
every binding, and publishes without rebuilding any binary.
Set `CLUSTERFLUX_RELEASE_STAGE=candidate` while creating the candidate and
`CLUSTERFLUX_RELEASE_STAGE=final` while finalizing it. The final stage requires
`CLUSTERFLUX_RELEASE_CANDIDATE_MANIFEST` and complete live evidence. There is no
incomplete-evidence publication override.
The `clusterflux-release` runner must provide `CLUSTERFLUX_DEPLOY_COMMAND` as a
protected secret. The command runs locally with
`CLUSTERFLUX_CANDIDATE_ARCHIVE`, `CLUSTERFLUX_CANDIDATE_COORDINATOR`, and their
SHA-256 identities exported. It must deploy that executable and restart the
configured service. `scripts/deploy-release-candidate.sh` then independently
compares the running `/proc/<MainPID>/exe` digest with the candidate and records
the service and proxy unit identities; a mismatch stops the release.
Clusterflux release binaries are built once. The public client/node archive and
the private-source hosted-service archive are both digest-bound to the same
candidate. The hosted archive is deployed, the strict production-shaped batch
@ -10,7 +34,7 @@ Create the candidate in a dedicated directory:
~~~bash
CLUSTERFLUX_PUBLIC_RELEASE_DIR=target/release-candidate \
CLUSTERFLUX_ALLOW_INCOMPLETE_RELEASE_EVIDENCE=1 \
CLUSTERFLUX_RELEASE_STAGE=candidate \
./scripts/prepare-public-release.js
~~~

6
docs/debugging.md
View file

@ -1,5 +1,11 @@
# Debugging
The DAP runtime observer keeps one coordinator session open and reconnects it
with a 100 ms to 5 second exponential backoff. Polling is responsive around
debug actions (100 ms) and backs off to one observation cycle every 5 seconds
while idle. A cycle makes at most four coordinator requests, so steady-state
idle traffic is bounded at 0.8 requests per second per debug session.
The VS Code extension uses the Debug Adapter Protocol and the coordinator's
authoritative process, task, attempt, and Debug Epoch APIs.

4
docs/environments.md
View file

@ -1,5 +1,9 @@
# Environments
Clusterflux disables network access while a task executes. Materializing an
environment for the first time can still fetch declared inputs; subsequent task
execution uses the materialized environment with networking disabled.
Declare environments in the bundle under:
~~~text

2
docs/getting-started.md
View file

@ -93,7 +93,7 @@ chmod +x ./hello-clusterflux
~~~
The workflow snapshots `examples/hello-build`, starts its `compile` task in the
offline Linux environment, and retains the real static executable returned by
network-disabled Linux execution environment, and retains the real static executable returned by
that task.
Choose another entrypoint by replacing `build`. Clusterflux rejects an oversized