rbox/README.md

# RBox

RBox is a self-hosted cloud storage web application designed for secure, scalable file management and sharing. Built with modern web technologies, it provides a comprehensive solution for individuals and organizations seeking full control over their data storage.

## Features

### Core Functionality
- **File Management**: Upload, download, organize, and manage files with a hierarchical folder structure
- **User Authentication**: Secure login with optional two-factor authentication (TOTP)
- **File Sharing**: Generate shareable links with customizable permissions and expiration dates
- **Search**: Full-text search across file names, metadata, and content
- **Thumbnails**: Automatic generation of image and video thumbnails for quick browsing
- **Photo Gallery**: Dedicated gallery view with date-based organization and lazy loading
- **File Requests**: Create forms for external users to submit files securely
- **Activity Logging**: Comprehensive audit trail of all file operations
- **Teams**: Organizational structure with role-based access control

### Storage & Performance
- **Multiple Storage Backends**: Support for local filesystem and S3-compatible object storage
- **WebDAV Protocol**: Native WebDAV support for seamless integration with desktop clients
- **SFTP Support**: Secure file transfer protocol for advanced users
- **Caching**: Redis-based caching for improved performance
- **Background Processing**: Asynchronous task queues for thumbnail generation and file processing
- **Quota Management**: Configurable storage limits per user

### Security & Compliance
- **Encryption**: TLS certificate management with Let's Encrypt integration
- **At-Rest Encryption**: Optional encryption of stored files
- **End-to-End Encryption**: Client-side encryption mode for maximum security
- **IP Whitelisting**: Enterprise-grade access controls
- **Audit Logging**: Detailed logs of all permission changes and access attempts

### Collaboration & Communication
- **Real-time Activity Feed**: Live updates on file operations across teams
- **Commenting System**: File-level discussions with email notifications
- **Email Integration**: SMTP configuration for notifications and invitations
- **Webhook Support**: Integration with external services via webhooks

### Administration
- **Billing Integration**: Stripe-powered subscription management and invoicing
- **Usage Analytics**: Detailed reporting on storage consumption and bandwidth usage
- **Admin Console**: Centralized user management and system monitoring
- **API Access**: RESTful API for third-party integrations

## Installation

### Prerequisites
- Python 3.12+
- PostgreSQL 15+
- Redis 7+
- Docker and Docker Compose (recommended)

### Quick Start with Docker

1. Clone the repository and navigate to the project directory
2. Copy the environment template:
   ```bash
   cp .env.example .env
   ```
3. Edit `.env` with your configuration (database credentials, secrets, etc.)
4. Start the services:
   ```bash
   docker-compose up -d
   ```
5. Access the application at `https://your-domain.com`

### Manual Installation

1. Install dependencies:
   ```bash
   pip install poetry
   poetry install
   ```

2. Set up the database:
   ```bash
   createdb rbox
   ```

3. Configure environment variables in `.env`

4. Run database migrations:
   ```bash
   poetry run rbox --migrate
   ```

5. Start the application:
   ```bash
   poetry run rbox --host 0.0.0.0 --port 8000
   ```

## Configuration

RBox uses environment variables for configuration. Key settings include:

- `DATABASE_URL`: PostgreSQL connection string
- `REDIS_URL`: Redis connection URL
- `SECRET_KEY`: JWT signing key (generate a secure random key)
- `DOMAIN_NAME`: Your domain for HTTPS certificates
- `SMTP_*`: Email server configuration
- `STRIPE_*`: Payment processing credentials
- `STORAGE_PATH`: Local storage directory path

See `.env.example` for a complete list of configuration options.

## Usage

### Web Interface
Access the web application through your browser. The interface provides:
- File browser with drag-and-drop upload
- Folder management and navigation
- Search and filtering capabilities
- User profile and settings
- Administrative controls (for admins)

### API Usage
RBox provides a comprehensive REST API. Example requests:

```bash
# Upload a file
curl -X POST "https://your-domain.com/api/files/upload" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@example.txt"

# List files
curl -X GET "https://your-domain.com/api/files/" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Create a share link
curl -X POST "https://your-domain.com/api/shares/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"file_id": 123, "expires_at": "2024-12-31T23:59:59Z"}'
```

### WebDAV Access
Mount RBox as a network drive using WebDAV:
```
https://your-domain.com/webdav/
```

### SFTP Access
Connect via SFTP using your RBox credentials on port 22.

## Deployment

### Production Deployment
1. Set up a reverse proxy (Nginx included in docker-compose.yml)
2. Configure SSL certificates (automatic with Let's Encrypt)
3. Set up database backups
4. Configure monitoring and logging
5. Scale as needed with load balancers

### Docker Compose Services
- **app**: FastAPI application with Gunicorn
- **db**: PostgreSQL database
- **redis**: Caching and session storage
- **nginx**: Reverse proxy and static file serving
- **certbot**: SSL certificate management

### Environment Variables
Configure all services through the `.env` file. Sensitive data is automatically loaded and validated.

## Security Considerations

- Change default secrets in production
- Enable HTTPS with valid certificates
- Regularly update dependencies
- Monitor access logs
- Implement backup strategies
- Use strong passwords and enable 2FA

## Troubleshooting

### Common Issues
- **Database connection errors**: Verify DATABASE_URL configuration
- **File upload failures**: Check storage permissions and quotas
- **Email not sending**: Confirm SMTP settings
- **WebDAV connection issues**: Ensure proper authentication

### Logs
Application logs are available in the Docker containers:
```bash
docker-compose logs app
```

## Support

For issues and questions:
- Check the troubleshooting section
- Review configuration examples
- Consult the API documentation at `/docs` when running

## License

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