# ScoutFS Package Build Repository

Automated build infrastructure for producing ScoutFS packages for Debian and RHEL-based distributions.

This repo is designed to work alongside the upstream [ScoutFS](https://github.com/versity/scoutfs) source, which is mirrored to `https://git.anomalous.dev/mirrors/scoutfs/`. When a version tag (`v*`) is pushed, Gitea Actions build and publish release packages to the mirror repo's releases page.

## Package Types

| Package | Format | Strategy | Description |
|---------|--------|----------|-------------|
| `scoutfs-dkms` | .deb | DKMS | Builds kernel module on install against running kernel |
| `scoutfs-utils` | .deb | Binary | User-space CLI utility, fenced daemon, man pages |
| `scoutfs-dev` | .deb | Headers | `format.h` + `ioctl.h` for development |
| `kmod-scoutfs-*` | .rpm | Pre-built | Kernel-version-locked module for EL8/EL9 |
| `scoutfs-kmod-dkms` | .rpm | DKMS | Builds kernel module on install (noarch) |
| `scoutfs-utils` | .rpm | Binary | User-space CLI utility |

## Architecture

```
GitHub (versity/scoutfs)  ──auto-mirror──►  Gitea (mirrors/scoutfs)
                                                    │
                                            v* tag triggers
                                                    │
                                                    ▼
                                           Gitea (builds/scoutfs-packages)
                                                    │
                                         ┌──────────┼──────────┐
                                         ▼          ▼          ▼
                                   .deb (DKMS)   .rpm       .rpm
                                   Debian 12    Pre-built   DKMS
                                   Ubuntu 22    EL8/EL9     (noarch)
                                   Ubuntu 24
                                         │          │          │
                                         └──────────┼──────────┘
                                                    ▼
                                          mirrors/scoutfs releases
```

## Directory Structure

```
.gitea/workflows/     Gitea Actions CI/CD workflows
  release.yml         Full build + publish on v* tags
  ci.yml              Compile checks on push/PR

dkms/                 DKMS configuration
  dkms.conf           Module build config for DKMS
  dkms-pre-build.sh   Kernel compatibility pre-flight check

debian/               Debian/Ubuntu packaging
  control             Package definitions (scoutfs-dkms, scoutfs-utils, scoutfs-dev)
  rules               Build rules
  source/format       Source package format
  compat              debhelper compatibility level
  scoutfs-dkms.*      DKMS package hooks

rpm/                  RPM packaging
  scoutfs-kmod-dkms.spec.in   DKMS RPM spec template

scripts/              Build and runtime scripts
  check-kernel-compat.sh       Standalone kernel compat test
  scoutfs-kernel-hook          Kernel postinst/postrm hook
  50-scoutfs-kernel-install.sh RHEL kernel-install plugin
  gen-deb-changelog.sh         Debian changelog generator

docker/               Pre-built RPM infrastructure (from greg/closer-kver-locking)
  Dockerfile           Build container image
  build-all.sh         Multi-version orchestrator
  build-container.sh   Docker image manager
  build-minor.sh       Per-version build coordinator
  build-packages.sh    Main RPM build script with mock
  repo-fixup.sh        Repository configuration
```

## Setup

### Gitea Secrets Required

| Secret | Description |
|--------|-------------|
| `SCOUTFS_FORMAT_HASH` | 64-bit hex format hash for utils build |
| `GITEA_RELEASE_TOKEN` | API token with write access to `mirrors/scoutfs` releases |

### Mirror Configuration

1. Set up Gitea to auto-mirror `https://github.com/versity/scoutfs` to `mirrors/scoutfs`
2. Create this build repo at `builds/scoutfs-packages`
3. Configure the secrets above in the build repo settings
4. When upstream pushes a `v*` tag, the mirror syncs it, and the release workflow triggers

## Kernel Compatibility

ScoutFS supports Linux kernels from ~3.6 through 6.12+. The DKMS packages include safety mechanisms:

- **Pre-build check** (`dkms-pre-build.sh`): Validates kernel headers exist, required headers present, minimum version met
- **Kernel install hook** (`scoutfs-kernel-hook`): Automatically attempts DKMS build for new kernels; logs warnings on failure but never blocks kernel updates
- **RHEL kernel-install plugin** (`50-scoutfs-kernel-install.sh`): Bridges to the kernel hook on systemd-based RHEL systems

### Testing Compatibility

```bash
# Test against the running kernel
./scripts/check-kernel-compat.sh

# Test against specific kernel headers
./scripts/check-kernel-compat.sh /lib/modules/6.8.0-45-generic/build
```

## Local Development

### Build .deb packages locally

```bash
# Clone scoutfs source alongside
git clone https://github.com/versity/scoutfs.git scoutfs

# Install build deps
sudo apt-get install debhelper dkms dpkg-dev libuuid-dev libssl-dev libblkid-dev

# Generate changelog and build
VERSION=1.29 bash scripts/gen-deb-changelog.sh 1.29 > debian/changelog
SCOUTFS_FORMAT_HASH=<hash> dpkg-buildpackage -us -uc -b
```

### Build pre-built RPMs locally

```bash
# Clone scoutfs source and overlay docker scripts
git clone https://github.com/versity/scoutfs.git scoutfs
cp docker/* scoutfs/

# Build for EL9.6
cd scoutfs
EL_VER=9.6 IS_EDGE=1 RELEASE=1 bash build-minor.sh
```