install-binary.sh handles Linux and macOS in one script and is published
as of the latest release, so the two platform lines collapse into one.
The old per-platform URLs still work, but there is no reason to send new
readers to them.
* docs: retitle the Docker section to match what it does
The section was called "Build Docker Image" but was almost entirely
about running the published one, so anyone scanning for how to try
Buckit in a container skipped past it.
Retitle to "Run with Docker", lead with the run commands, and demote
image building to a closing note. Also name both registries and the
advice to pin a tag in production.
* docs: make Quickstart reach a running server in one command
Quickstart opened with `make build`, so the first runnable thing in the
README required installing Go and compiling. Lead with the published
container image instead.
Fold Distributed Server Mode in as a subsection so the single-node and
cluster commands sit together. The cluster one-liner is the more
striking of the two and was previously buried under prose, split across
continuation lines, and immediately followed by advice to use bm web
instead. It now stands on its own line with an explanation of what it
describes.
* docs: quickstart without requiring Docker
Leading with a container image assumed a runtime the reader may not
have. The binary installer shipped in the last release needs neither a
toolchain nor Docker, so use that instead and keep the container path as
one of the alternatives listed beneath it.
* docs: split quickstart into download and run steps
* docs: walk the quickstart through to an uploaded file
The quickstart stopped at a running process, which is not the thing a
reader is trying to confirm. Continue through signing in to the console
and uploading an object with bm, so the first session ends with data in
object storage rather than a server listening on a port.
* docs: tighten the quickstart and end it in the console
Cut the throat-clearing: the "no toolchain required" claim, the
description of what the installer does, and the pointers to other
install methods, which are one heading away.
Swap the last two steps. Creating a bucket and uploading a file, then
opening the console to find them there, gives the sequence a payoff. The
previous order treated the console and the CLI as interchangeable
alternatives, which ended the quickstart on a shrug.
* docs: give quickstart steps their own headings
Bold-inline step labels ran into the text that followed them, so the
four steps read as one block. Promote them to h3 so each gets real
separation and an anchor, and move the platform variants and the bm
install note into the code blocks as comments, where a reader can copy
the line that applies to them instead of reading a sentence about it.
The cluster one-liner becomes its own section rather than a fifth
sibling heading under Quickstart, where it read as step 5.
* docs: restore the learning-purposes note on the quickstart
* docs: reword the quickstart note
* docs: state what the quickstart walks through
* docs: put the quickstart note above the intro line
* docs: point the quickstart note at the guided deployment wizard
* docs: comment each command in the quickstart upload step
* docs: note the PATH line is conditional
* docs: name the data directory in the quickstart
* docs: name the CLI in the step 3 heading
* docs: say web browser rather than console in step 4
* docs: point at the Object Browser menu in step 4
* docs: give the Windows bm install its own line
* docs: comment out the Windows bm install so the block pastes cleanly
* docs: restore the Distributed Server Mode heading
* docs: restore the original Distributed Server Mode section
* docs: keep the rewritten distributed section under its original heading
* docs: restore Distributed Server Mode to its original form
* docs: point distributed deployments at the guided wizard
* docs: simplify what the wizard handles
* docs: simplify the install section blurbs
* docs: drop the Linux install subsections from Install Buckit
Installing and deploying for real takes more than a one-line curl, and
the Deployment Guide covers it properly. The quickstart already shows
the download command for anyone who just wants to try the server, so
these two sections offered a third telling of the same thing at a level
of detail that suits neither audience.
Leaves Install Buckit as a pointer to the guide, plus building from
source, which is the part only this repository can document.
* docs: contrast the deployment guide with building from source
* docs: promote Build From Source to a top-level section
* docs: drop the build commands that do not work
`go install github.com/buckit-io/buckit@latest` cannot succeed. Go
refuses `pkg@version` installs for any module carrying a replace
directive, and go.mod:7 has one for go-openapi/testify. The line was
inherited from MinIO's README, where it works because their go.mod has
none. Running it here fails outright.
The manual `go build -tags kqueue -trimpath --ldflags ...` line was the
Makefile's build target spelled out, so it only offered a way to get the
invocation subtly wrong.
Leaves the one path that works, verified from a clean clone.
* docs: restore go install now that it works
Removing it was correct at the time: the go.mod replace directive made
`go install pkg@version` fail outright. That directive is gone, and the
command has been verified against the published module.
Note the version caveat -- go install skips the Makefile's gen-ldflags
step, so the binary cannot report which release it came from.
* docs: use the Docker Hub image in the run commands
Docker Hub is Docker's default registry, so buckitio/buckit needs no
prefix at all, and it is where most people expect to find an image. This
also matches the compose example in the migration blog post.
Name both registries explicitly in the note beneath, since GHCR is not
subject to Docker Hub's anonymous pull limits and is the better choice
from CI.
* docs: drop the custom-image aside from Run with Docker
* docs: name the bm section as the CLI
* docs: add a Buckit Manager Web screenshot
The section described a web UI without showing it. Use the cluster view
from the website's media assets, which covers four of the five things the
section lists: cluster health, nodes, pools and drives, and host
operations.
Cropped off the decorative video-poster frame and the burned-in caption
so it reads as a screenshot rather than a video thumbnail. Placed
centred under the intro, matching the console GIF at the top of the file.
* docs: fold the bm install blocks into one
Two blocks with prose labels became one with per-command comments,
matching how the quickstart presents the same install. The Windows line
is commented out so the block still pastes cleanly on Linux and macOS,
where the trailing `bm --help` runs either way.
* docs: add the PATH line the bm install block was missing
`bm --help` fails with "bm: not found" straight after install: bm lands
in ~/.local/bin and its installer only prints a PATH hint rather than
applying one. The two blocks this replaced had the same gap.
Verified by pasting the block verbatim with nothing added.
go.mod pinned go-openapi/testify/v2 down to v2.0.2 because newer
releases removed assert/yaml, which go-openapi's own test dependencies
still imported. The pin worked, but a replace directive makes
go install github.com/buckit-io/buckit@latest
fail outright: Go refuses pkg@version installs for any module carrying
one. Building from a clone was the only way in.
The stale module was not testify itself but its companion,
go-openapi/testify/enable/yaml, still at v2.0.2 while testify had moved
to v2.4.1. That older enable/yaml is what imported the removed package.
Upgrading it to v2.6.0 lets both move together, and the incompatibility
disappears without pinning anything.
Neither replace nor exclude remains, so pkg@version installs work.
install-linux-binary.sh and install-mac.sh were 443 lines that differed
in three places: the OS check and architecture allowlist, the platform
token in the pointer URL and asset name, and clearing the macOS
quarantine attribute. The other ~190 lines were identical.
That duplication already cost something. Hardening the installers meant
applying five fixes twice, by hand, in parallel -- pin-bypass path
traversal, pipeline masking, digest normalisation, directory
destination, and the cross-origin digest check. The next fix would have
had the same shape, and eventually one would land in only one file.
Merge them into install-binary.sh, which detects Linux or macOS and
validates the architecture against what is published for that platform:
Linux ships amd64 and arm64, macOS ships Apple Silicon only.
The release workflow publishes it under the old names as well, so URLs
already in the wild, in the docs, and in the blog post keep working and
pick up the merged behaviour on every release. Nothing needs to change
on the reader's side, and there is no window where a documented command
404s.
Two benign consequences: install-mac.sh now also works on Linux and
install-linux-binary.sh on macOS, and error messages self-identify as
install-binary.sh whichever URL was fetched.
* docs: point MinIO users at the migration path from the README
Someone arriving from the discontinued MinIO project has one question
before anything else: how much work is switching? The README answered
everything except that.
Add a callout directly under the intro, above the console screenshot,
stating that Buckit is a drop-in replacement and linking to the blog
post and the migration guide. Also list the new post under Learn More,
which only had the original fork announcement.
* docs: tighten the MinIO callout wording
* docs: drop the second link from the MinIO callout
* docs: keep the migration post to the callout only
* docs: move the MinIO callout above Quickstart
* docs: move the MinIO callout above What Buckit Provides
* docs: drop the redundant sentence from the MinIO callout
* docs: rewrite What Buckit Provides around technical capability
Three of the six bullets described the console, CLI, and web manager,
which the console recording directly above already demonstrates. Nothing
described replication, deployment shape, or the read path.
Replace them with capability statements: the S3 surface, single-binary
deployment, the scaling range, site and bucket replication, one bullet
covering the tooling, and the single-trip GET path that upstream does
not have.
* docs: trim the feature descriptions
* docs: clarify the scaling bullet
* docs: keep the plain feature wording, add leads and the missing items
* docs: fold the admin tools into an operations toolkit item
* docs: lead the replication item with what it buys you
* docs: shorten the replication item to the DR case
* docs: replication supports more than one remote site
* docs: simplify the replication item
* docs: note the browser console is the end-user surface
* docs: lead with S3-compatible object storage
* docs: group single binary with the operational items
* docs: name homelabs in the standalone item
* docs: describe the console as self-service
install-linux-binary.sh was adapted from install-mac.sh and inherited
several weaknesses from it. Fix them in all three installers so the
platforms behave consistently.
- Validate the release tag on the pinned path as well as the resolved
one. BUCKIT_VERSION previously bypassed the RELEASE.* guard entirely,
so a value like ../../evil reached the download URL as path traversal.
Both paths now share one check, and it requires a non-empty suffix and
a conservative character set, rejecting '/', whitespace, control
characters, and URL delimiters.
- Require the gh-pages pointer filename to actually carry the buckit.
prefix. Stripping it with ${name#buckit.} silently accepted a payload
that never had it.
- Fetch the published checksum into a variable before parsing it. Piping
the fetch straight into awk hid a failed transfer behind awk's exit
status; a partial response with a complete leading token could pass.
The hash utilities are now invoked outside a pipeline for the same
reason.
- Normalise digests to lowercase and require exactly 64 hex characters,
so an uppercase digest cannot cause a spurious mismatch and a truncated
record cannot be compared as if it were valid.
- Refuse to run when the destination is a directory. mv and Move-Item
both place the temp file inside it, after which the installer reported
success while leaving nothing runnable at the path it printed.
Also cross-check the pointer digest against the release-host digest on
macOS and Windows, matching the new Linux script.
install-linux.sh downloads a native package and registers a systemd
service, which is the wrong shape for deployments that run the server
binary directly -- a hand-run process, a non-systemd supervisor, or a
MinIO deployment being migrated in place.
Add a Linux counterpart to install-mac.sh that fetches only the binary:
resolve the current release from the gh-pages pointer, download the
matching asset, verify its SHA-256, chmod it, and leave ./buckit in the
working directory. It does not touch PATH and does not install a service.
The checksum is verified against both the release-host .sha256sum and the
digest published in the gh-pages pointer, and the two must agree. The
binary and its adjacent checksum share an origin, so that digest alone
only proves the transfer was not corrupted; the pointer is served from a
different origin and turns the check into something an attacker must
defeat in two places. A pinned BUCKIT_VERSION skips the cross-check,
since the pointer only ever describes the latest release.
Publish the script to gh-pages alongside the others, and advertise it in
the README and the generated release-notes install table.
abuckit