Get Started

• 1: Installation
• 2: Quick Start
• 3: Your First Workspace
• 4: Core Concepts

1 - Installation

SOW is one executable: there is no service to enable and no runtime language environment. Release builds target Linux and macOS on amd64 and arm64; Linux also gets RPM and DEB packages. Windows is not supported.

Use the Download page to select the archive or Linux package that matches your operating system and architecture. It links each published artifact, its source tag, and SHA256SUMS.

Install an archive

Download one archive plus SHA256SUMS, then verify the matching line before extraction:

# Linux amd64
grep 'sow_.*_linux_amd64.tar.gz$' SHA256SUMS | sha256sum -c -
tar -xzf sow_*_linux_amd64.tar.gz
sudo install -m 0755 sow /usr/local/bin/sow

On macOS, select darwin_amd64 or darwin_arm64 and replace sha256sum -c - with shasum -a 256 -c -. Without root, install to a directory already on your PATH, such as ~/.local/bin.

Install a Linux package

Linux packages use the 1PGSTY release suffix:

sudo rpm -Uvh ./sow-*-1PGSTY.x86_64.rpm
sudo apt install ./sow_*-1PGSTY_amd64.deb

Choose only the command and architecture that match the host. RPM installs the license at /usr/share/licenses/sow/LICENSE; DEB installs copyright/license metadata under /usr/share/doc/sow/.

Build from source

The module declares Go 1.27.0. Metadata generation needs no C toolchain. Replace vX.Y.Z with the source tag linked from the Download page:

git clone https://github.com/pgsty/sow.git
cd sow
set -euo pipefail
SOW_TAG=vX.Y.Z
git checkout "$SOW_TAG"
SOW_VERSION="${SOW_TAG#v}"
CGO_ENABLED=0 go build -trimpath \
  -ldflags="-s -w -X github.com/pgsty/sow/internal/v2cli.Version=${SOW_VERSION}" \
  -o sow ./cmd/sow
sudo install -m 0755 sow /usr/local/bin/sow

This uses the release build flags and embeds the selected tag’s product version.

Verify

sow version
sow help

sow version reports product version, target OS/architecture, and build Go toolchain. sow help lists the command tree. Each archive also contains README.md, CHANGELOG.md, and the Apache-2.0 LICENSE.

Upgrade a 0.3 Managed Workspace

SOW 0.4 introduces internal database schemas v11 and v12. The public layout and schema: sow/v3 configuration identifier stay the same, but each existing v0.3 Repository must be migrated explicitly before ordinary reads or writes. Stop Workspace writers before taking the backup:

cp -a /srv/sow /srv/sow.backup-before-0.4.0
sow repo migrate REPOSITORY -C /srv/sow
sow check -r REPOSITORY -C /srv/sow

Repeat the last two commands for every Repository named in sow.yml. The database transition is one-way; do not reopen a migrated Workspace with SOW 0.3. See sow repo migrate for the repaired status, signer, and publication evidence.

Permissions and optional tools

The invoking user needs read access to package inputs and write access to the Plain target or Managed workspace. Keep Managed workspaces on a local POSIX filesystem: locks, fsync, safe paths, and atomic rename are part of the correctness contract.

Repository parsing and metadata rendering are in-process. Only two optional paths need host tools:

• RPM package signing requires rpm and a working GPG environment;
• an agent:// metadata key requires gpg and gpg-agent.

Next: Quick Start for Plain mode, or First Workspace for Managed mode.

2 - Quick Start

Plain mode builds a flat repository in one directory. It does not read sow.yml, create a workspace, or keep a database.

