Storage Service

A comprehensive file storage microservice supporting multiple storage backends, image transformations, and file sharing.

Features

• Multiple Storage Providers: S3-compatible (AWS S3, MinIO, DigitalOcean Spaces) and local filesystem
• Image Processing: Resize, crop, format conversion, thumbnails, blur, sharpen, grayscale
• File Sharing: Password-protected share links with expiration and download limits
• Chunked Uploads: Resumable uploads for large files
• Multi-tenant: Full tenant isolation with configurable quotas
• OAuth 2.0: Authentication via auth service token introspection

Quick Start

Development

# Start development environment
make up-dev

# Or manually
docker-compose -f docker-compose.dev.yml up -d

Production

# Build and start
docker-compose up -d

API Endpoints

Files

Method	Endpoint	Description
POST	/api/v1/files	Upload a file
GET	/api/v1/files	List files
GET	/api/v1/files/:id	Get file metadata
GET	/api/v1/files/:id/download	Download file (with transforms)
GET	/api/v1/files/:id/thumbnail	Get file thumbnail
GET	/api/v1/files/:id/url	Get signed URL
PATCH	/api/v1/files/:id	Update file
DELETE	/api/v1/files/:id	Delete file
POST	/api/v1/files/:id/copy	Copy file

Image Transformations

Download with transformations:

GET /api/v1/files/:id/download?w=800&h=600&q=85&f=webp&fit=cover

Parameters:

• w - Width
• h - Height
• q - Quality (1-100)
• f - Format (jpeg, png, webp, avif)
• fit - Fit mode (contain, cover, fill, inside, outside)
• blur - Blur amount
• sharpen - Enable sharpening
• grayscale - Convert to grayscale
• rotate - Rotation degrees (90, 180, 270)
• flip - Flip vertically
• flop - Flip horizontally

Folders

Method	Endpoint	Description
POST	/api/v1/folders	Create folder
GET	/api/v1/folders	List folders
GET	/api/v1/folders/tree	Get folder tree
GET	/api/v1/folders/:id	Get folder
GET	/api/v1/folders/:id/breadcrumb	Get breadcrumb path
GET	/api/v1/folders/:id/contents	Get folder contents
PATCH	/api/v1/folders/:id	Update folder
DELETE	/api/v1/folders/:id	Delete folder
POST	/api/v1/folders/:id/move	Move folder

Shares

Method	Endpoint	Description
POST	/api/v1/shares	Create share link
GET	/api/v1/shares	List my shares
GET	/api/v1/shares/:id	Get share
DELETE	/api/v1/shares/:id	Delete share
POST	/api/v1/shares/:id/deactivate	Deactivate share

Public Share Access

GET /share/:token           # Get share info
GET /share/:token/download  # Download shared file

Chunked Uploads

Method	Endpoint	Description
POST	/api/v1/uploads	Create upload session
GET	/api/v1/uploads	List my sessions
GET	/api/v1/uploads/:id	Get session status
POST	/api/v1/uploads/:id/chunks	Upload chunk
POST	/api/v1/uploads/:id/complete	Complete upload
DELETE	/api/v1/uploads/:id	Cancel upload

Settings & Usage

Method	Endpoint	Description
GET	/api/v1/settings/usage	Get storage usage
GET	/api/v1/settings	List settings
POST	/api/v1/settings	Create setting
PUT	/api/v1/settings/upsert	Upsert setting

Configuration

Variable	Description	Default
SERVER_PORT	HTTP server port	5004
POSTGRES_HOST	PostgreSQL host	localhost
POSTGRES_PORT	PostgreSQL port	5432
POSTGRES_USER	PostgreSQL user	minisource
POSTGRES_PASSWORD	PostgreSQL password	minisource
POSTGRES_DB	PostgreSQL database	storage
STORAGE_DEFAULT_PROVIDER	Default storage provider	s3
STORAGE_S3_ENDPOINT	S3/MinIO endpoint	localhost:9000
STORAGE_S3_BUCKET	S3 bucket name	storage
STORAGE_S3_ACCESS_KEY	S3 access key	-
STORAGE_S3_SECRET_KEY	S3 secret key	-
STORAGE_LOCAL_PATH	Local storage path	./uploads
IMAGE_MAX_WIDTH	Max image width	4096
IMAGE_MAX_HEIGHT	Max image height	4096
UPLOAD_MAX_FILE_SIZE	Max upload size	100MB
AUTH_SERVICE_URL	Auth service URL	-

Scopes

Scope	Description
storage:read	Read files and folders
storage:write	Upload and update files
storage:delete	Delete files and folders
storage:share	Create and manage share links
storage:admin	Manage settings and providers

Development

# Run tests
make test

# Run with hot reload
make dev

# Generate swagger docs
make swagger

# Lint code
make lint

License

MIT License