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:
- Download the ZIP from Gumroad and extract it.
- Open in your favorite IDE (Eclipse, IntelliJ, VS Code).
- Update
application.properties
with your database, S3, and JWT settings. - Build and run:
./mvnw clean install
java -jar target/filorafs-0.0.1-SNAPSHOT.jar
Your file storage backend is now live and ready to use.
Usage & Examples
Fetching User Info
GET /api/users/me
Authorization: Bearer <token>
Response:
{
"id": 1,
"username": "admin",
"email": "admin@example.com"
}
Uploading a File
curl -X POST "http://localhost:8080/file" \
-H "Authorization: Bearer <token>" \
-F "file=@./myfile.png"
Downloading a File
curl -X GET "http://localhost:8080/file/download/4" \
-H "Authorization: Bearer <token>" \
-o myfile.png
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=
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
Clean, modular, and ready to scale.
Testing
Run all tests with:
./mvnw test
Integration tests can be run using testcontainers
or your dev profile with environment variables.
Extending & Customization
-
Add new endpoints: update
controllers
andservices
. -
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
FiloraFS makes secure, scalable file storage simple. 👉 Get FiloraFS on Gumroad
Need a custom feature? Email us at boileragents@gmail.com
About Boileragents
Boileragents creates ready-to-use, developer-friendly starter projects so you can focus on building your product, not boilerplate code.
- GitHub: https://github.com/boileragents
- dev.to: https://dev.to/boiler_agents
- Email: boileragents@gmail.com
- Gumroad: https://boileragent.gumroad.com/
Take a look
- Create Your Own Custom Discord Bot Using Spring Boot
- Deploy a Spring Boot File Server on a Free VPS (Step-by-Step Guide)
- AuthKit : Spring Boot JWT Authentication Boilerplate
👉 Subscribe to get updates on new boilerplates, free resources, and practical tips — https://boileragent.gumroad.com/
Top comments (0)