Installation

SOW is one executable. It needs no daemon, database service, or language runtime. Release archives support Linux and macOS on amd64 and arm64. Linux also has RPM and DEB packages.

Use the Download page to select a SOW 0.6.1 artifact. Download it and SHA256SUMS into a separate download directory.

Install an archive

For Linux amd64, verify the archive, extract it, and install the executable:

set -euo pipefail
grep '  sow_0.6.1_linux_amd64.tar.gz$' SHA256SUMS | sha256sum -c -
tar -xzf sow_0.6.1_linux_amd64.tar.gz
sudo install -m 0755 sow /usr/local/bin/sow

For macOS, select darwin_amd64 or darwin_arm64. Substitute that archive name and use shasum -a 256 -c - for the checksum command.

To install without root access:

mkdir -p "$HOME/.local/bin"
install -m 0755 sow "$HOME/.local/bin/sow"
export PATH="$HOME/.local/bin:$PATH"

Add the export PATH line to your shell profile to keep it in new sessions.

Install a Linux package

Verify the downloaded package against its entry in SHA256SUMS. Then run the command for your distribution:

# RPM, x86_64
sudo rpm -Uvh ./sow-0.6.1-1PGSTY.x86_64.rpm

# Debian or Ubuntu, amd64
sudo apt install ./sow_0.6.1-1PGSTY_amd64.deb

For ARM64, use the RPM ending in .aarch64.rpm or the DEB ending in _arm64.deb. Packages install the executable at /usr/bin/sow.

Build from source

Install Go 1.27.3 or newer and Git. The build uses CGO_ENABLED=0 and needs no C compiler.

set -euo pipefail
git clone --branch v0.6.1 https://github.com/pgsty/sow.git
cd sow
SOW_BUILD_DIR="$(mktemp -d)"
CGO_ENABLED=0 go build -trimpath \
  -ldflags='-s -w -X github.com/pgsty/sow/internal/v2cli.Version=0.6.1' \
  -o "$SOW_BUILD_DIR/sow" ./cmd/sow
sudo install -m 0755 "$SOW_BUILD_DIR/sow" /usr/local/bin/sow

Verify the installation

sow version
sow help

version shows the product version, target operating system and architecture, and Go toolchain. help lists commands. Use sow help COMMAND for a command’s options.

Upgrade to 0.6.1

SOW 0.6.1 keeps database schema v13, configuration schema sow/v3, and the public directory layout. Workspaces already on 0.5.0 or 0.6.0 need no schema migration.

1. Stop all workspace writers.
2. Back up the complete workspace with a tool that preserves hard links, such as rsync -aH or tar.
3. Install SOW 0.6.1.
4. Build and check each Repository in sow.yml:

sow version
sow build -r REPOSITORY -C /srv/sow
sow check -r REPOSITORY -C /srv/sow

Replace REPOSITORY with its configured name. A current repository produces a no-op build. An unchanged build keeps its Generation and metadata timestamps. New builds record one publication time and reuse it during recovery.

Workspaces from 0.3 or 0.4

These workspaces need migration before the first build. After backing up the workspace and installing 0.6.1, run:

sow repo migrate REPOSITORY -C /srv/sow
sow build -r REPOSITORY -C /srv/sow
sow check -r REPOSITORY -C /srv/sow

Repeat these commands for each Repository. Migration updates the database; the rebuild applies the current RPM verification and APT metadata rules. Keep the backup for rollback to a version that uses an older schema. See sow repo migrate and the 0.6.0 release notes.

Upgrade a Plain repository

Plain mode has no database to migrate. For an existing YUM repository, follow Migrate an Existing YUM Repository before changing its generator. The --metadata-timestamp default remains 0. Set the timestamp from the repository’s publication history so cached YUM clients accept the new index.

Storage and optional tools

The SOW user needs read access to input packages and write access to the repository. Keep Managed workspaces on a local POSIX filesystem with file locks, fsync, and atomic rename.

Package parsing and metadata generation run inside SOW. Optional signing needs these host tools:

Continue with Quick Start for Plain mode or First Workspace for Managed mode.