fountainkit-toolsmith-image.git · README.md

fountainkit-toolsmith-image.git / README.md

revision e23c356a35f1af331dd55d3588c2fb3aef04b1c2 · complete file

# FountainKit Toolsmith VM Image

**Suggested repository name:** `fountainkit-toolsmith-image`

This repository captures the automation, documentation, manifests, and release metadata required to build, validate, publish, and distribute the QCOW2 image that FountainKit uses when Toolsmith runs in virtual-machine mode. The tree is the source of truth for how the image is produced, while the tagged GitHub Releases attached to this repo carry the physical QCOW2 files (the "true physics" of the VM) as versioned assets.

## Repository layout

```text
build/                 # Scripts or Packer templates that assemble the image
manifests/tools.json   # Manifest snippet consumed by Toolsmith
scripts/               # Utility helpers for CI/CD and local development
docs/                  # Operational guides, validation instructions, and release notes
releases/              # Metadata about published artifacts (checksums, URLs)
```

Feel free to extend this structure as FountainKit evolves. Keep large binary outputs out of version control; instead, upload them to the Releases section for each tag so the published asset matches the automation at that revision.

## Getting started

1. **Install prerequisites**
   - QEMU (for `qemu-img` and local boot testing)
   - Your chosen provisioning toolchain (Packer, Ansible, Nix, etc.)
   - `shasum` or `sha256sum` for checksum generation
2. **Configure build variables**
   - Update `build/variables.example` (or equivalent) with FountainKit-specific settings (base image URL, default user, tool versions).
3. **Build the image**
   - Run the automation in `build/` (e.g. `make build` or `packer build build/template.json`).
   - The output should be a compressed or raw QCOW2 file stored in your local `dist/` folder.
4. **Validate**
   - Boot the image with QEMU (`make validate` or `scripts/validate.sh`).
   - Execute FountainKit integration smoke tests inside the guest to ensure parity with the sandbox environment.
5. **Publish**
   - Tag the commit that produced the image (e.g. `git tag vYYYY.MM.DD && git push origin vYYYY.MM.DD`).
   - Create a GitHub Release for that tag and upload the QCOW2 (optionally compressed) alongside checksum files (`.sha256`).
   - Record the release asset URL, SHA-256 digest, and manifest snippet in `releases/<version>.md` (or `.json`) for traceability.
6. **Rollout**
   - Update FountainKit's `.toolsmith/tools.json` to reference the new URL and checksum.
   - Communicate the change and instruct consumers to clear old caches if necessary.

## Release cadence and asset management

- Use semantic version tags of the form `vYYYY.MM.DD` (or similar) to align with Toolsmith manifests and release assets.
- Attach every QCOW2 binary to the matching GitHub Release so consumers can fetch the artifact directly from this repo.
- Keep a changelog in `docs/releases.md` summarizing base image upgrades, added packages, configuration changes, and links to the corresponding release assets.
- Automate CI to rebuild and validate the image whenever automation or provisioning scripts change, and to upload the new QCOW2 and checksum files as release assets when tags are pushed.

## Toolsmith integration tips

- The manifest's `qcow2` field should reference the GitHub Release asset URL generated by this repository, keeping the repo as the single source of truth for both automation and binaries.
- The `qcow2_sha256` must match the published file exactly; Toolsmith will refuse to boot if the digest differs. Publish the checksum alongside the asset and mirror it in `manifests/tools.json` to keep everything in sync.
- Encourage consumers to run `toolsmith ensure-vm` (or equivalent helper) after manifest updates to hydrate the new image before executing tasks.

## Support and contributions

Pull requests should include updated automation, manifests, and documentation whenever an image change is proposed. Provide links to validation logs and the artifact download URL in the PR description to streamline reviews.

For questions or operational incidents, open an issue in this repository or reach out to the FountainKit infrastructure team.