mkdir -p /srv/repo
cp /path/to/packages/*.rpm /path/to/packages/*.deb /srv/repo/

sow create /srv/repo

created /srv/repo: rpm=1 deb=1 signed=0 removed=0 marker=false noop=false recovered=false

/srv/repo/
├── package.rpm
├── package.deb
├── repodata/       # RPM: repomd.xml plus primary, filelists, other
├── Packages        # DEB flat index
└── Packages.gz

cd /srv/repo
python3 -m http.server --bind 127.0.0.1 8080

curl --fail http://127.0.0.1:8080/repodata/repomd.xml >/dev/null
curl --fail http://127.0.0.1:8080/Packages.gz >/dev/null

# /etc/yum.repos.d/sow-quickstart.repo
[sow-quickstart]
name=SOW Quick Start
baseurl=http://REPO_HOST:8080/
enabled=1
gpgcheck=0
repo_gpgcheck=0

# /etc/apt/sources.list.d/sow-quickstart.list
deb [trusted=yes] http://REPO_HOST:8080/ ./

sudo dnf makecache
sudo dnf install PACKAGE_NAME

sudo apt update
sudo apt install PACKAGE_NAME

sow create /srv/repo

sow create /srv/repo --json

When to use Managed mode

Use Plain mode when the directory already contains exactly what should be published. Use a Managed workspace when you need named Dists, architecture views, membership policy, signed metadata, generations, audit, or publication targets.

See also sow create and Plain Flat Repositories.

3 - Your First Workspace

Managed mode keeps configuration, membership, generations, and audit state. This example starts from an empty directory.

sow init /srv/sow
cd /srv/sow

/srv/sow/
├── sow.yml   # configuration; schema: sow/v3
└── .sow/     # SQLite state, locks, staging, recovery, journals

sow repo new local
sow dist new el9 --format rpm
sow dist new bookworm --format deb

/srv/sow/local/
├── pool/
└── dists/
    ├── el9/
    │   ├── x86_64/repodata/
    │   └── aarch64/repodata/
    └── bookworm/
        ├── Release
        └── main/
            ├── binary-amd64/{Packages,Packages.gz,by-hash/}
            └── binary-arm64/{Packages,Packages.gz,by-hash/}

sow add /path/to/packages/*.rpm -d el9
sow add /path/to/packages/*.deb -d bookworm

sow add /path/to/more/*.rpm -d el9 --skip
sow build

sow status
sow ls -d el9
sow ls -d bookworm
sow check

sow config show --all

Selection rules

• Workspace: search upward from the current directory, or start from -C DIR.
• Repository: -r NAME, the containing Repository, or the only configured Repository.
• Dist: -d NAME, repeatable; omission is accepted only when the command can resolve an unambiguous scope.

Ambiguity is an error; SOW does not pick an arbitrary Repository or Dist.

Next

• Core Concepts
• Build a YUM Repository
• Build an APT Repository
• sow.yml Reference

4 - Core Concepts

Plain or Managed

The two execution paths are separate.

Choose Plain when directory contents already equal the desired repository. Choose Managed when SOW must own membership, policy, generations, signing, audit, or publication.

Managed hierarchy

Workspace                    /srv/sow
├── sow.yml                  configuration
├── .sow/                    private state; never served
└── Repository               /srv/sow/local
    ├── pool/                canonical package payloads
    └── dists/
        └── Dist             one named RPM or DEB membership set
            └── views        metadata rendered per architecture

• Workspace is the configuration and discovery boundary.
• Repository is the isolation, Generation, publication, and public-tree boundary. Repositories do not deduplicate payloads with one another.
• Dist is a named membership set in exactly one package format.
• Architecture view is derived output, not a second membership set. noarch RPMs and all DEBs are selected into every applicable view without duplicating their pool bytes.

One canonical payload

A package object is identified by its exact-byte SHA-256. Its logical coordinate comes from the RPM header or DEB control data, not the filename.

Each accepted payload has one canonical path under the Repository pool/. RPM architecture views contain repodata/ only; their package locations use parent-relative paths back to the pool. APT Packages entries name the same pool directly.

Ordinary package clients and mirror tools are different contracts. Default dnf reposync rejects the canonical RPM view’s parent traversal. When a self-contained RPM mirror leaf is required, create a separate artifact with sow export rpm-leaf.

Desired and Built

Managed mode tracks intent and public bytes separately:

add / rm -> Desired Membership (revision)
                    |
                  build
                    v
             Built Generation -> pool/ + dists/

add and rm build affected Dists by default. --skip records membership changes but leaves the Repository dirty; sow build later converges Desired into a new Built Generation.

• sow status reads state cheaply and reports ready_to_copy.
• sow check performs the full, read-only delivery proof. Dirty or recovering state is not deliverable.
• sow changes [BASE_GENERATION] describes the physical difference between a recorded Generation and the current Built Generation. It is evidence and planning output, not a substitute for publication recovery or remote verification.
• sow publish TARGET publishes a verified Generation through the configured provider and records target-scoped recovery/checkpoint state.

Transactions and failure states

Writes are serialized by Workspace or Repository locks and journal their intent before public mutation. Payloads and immutable metadata are prepared before mutable protocol pointers. A later writer recovers an interrupted operation before starting new work.

The operational states are:

Use status to diagnose and check as the release gate. Do not publish a Repository with ready_to_copy=false.

Continue

• Managed Workspaces
• Pool & Architecture Views
• Transactions & Recovery
• Publication & Recovery