Simple Filedrop - Ultra-Minimal File Sharing Platform

A simple, modern, secure file sharing application with OIDC authentication, download limits, and automatic expiration. Built with FastAPI and Alpine.js in a true single-file backend architecture for maximum simplicity and maintainability.

? Use case

Easily upload a file and instantly receive a secure, shareable link. You control access by setting a maximum download count or an automatic expiration date—after which the file is deleted. All access is protected by authentication via your chosen OIDC provider; there’s no manual user management or registration required. Only authenticated users can upload and share files.

✨ Features

🔐 Security First

• OIDC Authentication - Industry-standard OAuth/OpenID Connect
• Session Management - Secure session handling with signed cookies
• Token-based Access - Cryptographically secure file tokens
• No Public Access - All operations require authentication

📁 Smart File Management

• Download Limits - Set maximum download counts (1-∞)
• Automatic Expiration - Files expire after 1 day to 1 month
• Auto-Cleanup - Expired and limit-reached files automatically deleted
• Real-time Tracking - Monitor download counts and expiration status

🎨 Modern Interface

• Subtle Dark Theme - Professional glassmorphism design with neutral tones
• Drag & Drop - Intuitive file upload experience
• Responsive Design - Works on desktop, tablet, and mobile
• Real-time Updates - Live file status and progress indicators

⚡ Performance & Reliability

• Single File Backend - True single-file backend with all storage classes included (~545 lines)
• Lightweight Frontend - Alpine.js (15KB) for minimal footprint
• SQLite Database - Zero-configuration, embedded database
• Background Tasks - Non-blocking file operations
• Async Operations - High-performance async/await architecture

🖼️ Screenshots

🚀 Quick Start

Prerequisites

• Docker & Docker Compose
• Python 3.11+ (for development)

1. Clone & Configure

git clone <your-repo>
cd dropbox

# Configure environment
cp .env.example .env
# Edit .env with your OIDC provider settings

2. Start Application

# Production deployment
docker compose up -d

# Development mode
cd app
python -m pip install -r ../requirements.txt
python main.py

3. Access Application

• Web Interface: http://localhost:8000
• API Documentation: http://localhost:8000/docs

📋 Configuration

Environment Variables

Create a .env file with your OIDC provider settings:

# OIDC Authentication (required for production)
OIDC_CLIENT_ID=your_client_id
OIDC_CLIENT_SECRET=your_client_secret
OIDC_DISCOVERY_URL=https://your-provider.com/.well-known/openid_configuration
OIDC_REDIRECT_URI=http://localhost:8000/auth/callback

# Application Settings
DATABASE_PATH=app.db
SESSION_SECRET=your-secret-key-here
MAX_FILE_SIZE=1073741824  # 1GB default

# Storage Backend Configuration
STORAGE_BACKEND=local  # Options: "local" or "s3"

# Local Storage (default)
UPLOAD_DIR=uploads

# S3 Storage (required if STORAGE_BACKEND=s3)
S3_ENDPOINT_URL=http://minio:9000
S3_BUCKET_NAME=filedrop
S3_ACCESS_KEY_ID=your-access-key
S3_SECRET_ACCESS_KEY=your-secret-key
S3_REGION=us-east-1
S3_USE_SSL=false  # Set true for production with valid SSL certs

OIDC Providers

Compatible with any OpenID Connect provider:

• pocket-id (tested with): https://your-pocket-id.com/.well-known/openid_configuration
• Auth0: https://your-domain.auth0.com/.well-known/openid_configuration
• Google: https://accounts.google.com/.well-known/openid_configuration
• Microsoft: https://login.microsoftonline.com/common/v2.0/.well-known/openid_configuration
• Keycloak: https://your-keycloak.com/auth/realms/your-realm/.well-known/openid_configuration

Storage Backends

Simple Filedrop supports two storage backends:

Local Storage (Default)

Files are stored in the uploads/ directory on the local filesystem. Suitable for single-server deployments.

Configuration:

STORAGE_BACKEND=local
UPLOAD_DIR=uploads  # Optional, defaults to 'uploads'

S3-Compatible Storage (MinIO, Backblaze B2)

Files are stored in S3-compatible object storage. Recommended for scalability and cloud deployments.

MinIO Setup (Self-Hosted):

1. Deploy MinIO server (Docker, Kubernetes, or standalone)

2. Create a bucket named filedrop (or your preferred name)

3. Generate access credentials (Access Key ID and Secret Access Key)

4. Configure environment variables:

   STORAGE_BACKEND=s3
   S3_ENDPOINT_URL=http://your-minio-server:9000
   S3_BUCKET_NAME=filedrop
   S3_ACCESS_KEY_ID=your-access-key-id
   S3_SECRET_ACCESS_KEY=your-secret-access-key
   S3_REGION=us-east-1
   S3_USE_SSL=false  # Set true if MinIO has SSL configured

