Skip to content

GreenPipe Website Contract

This contract lets greenpipe.partners publish Flux installs and Flux MkDocs documentation without becoming a remote shell or Flux runtime host.

Deployment Interface

Public release manifest:

GET https://greenpipe.partners/release/flux/0.1.1/manifest.example.json

The versioned release manifest is the public no-account deployment handoff. Managed deployment pages should show typed deploy commands, not arbitrary shell generated per request, and must not show placeholder deployment IDs or tokens in the primary CTA.

First, the page must provide the deploy runner:

GET https://greenpipe.partners/release/flux/0.1.1/flux-deploy.py
GET https://greenpipe.partners/release/flux/0.1.1/flux-deploy.py.sha256
GET https://greenpipe.partners/release/flux/0.1.1/flux-deploy.py.sig

Then a managed install command can be generated from a real deployment record:

sudo python3 flux-deploy.py apply \
  --manifest-url https://greenpipe.partners/api/flux/deployments/dep_123/manifest \
  --claim-token <one-time-token> \
  --json

Required release files:

GET https://greenpipe.partners/release/flux/0.1.1/flux-0.1.1.tar.zst
GET https://greenpipe.partners/release/flux/0.1.1/flux-0.1.1.tar.zst.sha256
GET https://greenpipe.partners/release/flux/0.1.1/flux-0.1.1.tar.zst.sig

Canonical path is /release/.... If /realease/... appears, redirect it to /release/....

Manifest shape. The deploy runner consumes JSON; YAML may be shown as documentation only.

{
  "apiVersion": "flux.greenpipe.partners/v1",
  "kind": "FluxInstall",
  "metadata": {"deployment_id": "dep_123"},
  "spec": {
    "release": {
      "version": "0.1.1",
      "artifact_url": "https://greenpipe.partners/release/flux/0.1.1/flux-0.1.1.tar.zst",
      "sha256": "<hex-digest>",
      "checksum_url": "https://greenpipe.partners/release/flux/0.1.1/flux-0.1.1.tar.zst.sha256",
      "signature_url": "https://greenpipe.partners/release/flux/0.1.1/flux-0.1.1.tar.zst.sig"
    },
    "target": {"allowed_hosts": "localhost,127.0.0.1", "web_bind": "0.0.0.0:8000"},
    "database": {"mode": "local"},
    "services": {"enable": true, "start": true}
  }
}

The target host downloads, verifies, unpacks, and runs:

sudo python3 install/flux_installer.py --start

Deployment API

Minimum website API for managed installs:

POST /api/flux/deployments
GET  /api/flux/deployments/{id}/manifest
POST /api/flux/deployments/{id}/events
POST /api/flux/deployments/{id}/complete

Event payload:

{
  "deployment_id": "dep_123",
  "stage": "systemd",
  "state": "running",
  "message": "Rendering Flux systemd units",
  "timestamp": "2026-06-21T12:00:00Z"
}

GitHub Artifact Handoff

Flux publishes unsigned handoff artifacts through .github/workflows/greenpipe-handoff.yml.

Workflow name: Build GreenPipe handoff
Artifact name: greenpipe-handoff
Default version: 0.1.1

The website signing workflow should use this Flux workflow run ID as source_run_id, download artifact greenpipe-handoff, verify .sha256 files, sign each checksummed release file, and publish the signed bundle.

MkDocs Interface

Flux docs are static MkDocs output. The website should mount the built site, not rewrite the docs at request time.

Source inputs:

mkdocs.yml
docs/

Build command:

uv run mkdocs build --strict

Build output:

.runtime/site/

Recommended published docs routes:

GET https://greenpipe.partners/docs/flux/0.1.1/
GET https://greenpipe.partners/docs/flux/latest/ -> redirect to /docs/flux/0.1.1/

Optional docs artifact files:

GET https://greenpipe.partners/release/flux/0.1.1/flux-docs-0.1.1.tar.zst
GET https://greenpipe.partners/release/flux/0.1.1/flux-docs-0.1.1.tar.zst.sha256
GET https://greenpipe.partners/release/flux/0.1.1/flux-docs-0.1.1.tar.zst.sig

For production docs builds, set MkDocs site_url to the mounted docs URL before build:

https://greenpipe.partners/docs/flux/0.1.1/

Security Rules

  • Website publishes typed install intent, immutable artifacts, checksums, signatures, docs, and status views.
  • Website must not SSH into targets or execute arbitrary root shell strings.
  • Target hosts execute the installer locally and report events back.
  • Secrets must be claim-scoped or resolved by the target runner; do not expose database URLs in public release metadata.