duke-storage

Stateless file storage microservice for the Duke Messenger platform. Abstracts over multiple storage backends behind a single REST API with file validation, metadata persistence, and streaming delivery.

Quick Start

# 1. Install dependencies
cd duke-storage
npm install

# 2. Configure environment
cp .env.example .env
# Edit .env — at minimum set STORAGE_BACKEND and DATABASE_URL

# 3. Run database migration (if using PostgreSQL)
psql $DATABASE_URL -f docs/migration.sql

# 4. Start the service
npm run dev

Service starts on http://localhost:3001 by default.

Docker Compose

cp .env.example .env
docker compose up -d
curl http://localhost:3001/healthz

Architecture

Client
  │ HTTP REST
  ▼
API Layer (Express + multer)
  │ Auth middleware → Validation → Controller
  ▼
Storage Adapter (StorageProvider interface)
  ├── LocalStorage  (dev / single-node)
  └── MinioStorage  (production / multi-node)

Metadata Store (PostgreSQL)

API

| Method | Path | Description | |--------|------|-------------| | POST | /upload | Upload a file (multipart/form-data) | | GET | /files/:id/:filename | Download / stream a file | | GET | /files/:id/meta | Get file metadata | | DELETE | /files/:id | Delete a file | | GET | /buckets/:bucket/files | List files in a bucket | | GET | /healthz | Health check (no auth) |

See docs/api.md for the full reference.

Storage Backends

| Backend | STORAGE_BACKEND | Use case | |---------|------------------|----------| | Local Disk | local | Development, single-node | | MinIO | minio | Production, multi-node |

Environment Variables

Copy .env.example to .env. Key variables:

STORAGE_BACKEND=local          # or minio
DATABASE_URL=postgres://...    # PostgreSQL connection string
JWT_SECRET=your-secret         # for token verification
MAX_FILE_SIZE=52428800         # 50 MB default
ALLOWED_MIME_TYPES=image/,video/,audio/,application/pdf

Scripts

npm start          # Production
npm run dev        # Hot reload (nodemon)
npm test           # All tests
npm run test:unit  # Unit tests only

License

MIT © duke-messenger contributors