OtterIO is a high-performance, S3-compatible object storage server. It is suitable for building infrastructure for machine learning, analytics, backup, and general application data workloads.

This README covers running OtterIO on bare metal, Docker, and from source. For deeper topics (erasure coding, distributed mode, KMS, replication, etc.) see the docs/ folder.

[!IMPORTANT] OtterIO is an independent, community-maintained fork of the upstream Apache-licensed MinIO codebase. It is not affiliated with, endorsed by, or sponsored by MinIO, Inc. See Trademark & Upstream Notice and the Security Advisory before deploying.

What is OtterIO

OtterIO is a customized fork of the last Apache License 2.0 release of MinIO (≈ RELEASE.2021-04-22T15-44-28Z). It differs from upstream in the following ways:

• HTTP layer — request router built on gofiber/fiber/v3 instead of gorilla/mux.
• Bucket notification targets — only elasticsearch, mysql, postgresql, redis, and webhook are supported. The message-queue targets (Kafka, NATS, NATS Streaming, NSQ, AMQP, MQTT) have been removed.
• Gateways — only nas and s3 remain. The azure, gcs, and hdfs gateways have been removed.
• Toolchain — requires Go 1.26 or newer (see go.mod).
• Container images — published at soulteary/otterio (Docker Hub) and ghcr.io/soulteary/otterio (GitHub Container Registry).

OtterIO continues to be distributed under the Apache License, Version 2.0. All original copyright notices are retained — see NOTICE.

Quick Start

Run a single-node OtterIO instance with Docker:

docker run -p 9000:9000 -p 9001:9001 \
  -v /mnt/data:/data \
  soulteary/otterio:latest server /data --console-address ":9001"

Default root credentials are otterioadmin:otterioadmin. Once running, see Verify to connect via the web console or mc.

[!NOTE] Standalone OtterIO servers are best suited for development and evaluation. Production deployments should run distributed mode with Erasure Coding enabled — at least 4 drives per server. See docs/erasure/README.md and docs/distributed/README.md.

Installation

Docker

OtterIO publishes container images to both Docker Hub and the GitHub Container Registry:

# Docker Hub
docker pull soulteary/otterio:latest

# GitHub Container Registry
docker pull ghcr.io/soulteary/otterio:latest

Run a standalone server with an ephemeral volume:

docker run -p 9000:9000 soulteary/otterio:latest server /data

For persistent storage, map a host directory to /data:

docker run -p 9000:9000 -v /mnt/data:/data soulteary/otterio:latest server /data

macOS

Homebrew (recommended)

brew install otterio/stable/otterio
otterio server /data

If you previously installed OtterIO from a different tap, reinstall from the official tap:

brew uninstall otterio
brew install otterio/stable/otterio

Binary

Pre-built macOS binaries are published on GitHub Releases. Download the appropriate archive, then:

chmod +x otterio
./otterio server /data

Linux

Pre-built Linux binaries are published on GitHub Releases. Download the asset that matches your architecture and run it as otterio:

chmod +x otterio
./otterio server /data

The release pipeline (.goreleaser.yml) currently produces Linux binaries for the following architectures:

.deb and .rpm packages are also produced for the supported architectures.

Windows

Pre-built Windows binaries (amd64) are published on GitHub Releases. After downloading otterio.exe, run it from the directory where it lives, or add that directory to the system PATH:

otterio.exe server D:\

FreeBSD

OtterIO does not currently provide an official FreeBSD package. Build from source on FreeBSD using the Build from Source instructions below.

Build from Source

Source builds are intended for developers and advanced users. Make sure you have a working Go toolchain (Go 1.26 or newer — see How to install Go).

git clone https://github.com/soulteary/otterio.git
cd otterio
make build
./otterio server /data

[!WARNING] We strongly recommend against running compiled-from-source binaries in production. Use a tagged release for production deployments.

Configuration

Run S3 and Web Console on separate ports

By default the web console and the S3 API share the listener bound to --address. OtterIO can serve the web UI and admin API on a dedicated port so that reverse proxies, firewalls, and network policies can govern S3 traffic and console traffic independently.

Enable the dedicated console listener via the --console-address flag or the OTTERIO_BROWSER_ADDRESS environment variable:

# CLI flag
otterio server --address ":9000" --console-address ":9001" /data

# Environment variable (equivalent)
export OTTERIO_BROWSER_ADDRESS=":9001"
otterio server --address ":9000" /data

When the dedicated console listener is enabled:

