diff --git a/README.md b/README.md index 3c1346a..cdc2008 100644 --- a/README.md +++ b/README.md @@ -1,21 +1,21 @@ # Talos CM5 Builder -Custom Talos Linux images for Raspberry Pi CM5 on Compute Blade hardware. +Custom Talos Linux images for Raspberry Pi 5 / CM5 on Compute Blade hardware. -[![Docker Hub](https://img.shields.io/docker/v/svrnty/talos-rpi5?sort=semver&label=talos-rpi5&logo=docker)](https://hub.docker.com/r/svrnty/talos-rpi5) +[![Docker Hub](https://img.shields.io/docker/v/svrnty/talos-rpi5?sort=semver&label=talos-rpi5&logo=docker&arch=arm64)](https://hub.docker.com/r/svrnty/talos-rpi5) [![Docker Pulls](https://img.shields.io/docker/pulls/svrnty/talos-rpi5?logo=docker)](https://hub.docker.com/r/svrnty/talos-rpi5) -[![Docker Image Size](https://img.shields.io/docker/image-size/svrnty/talos-rpi5?sort=semver&logo=docker)](https://hub.docker.com/r/svrnty/talos-rpi5) +[![Docker Image Size](https://img.shields.io/docker/image-size/svrnty/talos-rpi5?sort=semver&logo=docker&arch=arm64)](https://hub.docker.com/r/svrnty/talos-rpi5) The official Talos Image Factory does not support CM5 — the mainline kernel lacks CM5 device trees and RP1 driver support. This builder uses the RPi downstream kernel (via [talos-rpi5/talos-builder](https://github.com/talos-rpi5/talos-builder) patches) to produce working CM5 images with our extensions and overclock config. ## Current versions -| Component | Version | -|-----------|---------| -| Talos Linux | `v1.12.3` | -| RPi Kernel | `6.12.47` | -| iscsi-tools | `v0.1.6` | -| util-linux-tools | `2.40.4` | +| Component | Version | | +|-----------|---------|---| +| Talos Linux | `v1.12.3` | [![](https://img.shields.io/docker/v/svrnty/talos-rpi5?sort=semver&label=latest&logo=docker&arch=arm64)](https://hub.docker.com/r/svrnty/talos-rpi5) | +| RPi Kernel | `6.12.47` | arm64 only | +| iscsi-tools | `v0.1.6` | | +| util-linux-tools | `2.40.4` | | ## Image tags @@ -33,105 +33,32 @@ For example: `v1.12.3-k6.12.47-2` | `k6.12.47` | RPi downstream kernel version | | `2` | Build revision (bumped for config/patch changes on the same upstream versions) | -Use this tag with `talosctl upgrade`: +## Usage + +### Install from raw disk image + +Download `metal-arm64.raw.zst` from the [latest release](../../releases/latest) and flash to eMMC: + +```bash +zstd -d metal-arm64.raw.zst -o metal-arm64.raw +# Flash to eMMC/SD via your preferred tool (dd, balenaEtcher, etc.) +``` + +### Upgrade an existing node ```bash talosctl upgrade --image docker.io/svrnty/talos-rpi5:v1.12.3-k6.12.47-2 ``` -## What it builds +### What's included -- **Installer image** → `docker.io/svrnty/talos-rpi5:` (for `talosctl upgrade`) -- **Raw disk image** → Gitea release `metal-arm64.raw.zst` (for eMMC flashing) - -Baked-in config: - RPi downstream kernel with CM5/RP1 support - Overclock: 2.6GHz (`arm_freq=2600`, `over_voltage_delta=50000`, `arm_boost=1`) - Extensions: `iscsi-tools`, `util-linux-tools` -## Usage +## Building -### Building locally (ARM64 host required) - -```bash -make checkouts patches # Clone and patch sources -make kernel # Build RPi kernel -make overlay # Build SBC overlay -make installer # Build installer + disk image -``` - -### CI/CD (Gitea Actions) - -Push a version tag to trigger an automated build: - -```bash -git tag v1.12.3-k6.12.47-2 -git push origin v1.12.3-k6.12.47-2 -``` - -The pipeline runs on the ARM64 self-hosted runner and: -1. Builds the kernel, overlay, and installer -2. Pushes the installer image to Docker Hub -3. Creates a Gitea release with the raw disk image - -### Upstream update checks - -A weekly scheduled workflow checks for new Talos and RPi kernel releases and creates Gitea issues when updates are available. - -## CI Secrets - -| Secret | Description | -|--------|-------------| -| `REGISTRY_USERNAME` | Docker Hub username (org-level) | -| `REGISTRY_PASSWORD` | Docker Hub access token (org-level) | -| `COSIGN_PRIVATE_KEY` | PEM-encoded cosign signing key (org-level) | -| `COSIGN_PASSWORD` | Password for the cosign private key (org-level) | - -## Runner Setup (Apple Silicon Mac Mini) - -The build runner needs: -- Docker Desktop with Buildx (arm64 native) -- Gitea `act_runner` registered with labels: `self-hosted`, `macOS`, `arm64` -- Sufficient disk space for kernel builds (~20GB) - -```bash -# Install act_runner via Homebrew -brew install act_runner - -# Or download directly -curl -sL https://gitea.com/gitea/act_runner/releases/latest/download/act_runner-darwin-arm64 -o act_runner -chmod +x act_runner - -# Register -./act_runner register \ - --instance https://git.openharbor.io \ - --token \ - --name mac-mini \ - --labels self-hosted,macOS,arm64 - -# Run as service -./act_runner daemon -``` - -## Structure - -``` -.gitea/workflows/ - build.yaml # Build pipeline (tag push trigger) - check-updates.yaml # Upstream update checker (weekly cron) -Makefile # Build orchestration -config/ - config.txt.append # CM5 overclock settings - extensions.yaml # System extensions list -scripts/ - check-upstream.sh # Version comparison script -patches/ - siderolabs/ - pkgs/0001-*.patch # RPi kernel patch - talos/0001-*.patch # Module list patch - talos-rpi5/ - sbc-raspberrypi5/ # Overlay patches (Go toolchain bump) -``` +For local builds, CI/CD setup, runner configuration, and project structure, see [TECHNICAL.md](TECHNICAL.md). ## License diff --git a/TECHNICAL.md b/TECHNICAL.md new file mode 100644 index 0000000..0c89f97 --- /dev/null +++ b/TECHNICAL.md @@ -0,0 +1,87 @@ +# Technical Guide + +Build infrastructure, CI/CD configuration, and project structure for the Talos CM5 Builder. + +## Building locally (ARM64 host required) + +```bash +make checkouts patches # Clone and patch upstream sources +make kernel # Build RPi kernel +make overlay # Build SBC overlay +make installer # Build installer + disk image +``` + +## CI/CD (Gitea Actions) + +Push a version tag to trigger an automated build: + +```bash +git tag v1.12.3-k6.12.47-2 +git push origin v1.12.3-k6.12.47-2 +``` + +The pipeline runs on the ARM64 self-hosted runner and: +1. Builds the kernel, overlay, and installer +2. Attaches SBOM attestation (cosign + syft) +3. Pushes the installer image to Docker Hub +4. Creates a Gitea release with the raw disk image + +### Upstream update checks + +A weekly scheduled workflow checks for new Talos and RPi kernel releases and creates Gitea issues when updates are available. + +## CI Secrets + +| Secret | Description | +|--------|-------------| +| `REGISTRY_USERNAME` | Docker Hub username (org-level) | +| `REGISTRY_PASSWORD` | Docker Hub access token (org-level) | +| `COSIGN_PRIVATE_KEY` | PEM-encoded cosign signing key (org-level) | +| `COSIGN_PASSWORD` | Password for the cosign private key (org-level) | + +## Runner Setup (Apple Silicon Mac Mini) + +The build runner needs: +- Docker Desktop with Buildx (arm64 native) +- Gitea `act_runner` registered with labels: `self-hosted`, `macOS`, `arm64` +- Sufficient disk space for kernel builds (~20GB) + +```bash +# Install act_runner via Homebrew +brew install act_runner + +# Or download directly +curl -sL https://gitea.com/gitea/act_runner/releases/latest/download/act_runner-darwin-arm64 -o act_runner +chmod +x act_runner + +# Register +./act_runner register \ + --instance https://git.openharbor.io \ + --token \ + --name mac-mini \ + --labels self-hosted,macOS,arm64 + +# Run as service +./act_runner daemon +``` + +## Project Structure + +``` +.gitea/workflows/ + build.yaml # Build pipeline (tag push trigger) + check-updates.yaml # Upstream update checker (weekly cron) +Makefile # Build orchestration +config/ + config.txt.append # CM5 overclock settings + extensions.yaml # System extensions list +scripts/ + check-upstream.sh # Version comparison script +patches/ + siderolabs/ + pkgs/0001-*.patch # RPi kernel patch + talos/0001-*.patch # Module list patch + talos-rpi5/ + sbc-raspberrypi5/ # Overlay patches (Go toolchain bump) +cosign.pub # Public key for verifying image attestations +```