Minio is a self-hosted Amazon S3 compatible object storage server. That makes it a very interesting solution if you want to host data on your own server on the internet or intranet. Minio is also an elegant solution if you want to create your own NAS at home. For example, with a Raspberry PI on which Minio runs too.
Minio implements the Amazon S3 v4 API that makes it very convenient when you already have tools or applications that speak and understand this API.
Minio is written in Go and runs on many platforms like Windows, Linux, macOS, and FreeBSD. Minio consists of only one binary file, and there is no need to install it. Just download it from the download page and start it from the command line. On the download page, you find two links: Minio Server and Minio Client. For the following example, we only need the server. The client is a command-line tool that provides all sorts of file operations like list, copy, diff, and mirror. It can connect to Minio servers and Amazon S3. You find more information about the client in the official documentation.
After you downloaded the binary file open a terminal and start the server with the following command:
minio server /storage
or on Windows
minio.exe server c:\storage
The second argument specifies the directory which Minio uses as the root for storing and fetching files.
Another very nice feature of Minio is that it provides a web interface out of the box. After you started the server, open a browser and go to the URL http://localhost:9000 when the Minio server runs on your own computer. Specify the IP address instead of localhost when Minio runs on another computer. To log in, you need the access and secret key. Minio prints these keys during start-up into the console.
You can already do a lot with the web interface, like uploading and downloading files, creating buckets, and configuring access controls for buckets. In the case of Minio, buckets are mapped to folders in the file system.
Minio SDK ¶
Next, we create a simple Java application that speaks with the Minio server. Minio provides a Java client library that we use for this application. This is not going to be a complete introduction to all capabilities of the library, just a simple file upload. You find descriptions of all the supported operations on the official documentation page: https://min.io/docs/minio/linux/developers/java/API.html
First, create a Maven project and then add this dependency to the pom.xml
<dependency>
<groupId>io.minio</groupId>
<artifactId>minio</artifactId>
<version>8.5.7</version>
</dependency>
Create a new class with a main method and insert the following code. To send operations to the server, the application needs an instance of the MinioClient class. The constructor needs the endpoint address and both keys as arguments. You find this information in the terminal.
try {
String accessKey = "minioadmin";
String secretKey = "minioadmin";
MinioClient minioClient = MinioClient.builder().endpoint("http://127.0.0.1:9000")
Next, the application checks if a bucket with the name cats already exists. If not, it creates it.
boolean isExist = minioClient
.bucketExists(BucketExistsArgs.builder().bucket("cats").build());
if (isExist) {
System.out.println("Bucket already exists.");
}
else {
minioClient.makeBucket(MakeBucketArgs.builder().bucket("cats").build());
To demonstrate another operation the application lists all the existing buckets
Next, the application downloads a random cat picture from the internet and uploads it to our Minio server with the putObject operation.
URL url = URI.create(
"https://preview.redd.it/7i4g79z1ih071.jpg?width=640&crop=smart&auto=webp&s=139c4dc2c873d538316519031dc7c8ea8bd86c36").toURL();
Path tempFile = Files.createTempFile("cat", ".jpg");
try (InputStream in = url.openStream()) {
Files.copy(in, tempFile, StandardCopyOption.REPLACE_EXISTING);
}
UploadObjectArgs.Builder builder = UploadObjectArgs.builder().bucket("cats")
.object("cat.jpg").filename(tempFile.toString());
When you start the application, you should see a file cat/cat.jpg in the directory that you specified as the root folder when you started the Minio server.
Because Minio and S3 speak the same API, this application is able to connect to Amazon S3 too. All you have to do is change the keys with the ones you get from Amazon S3 and change the endpoint that corresponds to the region where the bucket is hosted.
Amazon SDK ¶
To further prove that Minio is S3 API compliant, we write the same application again, but this time with the official Amazon S3 Java library. For that, we need to add this dependency to our pom.xml
<dependency>
<groupId>com.amazonaws</groupId>
<artifactId>aws-java-sdk-s3</artifactId>
<version>1.12.629</version>
</dependency>
To access the operations, the application needs an instance of AmazonS3. The application creates that with the help of the AmazonS3ClientBuilder. Because the program does not use a common S3 HTTP endpoint, it needs to configure the Minio endpoint with a EndpointConfiguration.
public static void main(String[] args) throws IOException {
String accessKey = "minioadmin";
String secretKey = "minioadmin";
AWSCredentials credentials = new BasicAWSCredentials(accessKey, secretKey);
ClientConfiguration clientConfig = new ClientConfiguration();
clientConfig.setProtocol(Protocol.HTTP);
EndpointConfiguration endpointConfiguration = new EndpointConfiguration(
"http://127.0.0.1:9000", "us-east-1");
AmazonS3 client = AmazonS3ClientBuilder.standard()
.withCredentials(new AWSStaticCredentialsProvider(credentials))
.withClientConfiguration(clientConfig)
Next, the program checks if the bucket with the name cataws already exists. If not, it creates it.
boolean isExist = client.doesBucketExistV2("cataws");
if (isExist) {
System.out.println("Bucket already exists.");
}
else {
client.createBucket("cataws");
Then it lists all existing buckets
List<Bucket> buckets = client.listBuckets();
And like in the previous application, it downloads a cat picture from the internet and uploads it to the Minio Server.
URL url = URI.create(
"https://preview.redd.it/7i4g79z1ih071.jpg?width=640&crop=smart&auto=webp&s=139c4dc2c873d538316519031dc7c8ea8bd86c36").toURL();
Path tempFile = Files.createTempFile("cat", ".jpg");
try (InputStream in = url.openStream()) {
Files.copy(in, tempFile, StandardCopyOption.REPLACE_EXISTING);
}
Start the application, and you should find a picture in the folder cataws/cat.jpg.
You see that both libraries provide the same functionality and work the same. If you have applications written with the Amazon S3 library and want to switch to a self-hosted Minio server, you only need to change the keys and endpoint address. Everything else should work out of the box.