• :9000 only serves the S3 API, STS, health, and metrics. Browser requests are no longer redirected to the web UI.
• :9001 serves the web console (/otterio/) and the admin API (/otterio/admin/v3/*).
• The console port must differ from the S3 port; otherwise startup fails fast.
• Ctrl+C / SIGTERM shuts down both listeners gracefully.

[!NOTE] The admin API (used by mc admin ...) is served from the console port in this mode. Configure your mc alias to point at the console URL when issuing admin commands. Regular S3 operations (mc cp, mc ls, etc.) continue to use the S3 port.

If --console-address is not provided, both surfaces share a single port (the original behaviour).

Dedicated TLS certificates for the console listener

When you split listeners, you can also point the console at its own TLS keypair so the S3 API and the web console can use different certificates (e.g. an internal CA-signed cert for :9000 and a public cert for :9001). Use --console-certs-dir or OTTERIO_BROWSER_CERTS_DIR:

otterio server \
  --address ":9000" \
  --console-address ":9001" \
  --certs-dir /etc/otterio/certs/s3 \
  --console-certs-dir /etc/otterio/certs/console \
  /data

The directory pointed to by --console-certs-dir must contain public.crt and private.key, the same layout used by --certs-dir. Notes:

• --console-certs-dir requires --console-address; otherwise startup fails fast.
• If --console-certs-dir is not set, the console listener reuses the certificates loaded from --certs-dir (the legacy behaviour).
• The S3 listener always uses --certs-dir; only the console listener honours --console-certs-dir.
• Both keypairs are watched and hot-reloaded by the same certificate manager used for --certs-dir.

Firewall

By default OtterIO listens on port 9000 for S3 traffic (and 9001 if the console listener is split out). Some platforms block these ports until you explicitly open them.

ufw allow 9000

# Range
ufw allow 9000:9010/tcp

firewall-cmd --get-active-zones
firewall-cmd --zone=public --add-port=9000/tcp --permanent
firewall-cmd --reload

iptables -A INPUT -p tcp --dport 9000 -j ACCEPT
service iptables restart

# Range
iptables -A INPUT -p tcp --dport 9000:9010 -j ACCEPT
service iptables restart

Pre-existing data

When deployed on a single drive, OtterIO server lets clients access any pre-existing data in the data directory. For example, if OtterIO is started with otterio server /mnt/data, any pre-existing data in /mnt/data is accessible to clients. The same applies to all gateway backends.

Verify

Once OtterIO is running, the deployment uses default root credentials otterioadmin:otterioadmin (override via OTTERIO_ROOT_USER / OTTERIO_ROOT_PASSWORD environment variables in production).

Web console

Point a browser at http://127.0.0.1:9000 (or the console port if you split listeners). Log in with the root credentials to create buckets, upload objects, and browse contents.

mc client

mc is a modern command-line client that speaks S3 and local filesystem URIs (similar to ls, cp, mirror, diff, etc.). Configure an alias against your OtterIO endpoint:

mc alias set local http://127.0.0.1:9000 otterioadmin otterioadmin
mc mb local/test-bucket
mc cp ./somefile local/test-bucket/
mc ls local/test-bucket/

OtterIO is wire-compatible with the AWS S3 API, so aws-cli, s3cmd, and the various AWS SDKs all work out of the box — point them at your OtterIO endpoint with the root credentials (or an IAM-issued access key).

Further Reading

Project documentation (this repository)

• Erasure Coding
• Distributed mode
• Multi-user / IAM
• STS — temporary credentials
• TLS
• KMS
• Bucket notifications
• Bucket replication
• Bucket lifecycle / retention / versioning / quota
• Metrics & Prometheus
• Logging
• Docker · Orchestration
• Security advisories backlog
• LDAP DN normalisation migration
• Limits

Upstream references (third-party)

The links below point to the original upstream MinIO project's documentation. They remain useful as background reading on S3-compatible workflows, but they describe upstream MinIO behaviour and are not maintained by OtterIO:

• Erasure Code Quickstart Guide (upstream)
• mc Client Quickstart (upstream)
• aws-cli with MinIO (upstream)
• s3cmd with MinIO (upstream)
• Go SDK Quickstart (upstream)

Contributing

Contributions are welcome via the project repository at https://github.com/soulteary/otterio. For coding conventions inherited from the upstream baseline, see the original Contributor's Guide.

Security Advisory

Trademark & Upstream Notice

License

OtterIO is governed by the Apache License, Version 2.0, found at LICENSE. Attribution and third-party notices are listed in NOTICE.

"MinIO" is a trademark of MinIO, Inc. OtterIO is not affiliated with, endorsed by, or sponsored by MinIO, Inc.