Minio is a self-hosted Amazon S3 compatible object storage server. This makes it a very interesting solution if you want to host data on your own server, either on the internet or an 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 also runs.
Minio implements the Amazon S3 v4 API, which makes it very convenient if you already have tools or applications that use 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 will 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 various file operations like list, copy, diff, and mirror. It can connect to Minio servers and Amazon S3. You can find more information about the client in the official documentation.
After you have 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 that 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 have started the server, open a browser and go to the URL http://localhost:9000 when the Minio server is running on your own computer. Specify the IP address instead of localhost when Minio is running on another computer. To log in, you need the access and secret keys. Minio prints these keys to the console during startup.
You can already do a lot with the web interface, such as 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 communicates with the Minio server. Minio provides a Java client library that we will use for this application. This is not going to be a complete introduction to all the capabilities of the library, just a simple file upload. You can 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.14</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 requires the endpoint address and both keys as arguments. You can 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.
minioClient.listBuckets().forEach(b -> System.out.println(b.name()));
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());
minioClient.uploadObject(builder.build());
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 use the same API, this application can also connect to Amazon S3. All you have to do is change the keys to the ones you get from Amazon S3 and change the endpoint to the one that corresponds to the region where the bucket is hosted.
Amazon SDK ¶
To further prove that Minio is S3 API compliant, we will write the same application again, but this time using 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.780</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 is not using a common S3 HTTP endpoint, it needs to configure the Minio endpoint with an 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();
buckets.forEach(b -> System.out.println(b.getName()));
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);
}
client.putObject("cataws", "cat.jpg", tempFile.toFile());
Start the application, and you should find a picture in the folder cataws/cat.jpg.
You can see that both libraries provide the same functionality and work the same way. 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.