file-storage

Secure File Storage Service

A secure web application for storing and sharing files with customizable url.

Preview

File Storage interface showing upload form and file management

Fun fact: This preview image is actually being served by this tool! It was uploaded and made public using the file storage service itself. 🎉

Features

• 🔐 Secure authentication system with session timeout
• 📁 Custom link names for each uploaded file
• 🔄 File versioning support
• 🌐 Public/Private file toggle options
• ⏲️ 30-minute session timeout for security
• 🔗 Easy-to-share download links
• 🗑️ File management (upload, delete, visibility toggle)
• 📱 Responsive design
• ⚡ Session timeout warning (10 minutes before expiry)
• 📂 Configurable upload directory
• 🔄 Automatic directory creation
• 🐳 Docker support
• 🔒 Password protection for files
• 🗄️ Database support:
  • SQLite (default)
  • PostgreSQL
• 🔄 Database migrations using Alembic

URL Structure

# Clean and intuitive URLs:
http://your-domain.com/file/my-resume        # File info page
http://your-domain.com/download/my-resume    # Direct download
http://your-domain.com/preview/my-resume     # Browser preview

# Version control adds suffix automatically:
http://your-domain.com/file/my-resume-v1
http://your-domain.com/download/my-resume-v1
http://your-domain.com/preview/my-resume-v1

When uploading a file, you can:

• Choose a custom URL that’s meaningful to you
• Set a password for private files
• Make files public or private
• Preview files directly in the browser
• Download files directly

File Access Levels

• Public Files: Accessible to anyone with the link
• Private Files: Requires password or admin access
• Admin Access: Full access to all files and management features

User Interface Features

• Toast notifications for all actions (success, error, info)
• Separate download and preview options
• Quick copy buttons for sharing links
• Improved file deletion confirmation
• Clear visual indicators for file visibility status
• Custom link name display in file list
• Clean and intuitive URL structure

Technical Stack

• FastAPI (Python web framework)
• SQLite/PostgreSQL (Database)
• SQLAlchemy (ORM)
• Alembic (Database migrations)
• HTTP Basic Auth (Authentication)
• Jinja2 Templates (Frontend)
• Custom middleware for session management
• Docker & Docker Compose

Installation

Method 1: Traditional Setup

1. Clone the repository
2. Create a .env file with your credentials:

   ADMIN_USERNAME=your_username
   ADMIN_PASSWORD=your_password
   UPLOAD_DIR=/path/to/custom/uploads  # Optional - defaults to "uploads" folder
      
   # Database Configuration (Optional)
   DB_TYPE=sqlite                      # or 'postgres'
   DATABASE_PATH=/path/to/data         # SQLite only - defaults to "./data"
   DB_NAME=file-storage               # defaults to "file-storage"
      
   # PostgreSQL Configuration (if using postgres)
   DB_HOST=localhost
   DB_PORT=5432
   DB_USER=postgres
   DB_PASSWORD=your_password
   

3. Install dependencies: pip install -r requirements.txt
4. Initialize database:

   # Create initial migration
   alembic revision --autogenerate -m "Initial schema"
      
   # Apply migration
   alembic upgrade head
   

5. Run the application: uvicorn main:app --reload

Method 2: Docker Setup

1. Clone the repository
2. Create a .env file with your credentials (same as above)
3. Build and run with Docker Compose:

   docker-compose up -d --build
   

Docker-specific commands:

• Start application: docker-compose up -d
• View logs: docker-compose logs -f
• Stop application: docker-compose down
• Rebuild after changes: docker-compose up -d --build

The Docker setup includes:

• Persistent volume for uploads
• Persistent volume for database
• Automatic container restart
• Health checks
• Secure non-root user configuration

Security Features

• Protected routes with authentication
• Session timeout after 30 minutes of inactivity
• Secure file handling
• Environment variable configuration
• Public/Private file access control
• Session warning notifications

Usage

• Upload files with custom link names
• Toggle file visibility between public and private
• Share download links with others
• Manage files through the web interface
• Automatic version control for files with same custom link name
• Configure custom upload directory through environment variables
• Automatic creation of upload directory if it doesn’t exist