flog
Documentation menu

Installer and release channels

scripts/install is flog's canonical POSIX installer. The future https://flog.run/install endpoint must serve that file byte-for-byte; the website must not copy or reimplement it.

Once the endpoint and an initial stable channel are deployed, the normal command is:

curl -fsSL https://flog.run/install | sh

The script supports Linux and macOS on amd64 and arm64. It requires curl, tar, awk, and either sha256sum or shasum. It installs to $HOME/.local/bin/flog by default. It never invokes sudo, modifies a shell profile, or guesses a different privileged destination.

Installer controls#

  • FLOG_INSTALL_DIR=/absolute/path selects an explicit destination.
  • FLOG_VERSION=1.2.3 installs one exact historical or prerelease version and bypasses the mutable channel index.
  • FLOG_CHANNEL=next selects an explicit prerelease channel. The default is stable. It cannot be combined with FLOG_VERSION.
  • FLOG_RELEASES_URL=https://mirror.example/releases selects a compatible manifest origin.
  • FLOG_ALLOW_HTTP=1 permits HTTP for isolated local tests. Production use must retain HTTPS; without this opt-in, HTTP manifests, artifacts, and redirect targets are rejected.

Manifest protocol#

The protocol is strict newline-terminated, tab-separated text so the installer can parse it without jq, Python, Node, or sourced shell code. Unknown, duplicate, missing, malformed, CR-containing, and NUL-containing records are rejected by the Go tooling. The shell parser independently checks every record it consumes.

The mutable https://flog.run/releases/channels.v1 has this shape:

flog-channels-v1
stable	1.2.3
prerelease	next	1.3.0-pre.2

It contains exactly one stable version and zero or more explicitly named prerelease channels. It never contains URLs and never infers a version from Job numbers, timestamps, filenames, lexical ordering, or whichever build is newest.

Each selected version resolves to the immutable https://flog.run/releases/<version>/manifest.v1:

flog-release-v1
version	1.2.3
revision	0123456789abcdef0123456789abcdef01234567
artifact	darwin	amd64	<64-character-sha256>	<immutable-https-url>
artifact	darwin	arm64	<64-character-sha256>	<immutable-https-url>
artifact	linux	amd64	<64-character-sha256>	<immutable-https-url>
artifact	linux	arm64	<64-character-sha256>	<immutable-https-url>

Release manifests require all four supported targets, an exact semantic version, a full source commit, one unique artifact per target, and one SHA-256 checksum per artifact.

Installation safety#

The installer resolves the channel before selecting an immutable version manifest. It downloads into a mode-0700 staging directory located inside the destination directory, verifies the archive's SHA-256 checksum, requires the exact archive entries BUILD-INFO.json, LICENSE, and flog, and streams only the flog entry into the staged executable. The final rename occurs on the same filesystem and is the only operation that replaces an existing installation.

Network errors, redirects to disallowed protocols, malformed manifests, missing targets, checksum failures, malformed archives, interrupted downloads, and destination errors remove staging data and preserve an existing executable. Repeating the same version installation produces the same installed bytes.

Creating an immutable release manifest#

Job 1's automatic master Runs produce public SHA-versioned development artifacts, not channel promotions. For a semantic release, manually run Job 1 from the exact full source SHA with an explicit version as documented in releases.md, then download its artifacts and verify SHA256SUMS.

Create the version manifest without overwriting an existing one:

version=1.2.3
revision=0123456789abcdef0123456789abcdef01234567
run=123

mkdir -p "publish/releases/$version"
go run ./internal/releasecmd release-manifest \
  --checksums dist/SHA256SUMS \
  --version "$version" \
  --revision "$revision" \
  --artifact-url-template \
    "https://repopack.com/api/v0/jobs/1/runs/$run/artifacts/{filename}?project=flog" \
  --output "publish/releases/$version/manifest.v1"

The URL template uses Repopack's public immutable per-Run artifacts. Confirm the Run's source_sha, version argument, public access, filenames, and checksums before publishing the manifest. Publish the immutable version manifest before changing any channel.

Promoting a channel#

Promotion reads and validates both the current channel file and immutable release manifest, applies one SemVer-safe change, and replaces the output through a same-directory temporary file:

go run ./internal/releasecmd promote \
  --channels publish/releases/channels.v1 \
  --release "publish/releases/$version/manifest.v1" \
  --channel stable \
  --output publish/releases/channels.v1

The first promotion may create a missing channel file, but it must establish a stable version. Stable promotion rejects prereleases and SemVer regressions. Named prerelease channels reject stable versions and regressions. Equal-version promotion is an idempotent no-op in content. Review the diff, upload immutable files first, and update channels.v1 last. Public artifacts alone never update a channel or the installer.

SHA-256 protects downloaded bytes against corruption and substitution relative to the HTTPS manifest. Release-manifest signing and offline key management are tracked separately; until that is implemented, HTTPS integrity and controlled, reviewed channel promotion remain mandatory. Flog task #20 tracks signing and offline key management.

Self-update#

An installed POSIX release can update itself through the same manifests and artifact checks as the installer:

flog update
flog update --channel next
flog update --version 1.2.3

The default is stable. --channel deliberately opts into a named prerelease channel, while --version selects one exact stable, prerelease, or historical version. Channel updates refuse to move backwards or sideways in SemVer precedence; an exact --version is required for a deliberate downgrade. If the selected version exactly matches the running version, the command is a no-op.

--releases-url selects a compatible manifest mirror. The equivalent environment controls are FLOG_CHANNEL, FLOG_VERSION, and FLOG_RELEASES_URL; command-line selection options override channel/version environment values. FLOG_ALLOW_HTTP=1 exists only for isolated local fixtures and must not be used in production.

Self-update supports the same Linux/macOS amd64/arm64 matrix as the installer. It verifies strict channel and immutable release manifests, redirect protocols, the archive SHA-256, exact archive entries, and BUILD-INFO.json before writing a staged executable beside the running binary. A same-directory rename is the only replacement operation. Network, validation, checksum, archive, staging, permission, interruption, and rename failures leave the previous executable in place. The command never invokes sudo, changes profiles, or chooses another installation path; a non-writable executable directory produces an actionable error.