File Sharing Service

A self-hostable, cloud-native file sharing service with a CLI interface. Built with TypeScript, Node.js, PostgreSQL, and MinIO.

Features

• Simple CLI Interface: Upload files with a single command
• Secure File Sharing: Generate unique links for each file
• Password Protection: Optionally protect files with passwords
• Expiration Control: Set expiration times for shared files
• Self-Contained: Entire stack runs in Docker containers
• Type-Safe: End-to-end type safety with TypeScript and Prisma

Architecture

This project follows a modular, feature-based architecture with clean separation of concerns:

• Backend: Express.js REST API with TypeScript
• Database: PostgreSQL with Prisma ORM
• Storage: MinIO (S3-compatible object storage)
• CLI: Commander-based command-line interface

Prerequisites

• Docker and Docker Compose
• Node.js 16+ (for local development)

Quick Start

Running with Docker Compose

1. Clone the repository:

git clone https://github.com/yourusername/file-sharing-service.git
cd file-sharing-service

2. Create a .env file from the example:

cp .env.example .env

3. Start the entire stack with Docker Compose:

docker-compose up --build

This will start the backend server, PostgreSQL database, and MinIO storage service.

4. The services will be available at:
   • Backend API: http://localhost:3000
   • MinIO Console: http://localhost:9001 (login with credentials from docker-compose.yml)

First-Time Setup

After the first launch, you may need to:

1. Log in to the MinIO console at http://localhost:9001 using:

   • Username: minio-root-user
   • Password: minio-root-password

2. Verify that the uploads bucket has been created automatically.

Using the CLI Tool

Installation

# Install from npm
npm install -g file-sharing-service

# Or install locally from the repository
npm install -g .

Commands

Upload a File

fileshare upload /path/to/file.txt

Upload with Expiration (in seconds)

fileshare upload /path/to/file.txt --expires 86400  # Expires in 24 hours

Upload with Password Protection

fileshare upload /path/to/file.txt --password mysecretpassword

Combine Options

fileshare upload /path/to/file.txt --expires 3600 --password mysecretpassword

Development

Setup

1. Install dependencies:

npm install

2. Generate Prisma client:

npm run db:generate

3. Run database migrations:

npm run db:migrate

4. Start the development server:

npm run dev

Git Hooks

This project uses Husky to enforce code quality and prevent common mistakes:

• Pre-commit Hook: Prevents committing .env files and runs TypeScript type checking
• Commit Message Hook: Enforces conventional commit message format
• Pre-push Hook: Validates branch naming conventions

Commit Message Format

Commit messages must follow the Conventional Commits specification:

<type>(<optional scope>): <description>

[optional body]

[optional footer(s)]

Valid types: build, chore, ci, docs, feat, fix, perf, refactor, revert, style, test

Branch Naming Convention

Branch names should follow the format: type/description

Valid types: feature, bugfix, hotfix, release, chore, docs, refactor, test

Examples:

• feature/add-login
• bugfix/fix-upload-issue

Building

npm run build

API Endpoints

Upload

• POST /upload/url: Get a presigned URL for direct upload to MinIO

Download

• GET /download/:slug: Download a file by its unique slug
• GET /download/:slug/info: Get file information without downloading

License

MIT