Storage Service

Your own S3 — without AWS bills, vendor lock-in, or complexity.

A lightweight, self-hosted file storage REST API. Upload files with custom metadata, retrieve them by ID, and manage them over a clean HTTP interface — all running on your own infrastructure in a single just dev.

---

Quick Start

Prerequisites: Docker, just

# 1. Copy env templates
cp envs/.env.api.example envs/.env.api
cp envs/.env.minio.example envs/.env.minio

# 2. Start the stack
just dev

The API is live at http://localhost:8080.

---

API

All file IDs must be UUID v4.

Method	Path	Description
PUT	/files/{id}	Upload or replace a file. Returns 201 (created) or 200 (replaced).
PUT	/files/{id}/meta	Replace metadata without re-uploading the file. Returns 204.
GET	/files/{id}	Stream file content. Content-Type is set from stored metadata.
GET	/files/{id}/meta	Get metadata as JSON.
DELETE	/files/{id}	Delete a file. Returns 204.
GET	/health	Liveness probe.

Upload

curl -X PUT http://localhost:8080/files/550e8400-e29b-41d4-a716-446655440000 \
  -F 'file=@report.pdf' \
  -F 'meta={"content-type":"application/pdf","author":"alice"}'

Download

curl -O http://localhost:8080/files/550e8400-e29b-41d4-a716-446655440000

Get metadata

curl http://localhost:8080/files/550e8400-e29b-41d4-a716-446655440000/meta

Update metadata

curl -X PUT http://localhost:8080/files/550e8400-e29b-41d4-a716-446655440000/meta \
  -H 'Content-Type: application/json' \
  -d '{"content-type":"application/pdf","project":"q1-final"}'

Delete

curl -X DELETE http://localhost:8080/files/550e8400-e29b-41d4-a716-446655440000

For a detailed description of the architecture, data flows, and design decisions see docs/architecture.md.

---

Contributing

See CONTRIBUTING.md.

License

MIT