Skip to main content

ops

OPS.md: Operations Runbook

Target Hardware Manifest (Zero Compromises)​

  • System: Framework Laptop 13
  • Processor: AMD Ryzen™ AI 300 Series - Ryzen™ AI 9 HX 370 (Zen 5, RDNA 3.5, XDNA 2 NPU)
  • Memory: 96GB (2 x 48GB) DDR5-5600 (UMA maximized via BIOS for local LLM inference)
  • Storage: 2TB WD_BLACK™ SN850X NVMe™ M.2 2280
  • Display: 2.8K (2880x1920, 3:2 ratio - Wayland 150% fractional scaling defaults)
  • Expansion I/O: USB-C, USB-A, HDMI (3rd Gen), and Ethernet.

Performance Optimizations​

OS-Level Performance​

The OS image is tuned for the Framework Laptop 13 (Ryzen AI 9 HX 370) with the following kernel arguments:

  • amd_pstate=active: Enables the active EPP (Energy Performance Preference) driver for superior power management and performance on Zen 5 architecture.
  • amdgpu.sg_display=0: Disables scatter-gather display support to resolve flickering issues on certain high-resolution Framework panels.

Documentation Build Performance​

The documentation site (website/) uses Docusaurus 3.10.0 with the @docusaurus/faster plugin. This replaces the standard Webpack-based build system with Rspack, providing significantly faster cold starts and incremental builds.

Local Validation​

Before pushing changes to the repository, you can run the BATS test suite locally if you have bats and podman installed.

Running Tests Locally​

If you have already built the image locally:

podman run --rm localhost/bluefin-framework-antigravity:latest bats /tests/os_validation.bats

Disaster Recovery​

Rolling Back​

Since the OS is atomic, rolling back to a previous "known-good" version is straightforward:

rpm-ostree rollback

Resetting wtgOS Workspace​

If the AI quarantine environment becomes corrupted, you can delete the workspace and recreate it:

rm -rf ~/.local/share/wtg-workspace
ujust setup-workspace

Maintenance​

Updating the Image​

The image is rebuilt daily via GitHub Actions. To update your local system:

rpm-ostree upgrade

Updating GitHub Actions & Website Dependencies​

dependabot will automatically create Pull Requests for GitHub Action and npm package updates. Review and merge these weekly to ensure CI/CD security, stability, and performance.

CI/CD Pipeline​

The pipeline consists of:

  1. YAML Linting: Ensures syntax correctness for all configuration and workflow files.
  2. BlueBuild: Compiles the OCI image based on recipes/recipe.yml.
  3. BATS Validation: Runs the tests/os_validation.bats suite against the newly built image.
  4. Cosign Signing: Cryptographically signs the image if tests pass.
  5. Registry Push: Publishes the signed image to ghcr.io.