PSA/ee/docs/extension-system/enterprise-build-workflow.md

Enterprise Build Workflow: pack → sign → publish

This guide outlines the enterprise pipeline to build, package, sign, and publish extension bundles to S3-compatible storage (e.g., MinIO), and references related docs and APIs. Use the alga Client SDK CLI for packing, signing, and publishing.

References

• Development Guide: ee/docs/extension-system/development_guide.md
• Runner S3 Integration: ee/docs/extension-system/runner-s3-integration.md
• Upload Proxy API (streaming, 200 MiB cap): ee/server/src/app/api/ext-bundles/upload-proxy/route.ts
• Finalize API: ee/server/src/app/api/ext-bundles/finalize/route.ts

Objectives and Pipeline

The enterprise pipeline is responsible for taking a compiled extension, producing an integrity-verifiable bundle, optionally signing it, and publishing it to the canonical, immutable S3 location based on its content hash.

Stages:

1. Build: Produce compiled assets (e.g., entry.wasm, UI assets, manifest.json) in a dist directory.
2. Pack: Create bundle.tar.zst from the dist directory and compute sha256.
3. Sign (optional): Produce a SIGNATURE file tied to the bundle with the chosen algorithm.
4. Publish: Stream the bundle via upload‑proxy, then finalize with manifest/signature.

Output:

• S3 canonical objects are written to:
  • sha256//bundle.tar.zst
  • sha256//manifest.json

Example Commands

Install the CLI (local dev):

• In the monorepo: npm run build:sdk && npm -w sdk/alga-client-sdk link
• Then run: alga --help

Assumptions:

• Your extension build outputs to ./my-extension/dist and includes manifest.json at that path.

• You have Node 18+ available.

• Pack alga pack ./my-extension/dist ./out/bundle.tar.zst

• Sign (optional; placeholder) alga sign ./out/bundle.tar.zst --algorithm cosign

• Publish alga publish --bundle ./out/bundle.tar.zst --manifest ./my-extension/dist/manifest.json --declared-hash

Notes:

• The pack step writes a sidecar SHA file (bundle.sha256 or .sha256). You can use this value as the --declared-hash in publish to enforce integrity at the server.
• The sign step currently writes a placeholder SIGNATURE file next to the bundle. If provided to publish (via --signature and --signature-algorithm), it will be forwarded to finalize. Replace with real signing logic in your environment.

Environment Requirements and Local MinIO

Server/Storage configuration (server process):

• STORAGE_S3_ENDPOINT: e.g., http://localhost:9000 (MinIO)
• STORAGE_S3_BUCKET: e.g., alga-bundles
• STORAGE_S3_REGION: e.g., us-east-1
• STORAGE_S3_ACCESS_KEY, STORAGE_S3_SECRET_KEY: MinIO credentials
• STORAGE_S3_FORCE_PATH_STYLE: true (required for MinIO)
• STORAGE_S3_BUNDLE_BUCKET: optional separate bucket for bundles (required by server code in this setup)
• EXT_BUNDLES_ALLOW_INSECURE: true (for local/manual validation), or send header x-alga-admin: true
• RUNNER_* not required for publishing (see Runner doc for serving/execution config)

MinIO local setup:

• Run MinIO locally and create the configured bucket.
• Ensure path-style access and credentials align with the server config.
• Validate access using the E2E walkthrough: ee/docs/extension-system/e2e-minio-walkthrough.md

CLI (via alga-client-sdk):

• Pack: alga pack <inputDir> <outputBundlePath>
• Sign: alga sign <bundlePath> --algorithm cosign|x509|pgp
• Publish: alga publish --bundle <bundle> --manifest <manifest.json> [...options]

Auth for local/manual runs:

• Set ALGA_ADMIN_HEADER=true in the environment to automatically inject x-alga-admin: true on API calls from publish.ts.

CI Example Outline

This is an outline; adapt to your CI system (GitHub Actions, GitLab CI, Jenkins, etc.).

Environment variables/secrets (CI):

• SERVER_BASE: Base URL of the server (e.g., https://ee.example.com or http://localhost:3000 in local CI)
• ALGA_ADMIN_HEADER=true (for non-production/internal pipelines only)
• STORAGE_* vars should be set on the server side; CI does not require them unless testing end-to-end with a local server+MinIO instance.

Pipeline steps:

• Step 1: Build extension
  • Run your package build (e.g., npm ci && npm run build) producing ./my-extension/dist with manifest.json.
• Step 2: Pack
  • alga pack ./my-extension/dist ./out/bundle.tar.zst
  • Extract the sha256 from ./out/bundle.sha256 for later steps (or capture console output).
• Step 3: Sign (optional)
  • alga sign ./out/bundle.tar.zst --algorithm cosign
  • Store SIGNATURE as an artifact if you need auditability. -- Step 4: Publish
  • alga publish
    --bundle ./out/bundle.tar.zst
    --manifest ./my-extension/dist/manifest.json
    --declared-hash
    --server "$SERVER_BASE"
    --signature ./out/bundle.tar.zst.SIGNATURE
    --signature-algorithm cosign
  • Parse the output JSON { extension, version, contentHash } for downstream steps or notifications.
• Step 5: Validate (optional)
  • Optionally perform a GET on server endpoints or MinIO to confirm the objects exist at sha256//...
  • For end-to-end UI checks, consider a smoke test that loads the extension UI in a test environment.

Notes and Best Practices

• Immutability:
  • Ensure published bundles are content-addressed via sha256; treat canonical paths as immutable.
• Caching:
  • Downstream Runner and browser clients should leverage immutable URLs and ETag/If-None-Match semantics for efficient serving. See: ee/docs/extension-system/runner-s3-integration.md
• Manifests:
  • Keep manifest.json minimal but sufficient: extension, version, entry.wasm path, and UI asset mapping. Validate JSON strictly in CI.
• Error handling:
  • The publish script prints detailed errors for initiate/PUT/finalize failures. Monitor CI logs and surface them in notifications.

Related Docs

• Development Guide: ee/docs/extension-system/development_guide.md
• E2E Walkthrough (MinIO): ee/docs/extension-system/e2e-minio-walkthrough.md
• Runner S3 Integration: ee/docs/extension-system/runner-s3-integration.md
• Upload Proxy API: ee/server/src/app/api/ext-bundles/upload-proxy/route.ts
• Finalize API: ee/server/src/app/api/ext-bundles/finalize/route.ts