buckit/docs/release-process.md

# Buckit Release Process

## Cutting a Release

### Stable release

```sh
git tag RELEASE.2026-05-10T23-30-35Z
git push origin RELEASE.2026-05-10T23-30-35Z
```

Or generate the timestamp automatically:

```sh
TAG=RELEASE.$(date -u +%Y-%m-%dT%H-%M-%SZ)
git tag $TAG
git push origin $TAG
```

### Release candidate

```sh
TAG=RELEASE.$(date -u +%Y-%m-%dT%H-%M-%SZ).rc1
git tag $TAG
git push origin $TAG
```

### Tag format

The tag **must** follow `RELEASE.YYYY-MM-DDTHH-MM-SSZ` exactly. All
components (year, month, day, hour, minute, second) are required. The build
will fail if any part is missing.

Examples:
- `RELEASE.2026-05-10T23-30-35Z` — stable
- `RELEASE.2026-05-10T23-30-35Z.rc1` — release candidate

## What Happens Automatically

Once you push a tag, the **Release** workflow (`.github/workflows/release.yml`)
triggers. Monitor it at:

```
https://github.com/buckit-io/buckit/actions/workflows/release.yml
```

Or via CLI:

```sh
gh run list --workflow=release.yml --repo buckit-io/buckit
```

The workflow runs these jobs in order:

1. **build** — Compiles binaries for linux/amd64, linux/arm64, windows/amd64, darwin/arm64. Signs each with minisign. Generates `.deb`, `.rpm`, and `.apk` packages with `nfpm` on Linux, plus checksum files for those packages.
2. **docker** — Builds and pushes multi-arch Docker images to ghcr.io and Docker Hub.
3. **publish** — Creates a GitHub Release with all artifacts attached.
4. **update-gh-pages** — Publishes stable per-platform download files to GitHub Pages (stable releases only).

All jobs should show ✅. If any job fails, click into it to see the error log.

Release candidates skip the `:latest` Docker tag and the gh-pages update.

## Downloading Releases

### Binaries

```sh
# Linux
curl -LO https://github.com/buckit-io/buckit/releases/download/RELEASE.2026-05-10T23-30-35Z/buckit-linux-amd64.RELEASE.2026-05-10T23-30-35Z

# macOS
curl -LO https://github.com/buckit-io/buckit/releases/download/RELEASE.2026-05-10T23-30-35Z/buckit-darwin-arm64.RELEASE.2026-05-10T23-30-35Z

# Windows
curl -LO https://github.com/buckit-io/buckit/releases/download/RELEASE.2026-05-10T23-30-35Z/buckit-windows-amd64.exe.RELEASE.2026-05-10T23-30-35Z
```

### Docker

```sh
docker pull ghcr.io/buckit-io/buckit:latest
docker pull buckitio/buckit:latest

# Or a specific version:
docker pull ghcr.io/buckit-io/buckit:RELEASE.2026-05-10T23-30-35Z
```

### Run with Docker

```sh
# Basic single-node server
docker run -p 9000:9000 -p 9001:9001 ghcr.io/buckit-io/buckit:latest server /data --console-address :9001

# With persistent storage
docker run -p 9000:9000 -p 9001:9001 -v ~/buckit-data:/data ghcr.io/buckit-io/buckit:latest server /data --console-address :9001

# With custom credentials
docker run -p 9000:9000 -p 9001:9001 \
  -e MINIO_ROOT_USER=myadmin \
  -e MINIO_ROOT_PASSWORD=mysecretpassword \
  -v ~/buckit-data:/data \
  ghcr.io/buckit-io/buckit:latest server /data --console-address :9001

# Run in background
docker run -d --name buckit -p 9000:9000 -p 9001:9001 -v ~/buckit-data:/data ghcr.io/buckit-io/buckit:latest server /data --console-address :9001

# View logs
docker logs buckit

# Stop
docker stop buckit
```

Access the console at http://localhost:9001 and the S3 API at http://localhost:9000.
Default credentials: `buckitadmin` / `buckitadmin`.

### Linux Packages

DEB (Debian/Ubuntu):

```sh
wget https://github.com/buckit-io/buckit/releases/download/RELEASE.2026-05-10T23-30-35Z/buckit_20260510233035.0.0_amd64.deb
dpkg -i buckit_20260510233035.0.0_amd64.deb
```

RPM (RHEL/Fedora):

