BE-11: File Uploading and Object Storage Integration

[tecnodeveloper]

Implement file upload functionality for book-related assets (e.g., book images, review media) and store them in an object storage system. The solution should prioritize open-source, actively maintained alternatives to MinIO and include Docker-based orchestration.

User Story

Given a user uploads a file
When the request is processed
Then the file should be stored in object storage and accessible via URL

Goals

• Enable file uploads via API
• Store files in scalable object storage
• Avoid deprecated/unmaintained tools
• Provide a containerized setup using Docker Compose

Research Context

• Investigate object storage solutions

• Avoid MinIO (archived / maintenance mode as of 2026) ([alarik.io][1])

• Evaluate open-source alternatives:

  • Ceph (highly scalable, production-grade)
  • Garage (lightweight, S3-compatible)
  • SeaweedFS (good for large-scale file systems)
  • Alarik (modern, actively developed alternative) ([OpenAlternative][2])

• Compare trade-offs:

  • Complexity vs simplicity
  • Resource usage
  • S3 compatibility

• Document decision (ADR or README section)

Architecture Overview

• API (Node.js + Express)
• File upload middleware
• Object storage service (S3-compatible preferred)
• Docker Compose orchestration

Tasks

File Upload API

• Create file upload endpoint:

  POST /upload
  

• Accept:

  • Book images
  • Review media (optional)

• Validate file type (images/videos only)

• Validate file size limits

• Handle upload errors

Upload Handling

• Integrate file upload middleware:

  • multer (or equivalent)

• Store files temporarily before upload

• Generate unique file names

• Upload files to object storage

• Return file URL in response

Object Storage Integration

• Choose storage provider (after research)

• Ensure S3-compatible API (preferred)

• Configure SDK (e.g., AWS SDK for S3-compatible storage)

• Implement upload service:

  • Upload file
  • Get public/private URL

• Handle failures and retries

Docker Setup

• Create docker-compose.yml

• Add services:

  • API service
  • Object storage service (chosen alternative)

• Configure volumes for persistence

• Configure environment variables

• Ensure services communicate via network

Swagger Documentation

• Document /upload endpoint
• Add file upload schema (multipart/form-data)
• Add response examples

Project Structure

• Add upload-related modules:

  • /services/storage.service.js
  • /middlewares/upload.middleware.js
  • /routes/upload.routes.js

Acceptance Criteria

• File upload endpoint works

• Files stored in object storage

• Returned URL is accessible

• Invalid files rejected (type/size)

• Docker setup runs successfully:

  docker-compose up

• Services communicate correctly

• Swagger supports file upload testing

Testing Steps

• Run project with Docker
• Open Swagger UI
• Upload file via /upload
• Verify response contains file URL
• Check object storage:
  • File exists
• Access file via URL

Definition of Done

• Upload API implemented
• Object storage integrated
• Docker Compose working
• Research documented
• Swagger updated
• Code linted and formatted

Optional (Nice to Have)

• Generate thumbnails for images
• Add signed URLs (private access)
• Add file deletion endpoint
• Organize files by folder (e.g., /books/:id/)

---

Suggested Approach (Practical Tip)

For your level/project:

• Start with Garage (lightweight) or Alarik (modern & active)
• Avoid Ceph initially (too heavy for learning project)