DEV Community

Cover image for FiloraFS: The Ultimate Spring Boot File Storage Boilerplate
boiler_agents
boiler_agents

Posted on

FiloraFS: The Ultimate Spring Boot File Storage Boilerplate

#springboot #springsecurity #productivity #boilerplate

TL;DR: FiloraFS is a developer-friendly Spring Boot boilerplate that makes building secure, scalable file storage systems effortless, complete with JWT auth, S3/local storage fallback, and API-ready file management.

Introduction

If you've ever built an application that handles file uploads, downloads, or storage, you know how tricky it can get. Handling security, generating thumbnails, integrating cloud storage, and providing a clean API - all while keeping your code maintainable - is no small feat.

That’s where FiloraFS comes in. This Spring Boot boilerplate is designed to take the pain out of building file storage systems, giving you a ready-to-go backend that’s secure, organized, and production-ready.

Perfect for: developers, freelancers, small teams, and anyone who wants to integrate file management quickly without reinventing the wheel.

Why You’ll Love This Boilerplate

  • Saves you time: Skip weeks of setup. FiloraFS gives you file storage, JWT authentication, and APIs out of the box.
  • Production-ready: Security, validation, S3/local fallback - all built-in so you can deploy confidently.
  • Opinionated best practices: Structured code, clean architecture, and consistent error handling make scaling easy.
  • Fully featured: JWT auth, file upload/download, thumbnails, S3 & local storage fallback, Docker-ready, Postman collection for testing.

In short, FiloraFS isn’t just a starter kit - it’s a solid foundation for any project that deals with files.

Key Features

  • JWT Authentication - secure login, registration, and role-based access control.
  • File Upload & Download - easily handle files, complete with metadata.
  • Thumbnail Generation - automatically generate image previews for your app.
  • S3 + Local Storage Fallback - store files in the cloud or locally with automatic fallback.
  • File Management APIs - list files, delete, get info, stream content, and generate pre-signed URLs.
  • Ready-to-use Postman Collection - test your APIs instantly without writing extra code.

Prerequisites

Before you dive in, make sure you have:

  • Java 21 / OpenJDK 21
  • Maven 3.8+
  • Docker (optional, but recommended for deployment)

Quick Start: Install & Run

Getting started is simple:

  1. Download the ZIP from Gumroad and extract it.
  2. Open in your favorite IDE (Eclipse, IntelliJ, VS Code).
  3. Update application.propertieswith your database, S3, and JWT settings.
  4. Build and run: 
./mvnw clean install
java -jar target/filorafs-0.0.1-SNAPSHOT.jar
Enter fullscreen mode Exit fullscreen mode

Your file storage backend is now live and ready to use.

Usage & Examples

Fetching User Info 

GET /api/users/me
Authorization: Bearer <token>
Enter fullscreen mode Exit fullscreen mode

Response:

{
  "id": 1,
  "username": "admin",
  "email": "admin@example.com"
}
Enter fullscreen mode Exit fullscreen mode

Uploading a File 

curl -X POST "http://localhost:8080/file" \
  -H "Authorization: Bearer <token>" \
  -F "file=@./myfile.png"
Enter fullscreen mode Exit fullscreen mode

Downloading a File 

curl -X GET "http://localhost:8080/file/download/4" \
  -H "Authorization: Bearer <token>" \
  -o myfile.png
Enter fullscreen mode Exit fullscreen mode

With FiloraFS, uploading, streaming, and managing files is as easy as calling a few endpoints.

Configuration Made Simple

FiloraFS keeps configuration straightforward:

  • application.properties — main Spring config (dev & prod profiles) 

# Application Name
spring.application.name=FiloraFS
app.base-url=http://localhost:8080

# Database Configuration (MySQL)
spring.datasource.url=jdbc:mysql://localhost:3306/boiler_agents_filora_fs_db
spring.datasource.username=root
spring.datasource.password=<your password>

# Hibernate / JPA
spring.jpa.hibernate.ddl-auto=update
spring.jpa.database-platform=org.hibernate.dialect.MySQLDialect
spring.jpa.properties.hibernate.current_session_context_class=org.springframework.orm.hibernate5.SpringSessionContext
spring.jpa.properties.hibernate.allow_update_outside_transaction=true

# JWT
app.jwt.secret=<change-me-to-a-very-long-random-string>
app.jwt.access-token-expiration-ms= 900000
app.jwt.refresh-token-expiration-ms= 1209600000

# File Configuration
spring.servlet.multipart.max-file-size=50MB
spring.servlet.multipart.max-request-size=50MB
# Change this path to where you want files to be stored
file.upload-dir=<your local storage directory>
file.max-size-bytes=52428800
file.allowed-types=image/png,image/jpeg,application/pdf,video/mp4

# Thumbnail Configuration
app.thumbnails.enabled=true
app.thumbnails.dir=thumbs
app.thumbnails.width=300
app.thumbnails.quality=0.85

# S3 (set s3.enabled=true and provide credentials + bucket to enable)
s3.enabled=true
s3.access-key=<acess key>
s3.secret-key=<secret key>
s3.region=us-east-1
s3.bucket=<s3 bucket
# optional: s3.endpoint-url for S3-compatible storages (minio) - not used directly in code above
# s3.endpoint-url=http://localhost:9000

# If you are using LocalStack's S3 provide endpoint otherwise leave blank for real aws s3 service
s3.endpoint-url=
Enter fullscreen mode Exit fullscreen mode

Project Structure 


# Top-level project files

FiloraFS.postman_collection.json   # Postman collection for testing all API endpoints
license.md                          # License information for the project (MIT)
pom.xml                             # Maven project configuration file
readme.md                            # Project README with setup, usage, and documentation

# Source code
src
└── main
    ├── java
    │   └── com/filorafs
    │       ├── config            # Application and framework configuration (Security, S3, Async, FileStorage)
    │       ├── controller        # REST controllers for handling HTTP requests (Auth, File, User)
    │       ├── dto               # Data Transfer Objects for API responses and requests
    │       ├── entity            # JPA entity classes mapping database tables
    │       ├── exception         # Custom exceptions and global exception handling
    │       ├── repository        # Spring Data repositories for database access
    │       ├── security          # JWT authentication, filters, and security-related services
    │       ├── service           # Core business logic for files, thumbnails, users, and S3/local storage
    │       └── util              # Utility classes (e.g., file validation)
    │
    └── resources
        └── application.properties   # Main Spring Boot properties file for configuration
Enter fullscreen mode Exit fullscreen mode

Clean, modular, and ready to scale.

Testing

Run all tests with:

./mvnw test
Enter fullscreen mode Exit fullscreen mode

Integration tests can be run using testcontainers or your dev profile with environment variables.

Extending & Customization

  • Add new endpoints: update controllers and services.
  • Change database: update application.properties and repository layer.
  • Modify authentication: tweak JwtAuthFilter and security configs.

FiloraFS is built to be extended without breaking core functionality.

Troubleshooting / FAQ

  • App doesn’t start: Check JWT_SECRET, DB connection, and logs.
  • Forgot admin password: Reset via provided DB scripts.
  • File upload fails: Verify S3 credentials or local folder permissions.

License

This project is licensed under the MIT License – you can use it in personal and commercial projects.

Final Thoughts

About Boileragents

Boileragents creates ready-to-use, developer-friendly starter projects so you can focus on building your product, not boilerplate code.

Take a look

👉 Subscribe to get updates on new boilerplates, free resources, and practical tips — https://boileragent.gumroad.com/

Top comments (0)