sharey/README.md

# Sharey 📁

A secure, modern file sharing platform with configurable storage backends, encryption, themes, and flexible deployment options.

## ✨ Features

- 📁 **File Sharing**: Upload files and get shareable links
- 📝 **Pastebin**: Share text snippets with syntax highlighting
- 💾 **Flexible Storage**: Choose between Backblaze B2 cloud storage or local filesystem
- 🔒 **Client-side Encryption**: Optional encryption for sensitive files
- 🎨 **Dark/Light Themes**: Toggle between themes with preference saving
- 🔗 **Short URLs**: Clean, easy-to-share links
- 🛡️ **Admin Panel**: Secure administration interface
- 🔧 **Maintenance Mode**: Graceful service management

## ⚡ Quick Storage Setup

**Choose your storage type in `config.json`:**

```json
{
  "storage": {
    "backend": "local"    // Use "local" for filesystem or "b2" for cloud
  }
}
```

- 🏠 **`"local"`** = Files stored on your server (free, fast)
- ☁️ **`"b2"`** = Files stored in Backblaze B2 cloud (scalable, reliable)

**Test your choice:** `python test_storage.py`

## 🏗️ Project Structure

```
sharey/
├── src/                    # Application source code
│   ├── app.py             # Main Flask application
│   ├── config.py          # Configuration management
│   ├── config_util.py     # Configuration utilities
│   ├── static/            # CSS, JS, and static assets
│   └── templates/         # HTML templates
├── tests/                 # Test files
├── scripts/               # Utility scripts
│   ├── migrate.py         # Database migration
│   ├── setup.py          # Setup script
│   ├── setup.sh          # Shell setup script
│   └── set_admin_password.py
├── docs/                  # Documentation
├── logs/                  # Application logs
├── config.json           # Application configuration
├── requirements.txt      # Python dependencies
├── run.py                # Application entry point
└── README.md             # This file
```

## 🚀 Quick Start

### Method 1: Enhanced Python Runner (Recommended)
```bash
python run.py
```
This will automatically:
- Check Python version (3.8+ required)
- Create and activate virtual environment if needed
- Install dependencies
- Validate configuration
- Create necessary directories
- Start the application

## 💾 Storage Configuration

Sharey supports multiple storage backends for maximum flexibility. Choose the one that best fits your needs:

### 🔄 **How to Choose Storage Type**

**Method 1: Edit config.json directly (Easiest)**
Open your `config.json` file and change the `backend` field:

```json
{
  "storage": {
    "backend": "local"    // Change to "local" or "b2"
  }
}
```

**Method 2: Interactive setup**
```bash
python src/config_util.py set    # Interactive configuration
python src/config_util.py validate   # Validate your choice
python test_storage.py           # Test the storage backend
```

**Method 3: Environment variables**
```bash
export STORAGE_BACKEND=local     # or "b2"
```

### Option 1: Backblaze B2 Cloud Storage (Recommended for Production)
```json
{
  "storage": {
    "backend": "b2"
  },
  "b2": {
    "application_key_id": "your_key_id",
    "application_key": "your_application_key", 
    "bucket_name": "your_bucket_name"
  }
}
```
- ✅ Unlimited scalability
- ✅ Built-in redundancy and reliability  
- ✅ No local storage requirements
- 💰 Small cost (~$0.005/GB/month)

### Option 2: Local Filesystem Storage (Good for Development/Self-hosting)
```json
{
  "storage": {
    "backend": "local",
    "local_path": "storage"
  }
}
```
- ✅ No external dependencies or costs
- ✅ Fast local access
- ✅ Complete data control
- ⚠️ Limited by disk space
- ⚠️ No built-in redundancy

### 🧪 **Test Your Storage Choice**
After changing the storage backend, always test it:

```bash
python src/config_util.py validate  # Validate configuration
python test_storage.py              # Test storage operations
```

**Quick Test Results:**
- ✅ `Storage backend initialized: local` = Local storage working
- ✅ `Storage backend initialized: b2` = B2 cloud storage working
- ❌ `Storage test failed` = Check your configuration
- ✅ Fast local access
- ✅ Complete data control
- ⚠️ Limited by disk space
- ⚠️ No built-in redundancy
```

**Interactive Configuration:**
```bash
python src/config_util.py set      # Interactive setup
python src/config_util.py validate # Validate configuration
python test_storage.py             # Test storage backend
```

See [docs/STORAGE.md](docs/STORAGE.md) for complete storage configuration guide.

### Method 2: Python Utility
```bash
# Direct Python usage
python sharey.py start     # Full application start
python sharey.py dev       # Quick development mode
python sharey.py setup     # Set up environment
python sharey.py status    # Check system status
python sharey.py clean     # Clean temporary files
python sharey.py test      # Run tests
python sharey.py logs      # Show recent logs
python sharey.py service   # Install as system service (Linux)

# Or use the wrapper script (shorter)
./sharey status            # Unix/Linux/macOS
```

### Method 3: Manual Setup
```bash
# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate  # Linux/macOS
# .venv\Scripts\activate   # Windows

# Install dependencies
pip install -r requirements.txt

# Configure storage backend
cp config.json.example config.json
# Edit config.json with your settings

# Run
python src/app.py
```

## 📋 Features

- 🔐 **Security**: Optional file encryption with password protection
- 🎨 **Themes**: Light/dark mode with elegant UI
- ☁️ **Cloud Storage**: Backblaze B2 integration
- 📊 **Progress Tracking**: Real-time upload progress with percentage
- 📱 **Mobile Friendly**: Responsive design for all devices
- 🔗 **Easy Sharing**: Direct links, QR codes, and clipboard integration
- 📝 **Pastebin**: Share text content with syntax highlighting

## 🛠️ Development

### Running Tests
```bash
cd tests
python -m pytest
```

### Development Mode
```bash
# Set debug mode in config.json
python run.py
```

## 📚 Documentation

See the `docs/` directory for:
- Configuration guide
- Deployment instructions
- API documentation
- Migration notes

## 🔧 Configuration

Key configuration options in `config.json`:
- `host`: Server host (default: 0.0.0.0)
- `port`: Server port (default: 5000)
- `debug`: Debug mode (default: false)
- `max_file_size`: Maximum upload size
- `b2_*`: Backblaze B2 credentials

## 📄 License

See LICENSE file for details.