How to Upload Document Files to MinIO via Spring Boot

June 06, 2025

#1

MinIO is a high-performance, S3-compatible object storage system that’s easy to run locally or in the cloud. If you’re building a Java application with Spring Boot, integrating file upload functionality to MinIO is a common need—especially for storing documents like PDFs, Word files, or text files.
In this guide, you’ll learn how to upload document files to MinIO using Spring Boot. We’ll walk through the key components you need, including setting up a simple REST endpoint and using MinIO’s Java SDK.

What You’ll Learn

• How to integrate MinIO with a Spring Boot project
• How to configure access credentials
• How to build an API endpoint to upload files
• How to store documents in a MinIO bucket

Note: This article assumes you already have MinIO running and accessible from your Spring Boot app. If not, check out:
Connect Spring Boot to MinIO Server
MinIO Dependency Setup in Spring Boot

Step 1: Add MinIO SDK Dependency

Start by adding the MinIO Java client dependency to your pom.xml:

<dependency>
  <groupId>io.minio</groupId>
  <artifactId>minio</artifactId>
  <version>8.5.3</version> <!-- Use the latest version -->
</dependency>

This library gives you the tools needed to interact with MinIO (or any S3-compatible service).

Step 2: Configure MinIO in Your Application

Use either application.yml or application.properties to define your MinIO configuration.

application.properties (example):

minio.url=http://localhost:9000
minio.accessKey=minioadmin
minio.secretKey=minioadmin
minio.bucketName=documents

These values can be injected using @Value or bound using @ConfigurationProperties.

Step 3: Create a MinIO Client Bean

Create a configuration class to set up the MinIO client:

@Configuration
public class MinioConfig {

    @Value("${minio.url}")
    private String url;

    @Value("${minio.accessKey}")
    private String accessKey;

    @Value("${minio.secretKey}")
    private String secretKey;

    @Bean
    public MinioClient minioClient() {
        return MinioClient.builder()
                .endpoint(url)
                .credentials(accessKey, secretKey)
                .build();
    }
}

Step 4: Create a File Upload Service

Now let’s create a service that handles uploading files to MinIO:

@Service
public class FileStorageService {

    @Value("${minio.bucketName}")
    private String bucketName;

    private final MinioClient minioClient;

    public FileStorageService(MinioClient minioClient) {
        this.minioClient = minioClient;
    }

    public String uploadFile(MultipartFile file) throws Exception {
        // Ensure the bucket exists
        boolean found = minioClient.bucketExists(BucketExistsArgs.builder()
                .bucket(bucketName)
                .build());

        if (!found) {
            minioClient.makeBucket(MakeBucketArgs.builder()
                    .bucket(bucketName)
                    .build());
        }

        // Upload the file
        String fileName = UUID.randomUUID() + "_" + file.getOriginalFilename();

        minioClient.putObject(PutObjectArgs.builder()
                .bucket(bucketName)
                .object(fileName)
                .stream(file.getInputStream(), file.getSize(), -1)
                .contentType(file.getContentType())
                .build());

        return fileName;
    }
}

This code ensures the bucket exists, generates a unique filename, and uploads the file to MinIO.

Step 5: Create a REST Controller

Now let’s expose an API endpoint to upload document files:

@RestController
@RequestMapping("/api/files")
public class FileUploadController {

    private final FileStorageService fileStorageService;

    public FileUploadController(FileStorageService fileStorageService) {
        this.fileStorageService = fileStorageService;
    }

    @PostMapping("/upload")
    public ResponseEntity<String> uploadFile(@RequestParam("file") MultipartFile file) {
        try {
            String fileName = fileStorageService.uploadFile(file);
            return ResponseEntity.ok("File uploaded successfully: " + fileName);
        } catch (Exception e) {
            return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
                    .body("Error uploading file: " + e.getMessage());
        }
    }
}

You can now upload files using tools like Postman or directly from a frontend client.

Step 6: Test the Upload API

Use Postman or curl to test your endpoint:

curl -X POST http://localhost:8080/api/files/upload \
  -F "file=@sample.pdf"

Or use Postman’s form-data field to attach a document like .docx, .txt, or .pdf.
If everything is working, you’ll get a success message with the file name.

Best Practices

• Store file metadata in a database if needed
• Validate file types (e.g., only allow .pdf, .docx, .txt)
• Use unique file naming to prevent overwrites
• Implement error handling for file size and storage issues
• Use environment variables for credentials in production