svrnty/talos-rpi5
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 23 Wiki Activity

Split README into user manual and TECHNICAL.md

Browse Source 
Move CI/CD, runner setup, secrets, and project structure to
TECHNICAL.md. Streamline README as a user-facing guide with
install/upgrade instructions. Fix Docker badges for arm64.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Mathias Beaulieu-Duncan 2026-02-13 16:55:37 -05:00
parent 2618de74e8
commit 907dd98b24
2 changed files with 111 additions and 97 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

121
README.md
View File

@ -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:<tag>` (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 <runner-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

87
TECHNICAL.md Normal file
View File

@ -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 <runner-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
```