Deploy Buckit on macOS

Review Checklists

Ensure you have reviewed our published Hardware, Software, and Security checklists before attempting this procedure.

Erasure Coding Parity

Buckit automatically determines the default erasure coding configuration for the cluster based on the total number of nodes and drives in the topology. You can configure the per-object parity setting when you set up the cluster or let Buckit select the default (EC:4 for production-grade clusters).

Parity controls the relationship between object availability and storage on disk. Use the Erasure Code Calculator for guidance in selecting the appropriate erasure code parity level for your cluster.

While you can change erasure parity settings at any time, objects written with a given parity do not automatically update to the new parity settings.

1. Download the Buckit Binary

Use the following commands to download, verify, and install the latest stable Buckit binary for macOS:

curl -fsSL https://buckit-io.github.io/buckit/install-binary.sh | sh
chmod +x ./buckit
sudo mv ./buckit /usr/local/bin/

2. Enable TLS Connectivity

You can skip this step to deploy without TLS enabled. Buckit strongly recommends against non-TLS deployments outside of early development.

Create or provide Transport Layer Security (TLS) certificates to Buckit to automatically enable HTTPS-secured connections between the server and clients.

Place the certificates in a dedicated directory:

mkdir -p /opt/buckit/certs

cp private.key /opt/buckit/certs
cp public.crt /opt/buckit/certs

Buckit verifies client certificates against the OS list of trusted Certificate Authorities. To enable verification of third-party or internally-signed certificates, place the CA file in the /opt/buckit/certs/CAs folder. The CA file should include the full chain of trust from leaf to root to ensure successful verification.

For more specific guidance on configuring Buckit for TLS, including multi-domain support via Server Name Indication (SNI), see Network Encryption (TLS).

openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
  -keyout private.key \
  -out public.crt \
  -subj "/CN=localhost" \
  -addext "subjectAltName = DNS:localhost,DNS:*.example.net"

3. Create the Buckit Environment File

Create an environment file at /etc/default/minio. The Buckit server uses this file as the source of all environment variables used by Buckit.

Modify the example to reflect your deployment topology.

# Set the volumes Buckit uses at startup
# The command uses Buckit expansion notation {x...y} to denote a
# sequential series.
#
# The following specifies a single host with 4 drives at the specified location
#
# The command includes the port that the Buckit server listens on
# (default 9000).
# If you run without TLS, change https -> http

MINIO_VOLUMES="https://buckit1.example.net:9000/mnt/drive{1...4}/buckit"

# Set all Buckit server command-line options
#
# The following explicitly sets the Buckit Console listen address to
# port 9001 on all network interfaces.
# The default behavior is dynamic port selection.

MINIO_OPTS="--console-address :9001 --certs-dir /opt/buckit/certs"

# Set the root username.
# This user has unrestricted permissions to perform S3 and
# administrative API operations on any resource in the deployment.
#
# Defer to your organizations requirements for superadmin user name.

MINIO_ROOT_USER=buckitadmin

# Set the root password
#
# Use a long, random, unique string that meets your organizations
# requirements for passwords.

MINIO_ROOT_PASSWORD=buckit-secret-key-CHANGE-ME

# Set the volume Buckit uses at startup
#
# The following specifies the drive or folder path

MINIO_VOLUMES="/mnt/drive1/buckit"

# Set all Buckit server command-line options
#
# The following explicitly sets the Buckit Console listen address to
# port 9001 on all network interfaces.
# The default behavior is dynamic port selection.

MINIO_OPTS="--console-address :9001 --certs-dir /opt/buckit/certs"

# Set the root username.
# This user has unrestricted permissions to perform S3 and
# administrative API operations on any resource in the deployment.
#
# Defer to your organizations requirements for superadmin user name.

MINIO_ROOT_USER=buckitadmin

# Set the root password
#
# Use a long, random, unique string that meets your organizations
# requirements for passwords.

MINIO_ROOT_PASSWORD=buckit-secret-key-CHANGE-ME

Specify any other environment variables or server command-line options as required by your deployment.

4. Start the Buckit Server

The following command starts the Buckit Server attached to the current terminal/shell window:

. /etc/default/minio
./buckit server $MINIO_OPTS $MINIO_VOLUMES

The command output resembles the following:

INFO: Formatting 1st pool, 1 set(s), 1 drives per set.
Buckit Object Storage Server
License: GNU AGPLv3 - https://www.gnu.org/licenses/agpl-3.0.html
Version: RELEASE.2026-06-18T00-00-00Z (go1.26.2 darwin/arm64)

API: https://buckit1.example.net:9000 https://203.0.113.10:9000 https://127.0.0.1:9000
WebUI: https://buckit1.example.net:9001 https://203.0.113.10:9001 https://127.0.0.1:9001
Docs: https://buckit-io.github.io/docs

The API block lists the network interfaces and port on which clients can access the Buckit S3 API. The WebUI block lists the network interfaces and port on which clients can access the Buckit Web Console.

To run the buckit server process in the background or as a daemon, defer to your macOS documentation for best practices and procedures.

5. Connect to the Deployment

bm alias set mybuckit https://buckit1.example.net:9000 USERNAME PASSWORD

bm --insecure alias set mybuckit https://buckit1.example.net:9000 USERNAME PASSWORD