# 🌥️ Litecloud

Litecloud is a blazing fast, stupidly secure cloud storage application. Built on Rust and featuring industry standard encryption for all data that hits the server. While still at an early development stage, we consider the app ready for deployment for single user/small group 

## Features at a glance

- **Secure authentication** with JWT-based sessions
- **File encryption** using AES-256-GCM
- **Share files easily** with customizable access controls and expiration dates*
- **Full REST API** for building your own clients or automations
- **Modern web interface** built with React and TypeScript
- **Single binary deployment** — no complex setup required

## The tech behind the magic

### Backend Stack
- **Rust + Rocket**: For blazing-fast, memory-safe performance
- **AES-256-GCM encryption**: Your files are scrambled before they hit storage
- **JWT authentication**: Secure, stateless session management

### Frontend 
- **React + Vite + TypeScript**: Modern, type-safe user interface, with all the added benefits of vite
- **Tailwind CSS**: Clean, responsive design

## Why Rust? Why not just use Node.js?

Great question! While i have considered Node, rust seemed a much more reasonable choice for this scenario, given that, at capacity, we hope that the app won't budge even if a hundred users upload a bunch of big files all at the same time.

Here are the main points for why I chose it:

- **Memory safety without garbage collection** — no mysterious crashes or memory leaks, hence safer handling of encrypted files. 
- **Insanely good concurrency** — handle thousands of simultaneous uploads without breaking a sweat  
- **Zero-cost abstractions** — all the safety with none of the performance overhead
- **Type safety for encryption** — this really is a no-brainer for an app built with security in mind

Rocket framework adds the cherry on top with its elegant routing system and built-in request validation.

## How secure is "secure"?

We take this *security* thing quite seriously:

- **AES-256-GCM encryption**: The same encryption standard trusted by governments and militaries
- **On-pipe encryption**: Files are encrypted before they're written to your server's disk — even system administrators can't read your files without the keys
- **No plaintext storage**: Your original files exist only before you upload them and after you download them back on your machine
- **JWT-based auth**: Secure, industry-standard authentication tokens

## API-first design

Everything you can do in the web interface, you can do programmatically. The entire Litecloud feature set is available under the `/api` route, so you can:

- Build a mobile app that syncs with your Litecloud instance
- Create automated backup scripts
- Integrate file storage into your existing applications
- Build a command-line client for power users

*API documentation is coming as soon as all the routes are battle-tested*

## Getting started in 30 seconds

1. Clone the repository:
   ```bash
   git clone https://git.mercurio.moe/Mercury/litecloud.git
   cd litecloud
   ```

2. Fire it up:
   ```bash
   docker compose up --build
   ```

3. Open your browser to `http://localhost:8082` and create your account!

That's it! You now have your own private cloud storage running locally.

## Exposing to the internet (Production deployment)

Running locally is great for testing, but you'll probably want to access your files from anywhere. Here's how to properly expose Litecloud with SSL encryption:

### Option 1: Using Caddy (Recommended - Super Easy!)

Caddy automatically handles SSL certificates via Let's Encrypt. Create a `Caddyfile`:

```
your-domain.com {
    reverse_proxy localhost:8082
}
```

Then run Caddy:
```bash
caddy run
```

That's it! Caddy will automatically get SSL certificates and proxy requests to your Litecloud instance.

### Option 2: Using Nginx Proxy Manager (GUI-friendly)

If you prefer a web interface for managing your reverse proxy:

1. Set up [Nginx Proxy Manager](https://nginxproxymanager.com/) 
2. Create a new proxy host pointing to `ip:8082`
3. Enable SSL and let NPM handle the certificate generation
4. Configure any additional security headers you want

### Option 3: Traditional Nginx

For those who prefer manual configuration, here's a basic Nginx config:

```nginx
server {
    listen 443 ssl http2;
    server_name your-domain.com;
    
    ssl_certificate /path/to/your/certificate.crt;
    ssl_certificate_key /path/to/your/private.key;
    
    location / {
        proxy_pass http://ip:8082;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        
        # Important for file uploads
        client_max_body_size 5G;
    }
}
```

### Security considerations

When exposing to the internet:
- **Always use HTTPS** — your files are encrypted at rest, but you want them encrypted in transit too
- Consider **IP whitelisting** if you only access from specific locations
- Set up **fail2ban** to prevent brute force attacks on your login
- Regular **backups** of your encrypted file storage
- Keep your **Docker images updated** for security patches

## What's next?

-  Mobile app development
-  Comprehensive API documentation
-  File search and tagging
-  Client-side sync capabilities

## Contributing

Found a bug? Have a feature idea? We'd love your help! Check out our issues page or submit a pull request.

## License

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0). This means:

-  You can use, modify, and distribute this software freely
-  You can use it for commercial purposes
-  You must provide source code to users, or a way to get to this page (even if they access it over a local network)
-  Any modifications must also be open source under AGPL-3.0

The AGPL ensures that if you run a modified version of Litecloud as a service, your users have the right to access the source code. This keeps the project truly open and prevents proprietary forks from closing off improvements to the community.

See the [LICENSE](LICENSE) file for full details.

---

*Built with ❤️ and lots of ☕ by a solo developer who believes your files belong to you, not Big Tech.*