MinIO: Getting started

How to begin using MinIO for S3-compatible object storage

👋 Welcome to the Stackhero documentation!

Stackhero offers a ready-to-use MinIO Object Storage solution that provides a host of benefits, including:

  • Unlimited transfers.
  • Simple, predictive, and transparent pricing.
  • Customisable domain name secured with HTTPS (for example, https://object-storage.your-company.com).
  • Effortless updates with just a click.
  • Optimal performance and robust security powered by a private and dedicated VM.
  • Available in 🇪🇺 Europe and 🇺🇸 USA.

Save time and simplify your life: it only takes 5 minutes to try Stackhero's MinIO Object Storage hosting solution!

MinIO is an object storage service that implements the Amazon S3 protocol. Any Amazon S3-compatible client can connect to MinIO and interact seamlessly with your object storage. An Amazon S3 client library is available for nearly every major programming language, including Ruby, Node.js, Java, Python, Clojure, and Erlang.

We recommend using the MinIO SDKs to connect to your object storage. You can find a complete list of available SDKs in the MinIO official documentation.

Alternatively, you can use the MinIO CLI. It is especially useful for managing large files directly from your terminal. Detailed guidance on using the MinIO CLI is available in the MinIO CLI official documentation.

Using the MinIO CLI

Your Stackhero for MinIO instance includes the MinIO Console web UI by default. For more advanced tasks, you may choose to use the MinIO CLI.

The simplest way to try the MinIO CLI is to run its Docker container. Follow these steps:

  1. Start the container:

    docker run -it --entrypoint=/bin/sh minio/mc

  2. Inside the container, add your server using the following command (replace the placeholder values accordingly):

    mc alias set minio https://<XXXXXX>.stackhero-network.com <ROOT_ACCESS_KEY> <MINIO_ROOT_SECRET_KEY>

  3. Create a bucket named "test" to verify the setup:

    mc mb minio/test

  4. List your buckets:

    mc ls minio

You can view additional MinIO CLI commands by running mc --help.

Connecting Ruby to MinIO

First, install the AWS SDK gem:

gem install aws-sdk
bundle install

Below is a simple example demonstrating how to interact with MinIO using the AWS SDK in Ruby:

require 'aws-sdk'

Aws.config.update(
  endpoint: 'https://<XXXXXX>.stackhero-network.com',
  access_key_id: 'YOUR_ACCESS_KEY',
  secret_access_key: 'YOUR_SECRET_KEY',
  force_path_style: true,
  region: 'us-east-1'
)

rubys3_client = Aws::S3::Client.new

# put_object operation
rubys3_client.put_object(
  key: 'testobject',
  body: 'Hello from MinIO!',
  bucket: 'testbucket',
  content_type: 'text/plain'
)

# get_object operation
rubys3_client.get_object(
  bucket: 'testbucket',
  key: 'testobject',
  response_target: 'download_testobject'
)

print "Downloaded 'testobject' as 'download_testobject'."

For more details, check out the MinIO Ruby documentation.

Connecting Python to MinIO

There are two primary ways to connect Python applications to MinIO.

Connecting to MinIO with the AWS SDK (boto)

First, install the AWS SDK package (boto3):

pip install boto3
pip freeze > requirements.txt

The following example demonstrates how to connect to MinIO using boto3:

#!/usr/bin/env python
import os
import boto3
from botocore.client import Config

s3 = boto3.resource('s3',
                    endpoint_url='https://<XXXXXX>.stackhero-network.com',
                    aws_access_key_id='YOUR_ACCESS_KEY',
                    aws_secret_access_key='YOUR_SECRET_KEY',
                    config=Config(signature_version='s3v4'),
                    region_name='us-east-1')

# Upload a local file '/home/john/piano.mp3' to bucket 'songs' with the object name 'piano.mp3'
s3.Bucket('songs').upload_file('/home/john/piano.mp3', 'piano.mp3')

# Download the object 'piano.mp3' from bucket 'songs' and save it locally as '/tmp/classical.mp3'
s3.Bucket('songs').download_file('piano.mp3', '/tmp/classical.mp3')

print("'piano.mp3' downloaded as 'classical.mp3'.")

More details are available in the MinIO Python documentation.

Connecting to MinIO with the MinIO SDK

Alternatively, you can use the MinIO SDK for Python. First, install the MinIO package:

pip install minio
pip freeze > requirements.txt

Below is an example showing how to connect to MinIO using the MinIO SDK:

#!/usr/bin/env python
from minio import Minio
from minio.error import S3Error

def main():
  # Create a client for your MinIO server using your access and secret keys
  client = Minio(
    endpoint='<XXXXXX>.stackhero-network.com:443',
    secure=True,
    access_key='YOUR_ACCESS_KEY',
    secret_key='YOUR_SECRET_KEY'
  )

  # Check if the bucket 'asiatrip' exists, and create it if it does not
  found = client.bucket_exists("asiatrip")
  if not found:
    client.make_bucket("asiatrip")
  else:
    print("Bucket 'asiatrip' already exists")

  # Upload '/home/user/Photos/asiaphotos.zip' as 'asiaphotos-2015.zip' to the bucket 'asiatrip'
  client.fput_object(
    "asiatrip", "asiaphotos-2015.zip", "/home/user/Photos/asiaphotos.zip"
  )
  print(
    "'/home/user/Photos/asiaphotos.zip' has been successfully uploaded as "
    "object 'asiaphotos-2015.zip' to bucket 'asiatrip'."
  )


if __name__ == "__main__":
  try:
    main()
  except S3Error as exc:
    print("An error occurred.", exc)

For further guidance, see the MinIO Python SDK documentation.

Connecting PHP to MinIO

To connect PHP to MinIO, first install the AWS SDK for PHP package:

composer require aws/aws-sdk-php

The example below shows how to connect to MinIO from PHP using the AWS SDK:

<?php

// Include the SDK using the Composer autoloader
date_default_timezone_set('America/Los_Angeles');
require 'vendor/autoload.php';

$s3 = new Aws\S3\S3Client([
  'version' => 'latest',
  'region'  => 'us-east-1',
  'endpoint' => 'https://<XXXXXX>.stackhero-network.com',
  'use_path_style_endpoint' => true,
  'credentials' => [
    'key'    => 'YOUR_ACCESS_KEY',
    'secret' => 'YOUR_SECRET_KEY'
  ],
]);

// Send a PutObject request and obtain the result.
$insert = $s3->putObject([
  'Bucket' => 'testbucket',
  'Key'    => 'testkey',
  'Body'   => 'Hello from MinIO!'
]);

// Download the contents of the object.
$retrieve = $s3->getObject([
  'Bucket' => 'testbucket',
  'Key'    => 'testkey',
  'SaveAs' => 'testkey_local'
]);

// Print the body of the retrieved result.
echo $retrieve['Body'];

Connecting Go to MinIO

There are two options for connecting Go applications to MinIO.

Connecting to MinIO with the AWS SDK

First, install the AWS SDK packages for Go:

go get github.com/aws/aws-sdk-go-v2
go get github.com/aws/aws-sdk-go-v2/config

Below is an example of how to connect to MinIO from Go using the AWS SDK:

package main

import (
  "fmt"
  "os"
  "strings"

  "github.com/aws/aws-sdk-go/aws"
  "github.com/aws/aws-sdk-go/aws/credentials"
  "github.com/aws/aws-sdk-go/aws/session"
  "github.com/aws/aws-sdk-go/service/s3"
  "github.com/aws/aws-sdk-go/service/s3/s3manager"
)

func main() {
  bucket := aws.String("newbucket")
  key := aws.String("testobject")

  // Configure to use the MinIO server
  s3Config := &aws.Config{
    Credentials:      credentials.NewStaticCredentials("YOUR_ACCESS_KEY", "YOUR_SECRET_KEY", ""),
    Endpoint:         aws.String("https://<XXXXXX>.stackhero-network.com"),
    Region:           aws.String("us-east-1"),
    DisableSSL:       aws.Bool(false),
    S3ForcePathStyle: aws.Bool(true),
  }
  newSession := session.New(s3Config)

  s3Client := s3.New(newSession)

  cparams := &s3.CreateBucketInput{
    Bucket: bucket,
  }

  // Create a new bucket
  _, err := s3Client.CreateBucket(cparams)
  if err != nil {
    fmt.Println(err.Error())
    return
  }

  // Upload a new object with the string "Hello from MinIO!"
  _, err = s3Client.PutObject(&s3.PutObjectInput{
    Body:   strings.NewReader("Hello from MinIO!"),
    Bucket: bucket,
    Key:    key,
  })
  if err != nil {
    fmt.Printf("Failed to upload data to %s/%s, %s\n", *bucket, *key, err.Error())
    return
  }
  fmt.Printf("Successfully created bucket %s and uploaded data with key %s\n", *bucket, *key)

  // Retrieve our object and store it locally
  file, err := os.Create("testobject_local")
  if err != nil {
    fmt.Println("Failed to create file", err)
    return
  }
  defer file.Close()

  downloader := s3manager.NewDownloader(newSession)
  numBytes, err := downloader.Download(file,
    &s3.GetObjectInput{
      Bucket: bucket,
      Key:    key,
    })
  if err != nil {
    fmt.Println("Failed to download file", err)
    return
  }
  fmt.Println("Downloaded file", file.Name(), numBytes, "bytes")
}

For additional reading, visit the MinIO Go documentation.

Connecting to MinIO with the MinIO SDK

To use the MinIO SDK for Go, install the following package:

GO111MODULE=on go get github.com/minio/minio-go/v7

Below is an example showing how to connect to MinIO using the MinIO SDK for Go:

package main

import (
  "log"

  "github.com/minio/minio-go/v7"
  "github.com/minio/minio-go/v7/pkg/credentials"
)

func main() {
  endpoint := "<XXXXXX>.stackhero-network.com"
  accessKeyID := "YOUR_ACCESS_KEY"
  secretAccessKey := "YOUR_SECRET_KEY"
  useSSL := true

  // Initialize the MinIO client
  minioClient, err := minio.New(endpoint, &minio.Options{
    Creds:  credentials.NewStaticV4(accessKeyID, secretAccessKey, ""),
    Secure: useSSL,
  })
  if err != nil {
    log.Fatalln(err)
  }

  log.Printf("%#v\n", minioClient) // minioClient is now set up
}

For more information, please see the MinIO Go SDK documentation.

Connecting Node.js to MinIO

There are two methods to connect Node.js applications to MinIO.

Connecting to MinIO with the AWS SDK

First, install the AWS SDK package for Node.js:

npm install aws-sdk

Below is an example that shows how to connect to MinIO using the AWS SDK:

const process = require('process');
const AWS = require('aws-sdk');

const s3 = new AWS.S3({
  accessKeyId: 'YOUR_ACCESS_KEY',
  secretAccessKey: 'YOUR_SECRET_KEY',
  endpoint: 'https://<XXXXXX>.stackhero-network.com',
  s3ForcePathStyle: true, // required with MinIO
  signatureVersion: 'v4'
});

// putObject operation
s3.putObject(
  { Bucket: 'testbucket', Key: 'testobject', Body: 'Hello from MinIO!' },
  (err, data) => {
    if (err)
      console.log(err);
    else
      console.log('Successfully uploaded data to testbucket/testobject');
  }
);

// getObject operation
const file = require('fs').createWriteStream('/tmp/mykey');
s3.getObject({ Bucket: 'testbucket', Key: 'testobject' })
  .on('httpData', chunk => file.write(chunk))
  .on('httpDone', () => file.end())
  .send();

For further details, visit the MinIO Node.js documentation.

Connecting to MinIO with the MinIO SDK

If you prefer using the MinIO SDK for Node.js, install it using npm:

npm install minio

Here is an example of how to connect to MinIO using the MinIO SDK for Node.js:

const process = require('process');
const Minio = require('minio');

// Instantiate the MinIO client with the endpoint and access keys
const minioClient = new Minio.Client({
  endpoint: '<XXXXXX>.stackhero-network.com',
  port: 443,
  useSSL: true,
  accessKeyId: 'YOUR_ACCESS_KEY',
  secretAccessKey: 'YOUR_SECRET_KEY',
});

// File to be uploaded
const file = '/tmp/photos-europe.tar';

// Create a bucket called 'europetrip'
minioClient.makeBucket(
  'europetrip',
  'us-east-1',
  err => {
    if (err) return console.log(err);

    console.log('Bucket created successfully in "us-east-1".');

    const metaData = {
      'Content-Type': 'application/octet-stream',
      'X-Amz-Meta-Testing': 1234,
      'example': 5678
    };
    // Upload the file to the bucket 'europetrip' using fPutObject API
    minioClient.fPutObject(
      'europetrip',
      'photos-europe.tar',
      file,
      metaData,
      (err, etag) => {
        if (err) return console.log(err);
        console.log('File uploaded successfully.');
      }
    );
  }
);

For more information, see the MinIO Node.js SDK documentation.