RustFS

RustFS vs Other Object Storage

Staying ahead

Quickstart

• A single-node single-drive (SNSD) deployment is supported only as a standalone local path. It cannot expand in place or be added as a Pool. To move to a multi-drive topology, create a new deployment and migrate data through S3.
• Keep an existing multi-drive Pool's endpoints and Erasure Set width unchanged; expand by appending a new Pool. With ellipsis-based expansion, every Pool argument must contain an ellipsis expression and expand to at least two drive endpoints.
• Single-node multi-drive Pools and multi-node Pools with one drive per node are allowed, subject to valid Erasure Set geometry and EC settings; acceptance does not guarantee host-failure tolerance.

1. One-click Installation (Option 1)

curl -O https://rustfs.com/install_rustfs.sh && bash install_rustfs.sh

1. Docker Quick Start (Option 2)

# Create data and logs directories
mkdir -p data logs

# Change the owner of these directories
chown -R 10001:10001 data logs

# Using latest version
docker run -d -p 9000:9000 -p 9001:9001 -v $(pwd)/data:/data -v $(pwd)/logs:/logs rustfs/rustfs:latest

# Using specific version
docker run -d -p 9000:9000 -p 9001:9001 -v $(pwd)/data:/data -v $(pwd)/logs:/logs rustfs/rustfs:1.0.1

# Create data and logs directories
mkdir -p data logs

# Run the container (podman will automatically set the folders ownership)
podman run -d -p 9000:9000 -p 9001:9001 -v $(pwd)/data:/data:Z,U -v $(pwd)/logs:/logs:Z,U rustfs/rustfs:latest

mkdir -p certs
chown -R 10001:10001 certs

docker compose -f docker-compose-simple.yml up -d

• Ensure every mounted host path is writable by 10001:10001.
• If you enable TLS, ensure the certificate mount for /opt/tls is also readable by 10001:10001.
• If matching host ownership is not practical, run the rustfs service with user: "<host-uid>:<host-gid>" instead.
• docker-compose-simple.yml includes a volume-permission-helper service for named volumes. docker-compose-simple.yml relies on you to prepare bind-mounted host paths in advance.

podman compose -f docker-compose-simple.yml up -d

docker run -d --name rustfs -p 9000:9000 \
  -e RUSTFS_NOTIFY_ENABLE=true \
  -e RUSTFS_NOTIFY_WEBHOOK_ENABLE_PRIMARY=on \
  -e RUSTFS_NOTIFY_WEBHOOK_ENDPOINT_PRIMARY=http://<host-ip>:3020/webhook \
  -e RUSTFS_NOTIFY_WEBHOOK_QUEUE_DIR_PRIMARY=/tmp/rustfs-events \
  -e RUSTFS_OUTBOUND_ALLOW_ORIGINS=http://<host-ip>:3020 \
  rustfs/rustfs:latest

• RUSTFS_NOTIFY_ENABLE=true enables the global notify module switch.
• For ARN arn:rustfs:sqs::primary:webhook, use instance-scoped env vars with _PRIMARY.
• If queue dir is omitted, the official image maps /opt/rustfs/events into the persistent /data volume so it is writable by the runtime user and pending events survive container recreation. Override queue_dir when using another deployment layout.
• RUSTFS_NOTIFY_WEBHOOK_SKIP_TLS_VERIFY_PRIMARY defaults to false; enabling it skips webhook TLS certificate verification, allows MITM attacks, and emits a startup warning. Prefer RUSTFS_NOTIFY_WEBHOOK_CLIENT_CA_PRIMARY for private CAs.
• Since 1.0.0-beta.11, webhook endpoints on private or container networks

3\. Build from Source (Option 3) - Advanced Users

# Build multi-architecture images locally
./docker-buildx.sh

# Build a single-platform image locally
./docker-buildx.sh -p linux/amd64

# Build and push to registry
./docker-buildx.sh --push

# Build specific version
./docker-buildx.sh --release 1.0.1 --push

# Build for custom registry
./docker-buildx.sh --registry your-registry.com --namespace yourname --push

• Multi-architecture builds: linux/amd64, linux/arm64
• Automatic version detection: Uses git tags or commit hashes
• Registry flexibility: Supports Docker Hub, GitHub Container Registry, etc.
• Build optimization: Includes caching and parallel builds

make docker-buildx                    # Build locally
make docker-buildx-push               # Build and push
make docker-buildx-version VERSION=1.0.1  # Build specific version
make help-docker                      # Show all Docker-related commands

4\. Build with Helm Chart (Option 4) - Cloud Native

5\. Nix Flake (Option 5)

# Run directly without installing
nix run github:rustfs/rustfs

# Build the binary
nix build github:rustfs/rustfs
./result/bin/rustfs --help

# Or from a local checkout
nix build
nix run

imports = [ inputs.rustfs.nixosModules.rustfs ];

services.rustfs = {
  enable = true;
  accessKeyFile = "/run/secrets/rustfs-access-key";
  secretKeyFile = "/run/secrets/rustfs-secret-key";
  volumes = [ "/var/lib/rustfs" ];
};

6\. X-CMD (Option 6)

# Run directly without installing
x rustfs

# Download the binary and install it to the global environment
x env use rustfs
rustfs --help

Accessing RustFS

1. Access the Console: Open your web browser and navigate to http://localhost:9001 to access the RustFS console.

- Default credentials: `rustfsadmin` / `rustfsadmin`

1. Create a Bucket: Use the console to create a new bucket for your objects.
2. Upload Objects: You can upload files directly through the console or use S3-compatible APIs/clients to interact with your RustFS instance.

OIDC Roles Claim (Microsoft Entra ID)

RUSTFS_IDENTITY_OPENID_ENABLE=on
RUSTFS_IDENTITY_OPENID_CONFIG_URL="https://login.microsoftonline.com/<tenant-id>/v2.0/.well-known/openid-configuration"
RUSTFS_IDENTITY_OPENID_CLIENT_ID="<client-id>"
RUSTFS_IDENTITY_OPENID_CLIENT_SECRET="<client-secret>"
RUSTFS_IDENTITY_OPENID_SCOPES="openid,profile,email"
RUSTFS_IDENTITY_OPENID_GROUPS_CLAIM="groups"
RUSTFS_IDENTITY_OPENID_ROLES_CLAIM="roles"

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["admin:*"],
      "Resource": ["arn:aws:s3:::*"],
      "Condition": {
        "ForAnyValue:StringEquals": {
          "jwt:roles": ["RustFS.ConsoleAdmin"]
        }
      }
    }
  ]
}

Documentation

Getting Help

• Check the FAQ for common issues and solutions.
• Join our GitHub Discussions to ask questions and share your experiences.
• Open an issue on our GitHub Issues page for bug reports or feature requests.

Links

• Documentation - The manual you should read
• Changelog - What we broke and fixed
• GitHub Discussions - Where the community lives
• Discord - Chat with the RustFS community

Contact

• Bugs: GitHub Issues
• Business: [email protected]
• Jobs: [email protected]
• General Discussion: GitHub Discussions
• Contributing: CONTRIBUTING.md

Contributors

Star History

License