Backblaze B2 Setup:

1. Create a Backblaze B2 account

2. Create a private bucket

3. Generate an application key (with read/write permissions)

4. Configure environment variables:

   STORAGE_BACKEND=s3
   S3_ENDPOINT_URL=https://s3.us-west-002.backblazeb2.com
   S3_BUCKET_NAME=your-bucket-name
   S3_ACCESS_KEY_ID=your-key-id
   S3_SECRET_ACCESS_KEY=your-application-key
   S3_REGION=us-west-002  # Use your bucket's region
   S3_USE_SSL=true

S3 Storage Features:

• Files up to 1GB supported (configurable via MAX_FILE_SIZE)
• Presigned URLs for direct downloads (reduces server bandwidth)
• Automatic expiration via cleanup tasks
• Compatible with AWS S3, MinIO, Backblaze B2, and other S3-compatible services

🏗️ Architecture

Project Structure

simple-filedrop/
├── app/
│   ├── main.py              # Complete backend (FastAPI + Storage classes)
│   └── static/
│       ├── index.html       # Frontend HTML structure
│       ├── styles.css       # Modern dark theme styles
│       └── app.js           # Alpine.js application logic
├── requirements.txt         # Python dependencies
├── Dockerfile               # Container configuration
├── docker-compose.yml       # Deployment setup
└── README.md                # This file

Technology Stack

Backend (main.py - 545 lines)

• FastAPI - Modern async web framework
• SQLite - Embedded database
• OIDC - Authentication via authlib
• aiofiles - Async file operations
• aioboto3 - S3-compatible storage support
• Integrated Storage - Local and S3 storage backends included

Frontend (static/ - 633 lines)

• Alpine.js 3.14.1 - Lightweight reactive framework (15KB)
• Custom CSS - Modern glassmorphism design with subtle neutral tones
• FontAwesome - Icon library
• Responsive Design - Mobile-friendly interface

📊 API Endpoints

Authentication

• GET /auth/me - Check authentication status
• GET /auth/login - Initiate OIDC login
• GET /auth/callback - OIDC callback handler
• POST /auth/logout - Logout and clear session

File Operations

• POST /api/upload - Upload file with limits
• GET /api/files - List user's uploaded files
• GET /share/{token} - Download file by token
• DELETE /api/files/{id} - Delete file

Frontend

• GET / - Main application interface
• GET /static/* - Static assets (CSS, JS, images)

🔧 Development

Local Development Setup

# Create virtual environment
python -m venv venv
source venv/bin/activate  # Linux/Mac
# or
venv\Scripts\activate     # Windows

# Install dependencies
pip install -r requirements.txt

# Set test environment
export OIDC_CLIENT_ID=""  # Disable auth for testing

# Run application
python app/main.py

Code Organization

True Single File Backend

• All backend logic in app/main.py (545 lines)
• Includes storage backends (Local + S3), database, API, auth, and cleanup
• No separate storage.py or utility files
• Minimal dependencies, maximum maintainability
• Easy to understand, deploy, and modify

Minimalist Frontend

• Clean HTML structure (static/index.html - 248 lines)
• Modern CSS with subtle dark theme (static/styles.css - 124 lines)
• Alpine.js application logic (static/app.js - 261 lines)
• Total: ~1,178 lines for the entire application

🚢 Deployment

Docker Deployment (Recommended)

# Build and start
docker compose up -d

# View logs
docker compose logs -f

# Stop application
docker compose down

Manual Deployment

# Install dependencies
pip install -r requirements.txt

# Set production environment
export DATABASE_PATH=/var/lib/secureshare/app.db
export UPLOAD_DIR=/var/lib/secureshare/uploads

# Create directories
mkdir -p /var/lib/secureshare/uploads

# Run application
python app/main.py

Production Considerations

• Set strong SESSION_SECRET
• Configure proper OIDC redirect URIs
• Use reverse proxy (nginx) for HTTPS
• Set up log rotation and monitoring
• Regular database backups
• Monitor disk space for uploads

🔒 Security Features

Authentication & Authorization

• OIDC Integration - Delegate authentication to trusted providers
• Session Security - Cryptographically signed sessions
• No Anonymous Access - All operations require authentication
• Secure Tokens - URL-safe, cryptographically random file tokens

File Security

• Automatic Cleanup - Expired files automatically removed
• Download Limits - Prevent unlimited file sharing
• File Isolation - Files stored with unique tokens
• No Directory Traversal - Safe file path handling

Infrastructure Security

• Minimal Attack Surface - Single file backend
• No File Uploads to Web Root - Uploads stored separately
• CORS Configuration - Configurable cross-origin policies
• Error Handling - No sensitive information in error messages

🤝 Contributing

You're very welcome to contribute to this project by discussions, issues or pull requests.

📜 License

This project is licensed under the MIT License - see the LICENSE file for details.