Build and package¶

The packaging scripts build, sign, package, install, enroll, drain, and roll back AWC for a VM deployment. They work alongside the systemd units (see systemd units).

Scripts¶

Script	What it does
`build-release.sh`	`cargo build --release --locked` for `awcd`, `awc-worker`, `awc-control`, `awcctl` with production FUSE and S3 features; stages stripped binaries under `dist/staging/awc-<target>/bin/`
`sign.sh <staging-dir>`	Writes `SHA256SUMS` and a detached signature. Uses `cosign sign-blob` if available, otherwise `gpg --detach-sign`. Fails loudly if neither signer is present
`package.sh`	Runs the full pipeline: build, stage units, scripts, defaults, migrations, offline docs, golden vectors, and SBOM, sign, then `dist/awc-<version>-<target>.tar.gz`
`install.sh`	Idempotent, upgrade-safe install: versioned `/opt/awc/versions/<v>` with a `current` symlink, the `awc` system user, units, the health check, and default config (only if absent). Run as root
`enroll.sh`	Local host enrollment: writes `/etc/awc/awcd.toml` and `awcd.env`, creates state dirs, mints a host id and a placeholder control endpoint (provision mTLS identity separately)
`drain.sh [awcd\\|worker\\|control\\|all]`	Graceful drain (SIGTERM; `awcd` reconciles live sessions), bounded by `MAX_WAIT`
`rollback.sh [version]`	Repoints `/opt/awc/current` to a prior version, reloads systemd, restarts active services
`awc-health-check.sh`	Minimal HTTP probe used by the units' `ExecStartPost`; installed to `/usr/lib/awc/awc-health-check`

Build and package¶

packaging/package.sh
# -> dist/awc-<version>-<target>.tar.gz
#    dist/SHA256SUMS{,.bundle|.gpg}       (copied next to the tarball)
#    dist/staging/awc-<target>/{bin,lib/systemd/system,lib/awc,share/awc,install.sh,...,SHA256SUMS,.bundle|.gpg}

Override the target with TARGET=<triple>. The version is read from the workspace Cargo.toml. Signing uses cosign if it is on PATH, otherwise gpg.

What the tarball carries besides binaries¶

Under share/awc/ in the tarball:

migrations/ — the control-plane PostgreSQL migrations (crates/awc-db/migrations/), so an offline host can inspect or replay the schema.
docs/ — kernel-compatibility.md, on-disk-format.md, golden-vectors.md, and upgrade.md, for offline reference.
golden-vectors/golden_vectors.json — the golden manifest vectors used by CI, for offline conformance checks.
sbom.spdx.json — an SPDX JSON SBOM of the repository, produced with syft.

SBOM¶

package.sh scans with syft when it is on PATH. Without syft it writes share/awc/sbom.MISSING and continues. Set AWC_REQUIRE_SBOM=1 to make a missing SBOM fail the build instead. Release builds (the release workflow) always set it.

The SBOM lands inside the tarball before sign.sh runs, so SHA256SUMS covers it.

Install and enroll (on the VM, as root)¶

tar xzf awc-<version>-<target>.tar.gz
cd awc-<target>
./install.sh
./enroll.sh --control-endpoint https://control.example.invalid
systemctl enable --now awcd

install.sh is safe to re-run for upgrades. It never overwrites /etc/awc/* and prunes to the last KEEP_VERSIONS (default 3), so rollback is always possible. See Upgrade a deployment.

Verify a package¶

sha256sum -c SHA256SUMS
# cosign: cosign verify-blob --bundle SHA256SUMS.bundle SHA256SUMS
# gpg:    gpg --verify SHA256SUMS.gpg SHA256SUMS

Layout on the host¶

/opt/awc/versions/<v>/{bin,lib/systemd/system,lib/awc,share/awc/{migrations,docs,golden-vectors}}
/opt/awc/current                        -> versions/<v>
/usr/bin/{awcd,awc-worker,awc-control,awcctl}
/usr/lib/awc/awc-health-check
/etc/systemd/system/{awcd,awc-worker,awc-control}.service
/etc/awc/{awcd.toml,awcd.env,worker.env,control.env}
/var/lib/awc/{basefs,cache,workspaces,binds}   (awc:awc, 0750)
/var/cache/awc  /var/log/awc                    (awc:awc)

See systemd units for capability boundaries, hardening, and the drain, restart, and rollback semantics.

Cut a release¶

Pushing a v* tag triggers the release workflow. It re-runs the test gates, packages with AWC_REQUIRE_SBOM=1, signs the tarball keyless with cosign (OIDC; the certificate and rekor entry land in <tarball>.bundle), and creates a GitHub release with the tarball, SHA256SUMS, its bundle, the tarball bundle, the SBOM, and the cargo deny log. Release notes come from the matching section of CHANGELOG.md.

Steps:

Update CHANGELOG.md (Keep a Changelog format) and wait for green CI on main.
Push a rehearsal tag: git tag v0.1.0-rc1 && git push origin v0.1.0-rc1. An -rc* tag reuses the notes of the version it rehearses.
Verify the release assets and the signature:

cosign verify-blob --bundle awc-<version>-<target>.tar.gz.bundle \
  awc-<version>-<target>.tar.gz \
  --certificate-identity-regexp '^https://github.com/nibzard/awc/' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

The issuer is GitHub's OIDC token issuer; the identity is the workflow ref inside this repository. 4. Delete the rehearsal release and tag, then tag v0.1.0 on the same commit and push it.

The Postgres and minio service jobs from CI are not repeated in the release workflow: the tag points at a commit that already passed them on push.