Why SOW Uses One Payload Tree per Repository

Wed, 05 Aug 2026 00:00:00 +0000

This decision was drafted on 2026-08-05 during the pre-v0.2 release design consolidation and shipped in SOW v0.2.0 on 2026-08-08. It remains the layout contract in v0.3 and v0.4. It records an architecture choice, not a blanket compatibility claim: protocol closure, ordinary package clients, mirror tools, static hosting, and object storage are verified as separate evidence layers.

Decision

Each SOW Repository owns one public tree:

<repository>/
  pool/                         # canonical package bytes
  dists/
    <dist>/
      <architecture>/           # protocol metadata only

A Package Object has one canonical payload path inside one Repository. Adding the same object to several Dists or architecture views adds membership and metadata references; it does not create another canonical package file.

Build an APT Repository

Mon, 01 Jan 0001 00:00:00 +0000

This tutorial creates a new Managed DEB repository. You need a writable directory, and one or more DEB files.

1. Create the workspace

mkdir -p /srv/sow
cd /srv/sow
sow init .
sow repo new pigsty
sow dist new trixie --format deb -r pigsty

The Dist name becomes the APT suite. It is an identifier chosen by you; SOW does not infer distribution semantics from trixie.

Tutorials

Mon, 01 Jan 0001 00:00:00 +0000

Each tutorial starts from a new workspace. Commands are intended to be run in order; replace uppercase placeholders and package paths for your environment.

If you have not installed SOW yet, start with Installation and Quick Start. The tutorials below cover the managed repository path.

Build a YUM Repository

A managed RPM repository with per-architecture views, noarch projection, debuginfo filtering, version limits, and a working dnf client configuration.

Build an APT Repository

A managed DEB repository with a Debian-style pool, by-hash indexes, and a deb822 client configuration.

Sign Your Repository

Mon, 01 Jan 0001 00:00:00 +0000

SOW has two independent signing paths:

Path	Output	Client control
RPM metadata	`repodata/repomd.xml.asc`	`repo_gpgcheck=1`
APT metadata	`InRelease` and `Release.gpg`	`Signed-By`
RPM package body	embedded RPM signature	`gpgcheck=1`

APT trusts package hashes through the signed Release; SOW does not re-sign DEB package bodies. Start with metadata signing. Add RPM package signing only when you own the signing policy for those package bytes.

1. Create a dedicated key

The commands below create an unencrypted example key. Use a protected key and a passphrase reference for production; see the configuration reference.

Signing Model

Mon, 01 Jan 0001 00:00:00 +0000

There are two different questions a client can ask about a repository, and SOW answers them with two separate mechanisms. Confusing them is the most common source of “I signed it but dnf still complains”, so this page starts by pulling them apart.

Two independent trust chains

	Metadata signing	RPM package signing
Question answered	“Is this index really from you, and unmodified?”	“Is this `.rpm` file really from you?”
Configured by	`signing.rpm.metadata`, `signing.deb.metadata`	`signing.rpm.packages`
Produces	`repodata/repomd.xml.asc`, `InRelease`, `Release.gpg`	an OpenPGP signature embedded in the package
Changes package bytes	no	yes
Client setting	dnf `repo_gpgcheck=1`, apt `Signed-By`	dnf `gpgcheck=1`
Available in Plain mode	no	yes, via `create -S KEY`

They are configured separately and can be used separately. Metadata signing alone is usually the right starting point: it authenticates the whole index in one place and requires no change to the packages you received from upstream.

Platforms & Integrations

Mon, 01 Jan 0001 00:00:00 +0000

This page defines the environments SOW ships for, the storage semantics it requires, and the exact scope of its automated integrations. Repository generation happens inside the SOW binary; a real package manager remains the final check for a deployed repository.

Release targets

Operating system	`amd64`	`arm64`	Artifact
Linux	yes	yes	archive, RPM, DEB
macOS	yes	yes	archive
Windows	no	no	not supported

Release binaries use CGO_ENABLED=0 and require no language runtime. The 0.4.0 artifacts were built with Go 1.27.0; the source module requires Go 1.27.0 or newer. Archives include README.md, CHANGELOG.md, and the Apache-2.0 LICENSE; Linux packages install the same license with the binary. Use sow version to print the product version, target OS/architecture, and build toolchain.

apt on SOW

Why SOW Uses One Payload Tree per Repository

Decision

Build an APT Repository

1. Create the workspace

Tutorials

Sign Your Repository

1. Create a dedicated key

Signing Model

Two independent trust chains

Platforms & Integrations

Release targets