```sh
dnf install https://github.com/buckit-io/buckit/releases/download/RELEASE.2026-05-10T23-30-35Z/buckit-20260510233035.0.0-1.x86_64.rpm
```

APK (Alpine):

```sh
wget https://github.com/buckit-io/buckit/releases/download/RELEASE.2026-05-10T23-30-35Z/buckit-20260510233035.0.0-r0.apk
apk add --allow-untrusted buckit-20260510233035.0.0-r0.apk
```

The packages install the binary to `/usr/local/bin/buckit` and include a
systemd service unit at `/lib/systemd/system/buckit.service`.

## Verifying Signatures

Each binary has a `.minisig` signature file. To verify:

```sh
minisign -Vm buckit-linux-amd64.RELEASE.2026-05-10T23-30-35Z \
  -x buckit-linux-amd64.RELEASE.2026-05-10T23-30-35Z.minisig \
  -p buckit.pub
```

The public key (`buckit.pub`) is in the repository root.

Package artifacts also have checksum files in the GitHub Release:

- `buckit_*.deb.sha256sum`
- `buckit-*.rpm.sha256sum`
- `buckit_*.apk.sha256sum`

GitHub Releases contain the immutable versioned artifacts. GitHub Pages
publishes the stable latest filenames such as `buckit`, `buckit.rpm`, and
their matching checksum files.

## Upgrading a Running Server

### Using `mc admin update`

```sh
mc admin update <alias>
```

This automatically discovers the latest release and performs a rolling
update across all nodes in the cluster.

How it works by default:

1. The server fetches `buckit.sha256sum` from GitHub Pages for its platform.
2. It derives the stable sibling binary URL in the same directory.
3. It downloads the stable binary once.
4. It verifies the binary against the checksum and `.minisig`.
5. It inspects the embedded Buckit release tag in the downloaded binary.
6. If the binary is newer than the running server, it performs the rolling update.

Stable update URLs:

```
https://buckit-io.github.io/buckit/server/buckit/release/linux-amd64/buckit.sha256sum
https://buckit-io.github.io/buckit/server/buckit/release/linux-arm64/buckit.sha256sum
https://buckit-io.github.io/buckit/server/buckit/release/windows-amd64/buckit.sha256sum
https://buckit-io.github.io/buckit/server/buckit/release/darwin-arm64/buckit.sha256sum
```

The GitHub Pages branch also publishes the actual stable files that match
those checksums, for example:

```
https://buckit-io.github.io/buckit/server/buckit/release/linux-amd64/buckit
https://buckit-io.github.io/buckit/server/buckit/release/linux-amd64/buckit.minisig
https://buckit-io.github.io/buckit/server/buckit/release/linux-amd64/buckit.rpm
https://buckit-io.github.io/buckit/server/buckit/release/linux-amd64/buckit.rpm.sha256sum
```

`buckit.sha256sum` is a normal checksum file for the stable `buckit` binary,
not a version-pointer file.

For an explicit custom update URL, Buckit uses the simplest contract:

- the provided URL is treated as the binary itself
- the signature is fetched from `<URL>.minisig`
- the checksum is computed from the downloaded binary bytes
- no custom `.sha256sum` sidecar is required

Example:

```sh
mc admin update <alias> https://my-mirror.example.com/buckit/linux-amd64/buckit
```

### Manual upgrade

Download the new binary, replace the old one, restart the service.

## Secrets

These are configured in GitHub Actions (Settings → Secrets):

| Secret | Purpose |
|--------|---------|
| `MINISIGN_PRIVATE_KEY` | Signs release binaries |
| `MINISIGN_PASSWORD` | Passphrase for the signing key |
| `DOCKERHUB_USERNAME` | Pushes images to Docker Hub |
| `DOCKERHUB_TOKEN` | Docker Hub access token |

`GITHUB_TOKEN` is provided automatically by GitHub Actions.

## Infrastructure

| Service | Purpose | URL |
|---------|---------|-----|
| GitHub Releases | Binary/package hosting | https://github.com/buckit-io/buckit/releases |
| GitHub Pages | Stable latest binaries, packages, and checksum files | https://buckit-io.github.io/buckit/ |
| ghcr.io | Docker images | ghcr.io/buckit-io/buckit |
| Docker Hub | Docker images (mirror) | docker.io/buckitio/buckit |

## Workflow File

The release workflow lives at `.github/workflows/release.yml`.