Free · Open source

File Storage foundation

FiloraFS-LiteSpring Boot file upload starter

A focused Spring Boot local file upload starter with API-key access and straightforward REST APIs.

Spring BootREST APILocal storage
View on GitHubView documentation

FiloraFS-Lite · quick run

Quick start

Run FiloraFS-Lite

Terminal
git clone https://github.com/buildbasekit/FiloraFS-Lite.git
cd FiloraFS-Lite
# Local defaults work without a .env file
./mvnw spring-boot:run
Java 25 · Git · Maven wrapper includedRead the quickstart

Product preview

File upload

Release details

View changelog
Version
v2.0.0
Java
25
Spring Boot
4.1.1
License
MIT

Capability summary

Features

The focused capabilities included in the current product generation.

Local file storage

Store uploads under one configured filesystem path with UUID filenames, path containment, and checks that reject symbolic links.

API-key access

File operations require X-API-KEY, except OPTIONS requests. One shared key grants access to all stored files; replace the local development key before deployment.

File management APIs

Upload, retrieve, list, delete, and inspect file metadata through focused REST endpoints.

File-type allowlist

PNG, JPEG, PDF, and WebP uploads require matching extensions, declared media types, and lightweight content signatures. Multipart file and request limits default to 10 MB.

Minimal architecture

Controllers, an API-key filter, configuration and metadata records, and one local file service. Spring Boot supplies a public health endpoint and graceful shutdown.

Fit

Who this is for

  • Developers learning Spring Boot file upload patterns
  • Prototypes and internal tools using a single host
  • Small self-hosted applications with simple backup needs
  • Teams that want a readable local-storage starting point

Build or adopt

Why FiloraFS-Lite?

FiloraFS-Lite keeps the local-storage workflow small enough to understand and adapt without introducing a database or cloud provider.

Without FiloraFS-Lite

  • Wire multipart upload and file responses
  • Choose stored filenames and MIME handling
  • Add a basic access boundary
  • Document every file operation for consumers

With FiloraFS-Lite

  • Core local file operations are already exposed
  • API-key access is explicit and easy to replace
  • The project has no database dependency
  • The browser API tester and Postman collection cover the file workflow

Implementation resources

Technical documentation

Task-oriented setup, configuration, architecture, and API references for this product.

DocumentationQuickstart

Run FiloraFS-Lite without local configuration and try its file APIs in the browser.

Open resourceDocumentationConfiguration

Use local defaults, then override storage, API access, upload limits, and shutdown through environment variables or an optional .env file.

Open resourceDocumentationAPI Reference

Try and reference the API-key-protected local file endpoints available in FiloraFS-Lite.

Open resourceDocumentationArchitecture

Understand the small API-key, controller, service, and local filesystem flow.

Open resource

Edition guidance

When to upgrade to FiloraFS-Pro

Choose Pro when the application boundary extends beyond a small, single-host file service.

  • JWT authentication and user roles
  • MySQL-backed file metadata
  • AWS S3 storage
  • Pre-signed URLs and thumbnails
  • Commercial support and update policy
Compare FiloraFS-Pro

Related guidance

Architecture and implementation guidance related to this foundation.

GuideSpring Boot File Upload API with MultipartFile

Build a Spring Boot multipart file upload API with controller, service, and storage separation, configured limits, safe filenames, and verification steps.

5 min readGuideLocal File Storage in Spring Boot

Store and serve files from a configured local filesystem in Spring Boot with safe names, validation, controlled access, and a replaceable storage boundary.

8 min readGuideSpring Boot File Upload Mistakes and Fixes

Prevent common Spring Boot file upload mistakes involving controller logic, validation, configured paths, storage boundaries, filenames, and access control.

6 min read

Evaluate FiloraFS-Lite

Use the open-source starter when a small local-storage API fits your application boundary.

View on GitHubView the quickstart