Skip to content

BUILD.md

Latest commit

 

History

History
88 lines (65 loc) · 2.41 KB

BUILD.md

File metadata and controls

88 lines (65 loc) · 2.41 KB

Build & Packaging Guide

This guide documents the supported build flows and the reproducible release artifact produced by WebSSH2.

Development Builds

Use the standard npm scripts when iterating locally:

npm ci
npm run dev
npm run build

These commands operate directly on the TypeScript sources in the repository and mirror the behaviour of the previous tooling.

Release Artifact Pipeline

Releases publish a tarball that contains only the files required to run WebSSH2 in production:

  1. Install dependencies without development packages. 
    npm ci --omit=dev
  2. Compile the TypeScript project. 
    npm run build
  3. Package the reproducible artifact. 
    node dist/scripts/create-release-artifact.js

Release tags are generated by release-please and use the webssh2-server-v<version> naming convention.

Note: If you install dependencies with --ignore-scripts, run npm run prepare:runtime before packaging to ensure optional native modules are installed when needed.

The packaging script requires GNU tar on the system PATH. The script stages the following files in a deterministic archive:

  • dist/ – compiled JavaScript and type definitions
  • package.json and package-lock.json
  • scripts/postinstall.js and scripts/prestart.js
  • manifest.json – metadata about the build

The script writes the outputs to release-artifacts/ (override with RELEASE_ARTIFACT_DIR). It also emits a SHA-256 checksum file alongside the tarball.

Manifest Format

manifest.json contains:

{
  "version": "x.y.z",
  "gitSha": "<full commit sha>",
  "buildTime": "<ISO 8601 timestamp>",
  "distSha256": "<sha256 of staged dist/>"
}

Use the manifest together with the .sha256 checksum to verify the artifact before deploying.

Validating a Release Artifact

To test a packaged release locally:

tar -xzf webssh2-<version>.tar.gz -C ./test-release
cd ./test-release
npm ci --omit=dev
NODE_ENV=production npm start

The prestart script detects that tsconfig.build.json is absent and skips rebuilding, launching the compiled server from dist/index.js.

CI Integration Checklist

  • GNU tar available on the runner (tar --version prints "GNU tar")
  • npm ci --omit=dev succeeds before building
  • node dist/scripts/create-release-artifact.js runs after compilation
  • Upload both the tarball and its .sha256 file to the release