{"id":30850177,"url":"https://github.com/anddsdev/cloudlet","last_synced_at":"2025-09-07T05:07:26.710Z","repository":{"id":310598257,"uuid":"1039386275","full_name":"anddsdev/cloudlet","owner":"anddsdev","description":"A lightweight, self-hosted file storage service designed to be simple, fast, and easy to use.","archived":false,"fork":false,"pushed_at":"2025-08-26T04:31:42.000Z","size":325,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-26T06:19:50.368Z","etag":null,"topics":["api","cloud","docker","docker-compose","go","golang","self-hosted"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/anddsdev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-17T05:29:42.000Z","updated_at":"2025-08-26T04:31:46.000Z","dependencies_parsed_at":"2025-08-19T05:39:56.265Z","dependency_job_id":"4bd96303-d197-4ca8-81ff-e34508ab0671","html_url":"https://github.com/anddsdev/cloudlet","commit_stats":null,"previous_names":["anddsdev/cloudlet"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/anddsdev/cloudlet","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anddsdev%2Fcloudlet","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anddsdev%2Fcloudlet/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anddsdev%2Fcloudlet/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anddsdev%2Fcloudlet/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/anddsdev","download_url":"https://codeload.github.com/anddsdev/cloudlet/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anddsdev%2Fcloudlet/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273997155,"owners_count":25204479,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-07T02:00:09.463Z","response_time":67,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","cloud","docker","docker-compose","go","golang","self-hosted"],"created_at":"2025-09-07T05:07:24.984Z","updated_at":"2025-09-07T05:07:26.695Z","avatar_url":"https://github.com/anddsdev.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ☁️ Cloudlet\n\n[![Go Version](https://img.shields.io/badge/Go-1.23.4-blue.svg)](https://golang.org/)\n[![License](https://img.shields.io/badge/license-AGPL-green.svg)](LICENSE)\n[![Build Status](https://img.shields.io/badge/build-passing-brightgreen.svg)](https://github.com/anddsdev/cloudlet)\n\nA lightweight, self-hosted file storage service designed to be simple, fast, and easy to use. Cloudlet provides a minimalist alternative to complex file management systems like Nextcloud, focusing on essential file operations without unnecessary overhead.\n\n## ✨ Features\n\n- 🌐 **Modern Web Interface**: Beautiful, responsive React-based dashboard with drag \u0026 drop support\n- 📁 **File Management**: Upload, download, and organize files through both web UI and API\n- 📂 **Directory Operations**: Create, navigate, and manage folder structures\n- 🔄 **File Operations**: Move, rename, and delete files and directories\n  - Smart deletion with recursive directory support\n  - Confirmation dialogs for destructive operations\n  - Atomic transactions for data consistency\n- 📊 **Statistics**: View file information, directory sizes, and item counts\n- 🗂️ **Multiple File Types**: Support for various file formats with MIME type detection\n- ⚡ **High Performance**: Built with Go for speed and efficiency\n- 🛡️ **Advanced Security**: \n  - Path validation with directory traversal protection\n  - SQL injection prevention with SafeQueryBuilder\n  - Dangerous file detection and validation\n  - Enhanced input validation and sanitization\n- 🚀 **Multiple Upload Options**:\n  - Traditional single file uploads\n  - Multiple file upload with batch processing\n  - Streaming uploads for large files\n  - Chunked uploads with progress tracking\n  - Concurrent and sequential processing strategies\n- 🔒 **Atomic Operations**: Thread-safe file operations with data integrity guarantees\n- 🐳 **Easy Deployment**: Simple configuration and deployment\n- 💾 **SQLite Database**: Lightweight database with optimized queries\n- 🌐 **REST API**: Complete RESTful API for integration\n- 🧪 **Comprehensive Testing**: Extensive test coverage with benchmarks\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n- Go 1.23.4 or later\n- SQLite3 (included)\n\n### Installation\n\n1. **Clone the repository**\n\n   ```bash\n   git clone https://github.com/anddsdev/cloudlet.git\n   cd cloudlet\n   ```\n\n2. **Build the application**\n\n   ```bash\n   go mod download\n   go build -o cloudlet ./cmd/cloudlet\n   ```\n\n3. **Run Cloudlet**\n   ```bash\n   ./cloudlet\n   ```\n\nThe server will start on `http://localhost:8080` by default and will serve the web interface at the root path.\n\n### Frontend Development\n\nTo run the React frontend in development mode:\n\n1. **Navigate to the client directory**\n   ```bash\n   cd client\n   ```\n\n2. **Install dependencies**\n   ```bash\n   bun install\n   ```\n\n3. **Start the development server**\n   ```bash\n   bun run dev\n   ```\n\nThe frontend will start on `http://localhost:5173` and will proxy API requests to the backend on port 8080.\n\n4. **Build for production**\n\n   Using Make (builds both client and backend):\n   ```bash\n   make build-prod\n   ```\n\n   Or build individually:\n   ```bash\n   make build-client  # Builds React client to web/\n   make build         # Builds Go backend\n   ```\n\n   Or using npm/bun directly (client only):\n   ```bash\n   cd client \u0026\u0026 bun run build\n   ```\n\nThe built client files are output to `web/` directory to be served by the Go backend.\n\n### Using Docker\n\nBuild and run with Docker:\n```bash\n# Build Docker image (includes both client and backend)\nmake docker-build\n# or\ndocker build -t cloudlet:latest .\n\n# Run container\nmake docker-run\n# or\ndocker run -d \\\n  --name cloudlet \\\n  -p 8080:8080 \\\n  -v ./data:/app/data \\\n  cloudlet:latest\n```\n\n## ⚙️ Configuration\n\nCloudlet uses a YAML configuration file located at `config/config.yaml`:\n\n```yaml\nserver:\n  port: 8080\n  max_memory: 32000000 # 32MB\n  max_file_size: 100000000 # 100MB\n  storage:\n    path: ./data/storage\n  timeout:\n    read_timeout: 30\n    write_timeout: 30\n    idle_timeout: 60\n    max_header_bytes: 1024\n    read_header_timeout: 10\n  \n  upload:\n    max_files_per_request: 50\n    max_total_size_per_request: 524288000 # 500MB in bytes\n    allow_partial_success: true        \n    enable_batch_processing: true      \n    batch_size: 10          \n    max_concurrent_uploads: 3\n    streaming_threshold: 10485760 # 10MB in bytes\n    validate_before_upload: true\n    enable_progress_tracking: false\n    cleanup_on_failure: false    \n    rate_limit_per_minute: 100\n\ndatabase:\n  driver: sqlite3\n  dsn: ./data/cloudlet.db\n  max_conn: 10\n```\n\n### Configuration Options\n\n| Option                                      | Description                                | Default              |\n| ------------------------------------------- | ------------------------------------------ | -------------------- |\n| `server.port`                               | HTTP server port                           | `8080`               |\n| `server.max_memory`                         | Maximum memory for file uploads            | `32MB`               |\n| `server.max_file_size`                      | Maximum file size allowed                  | `100MB`              |\n| `server.storage.path`                       | Physical storage directory                 | `./data/storage`     |\n| `server.timeout.read_timeout`               | HTTP read timeout (seconds)                | `30`                 |\n| `server.timeout.write_timeout`              | HTTP write timeout (seconds)               | `30`                 |\n| `server.timeout.idle_timeout`               | HTTP idle timeout (seconds)                | `60`                 |\n| `server.upload.max_files_per_request`       | Maximum files per upload request           | `50`                 |\n| `server.upload.max_total_size_per_request`  | Maximum total size per request             | `500MB`              |\n| `server.upload.allow_partial_success`       | Allow partial upload success               | `true`               |\n| `server.upload.enable_batch_processing`     | Enable batch processing                    | `true`               |\n| `server.upload.batch_size`                  | Batch size for processing                  | `10`                 |\n| `server.upload.max_concurrent_uploads`      | Maximum concurrent uploads                 | `3`                  |\n| `server.upload.streaming_threshold`         | File size threshold for streaming          | `10MB`               |\n| `server.upload.validate_before_upload`      | Validate files before upload               | `true`               |\n| `server.upload.enable_progress_tracking`    | Enable upload progress tracking            | `false`              |\n| `server.upload.cleanup_on_failure`          | Clean up files on upload failure          | `false`              |\n| `server.upload.rate_limit_per_minute`       | Upload rate limit per minute               | `100`                |\n| `database.dsn`                              | SQLite database file path                  | `./data/cloudlet.db` |\n| `database.max_conn`                         | Maximum database connections               | `10`                 |\n\n## 📖 API Documentation\n\n### Endpoints\n\n#### Files\n\n| Method   | Endpoint                        | Description                      |\n| -------- | ------------------------------- | -------------------------------- |\n| `GET`    | `/api/v1/files`                 | List files in root directory     |\n| `GET`    | `/api/v1/files/{path}`          | List files in specific directory |\n| `POST`   | `/api/v1/upload`                | Upload single file               |\n| `POST`   | `/api/v1/upload/multiple`       | Upload multiple files            |\n| `POST`   | `/api/v1/upload/batch`          | Batch upload with validation     |\n| `POST`   | `/api/v1/upload/stream`         | Streaming upload for large files |\n| `POST`   | `/api/v1/upload/chunked`        | Chunked upload with progress     |\n| `POST`   | `/api/v1/upload/progress`       | Upload with progress tracking    |\n| `GET`    | `/api/v1/download/{path}`       | Download a file                  |\n| `DELETE` | `/api/v1/files/{path}`          | Delete a file or directory       |\n\n#### Directories\n\n| Method | Endpoint                     | Description             |\n| ------ | ---------------------------- | ----------------------- |\n| `POST` | `/api/v1/directories`        | Create a new directory  |\n| `GET`  | `/api/v1/directories/{path}` | List directory contents |\n\n#### Operations\n\n| Method | Endpoint         | Description                 |\n| ------ | ---------------- | --------------------------- |\n| `POST` | `/api/v1/move`   | Move files or directories   |\n| `POST` | `/api/v1/rename` | Rename files or directories |\n\n#### Health\n\n| Method | Endpoint  | Description           |\n| ------ | --------- | --------------------- |\n| `GET`  | `/health` | Health check endpoint |\n\n### Request/Response Examples\n\n#### Upload a single file\n\n```bash\ncurl -X POST \\\n  -F \"file=@example.txt\" \\\n  -F \"path=/\" \\\n  http://localhost:8080/api/v1/upload\n```\n\n#### Upload multiple files\n\n```bash\ncurl -X POST \\\n  -F \"files=@file1.txt\" \\\n  -F \"files=@file2.txt\" \\\n  -F \"path=/\" \\\n  http://localhost:8080/api/v1/upload/multiple\n```\n\n#### Streaming upload for large files\n\n```bash\ncurl -X POST \\\n  -F \"file=@largefile.zip\" \\\n  -F \"path=/\" \\\n  http://localhost:8080/api/v1/upload/stream\n```\n\n#### Create a directory\n\n```bash\ncurl -X POST \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"name\": \"documents\", \"parent_path\": \"/\"}' \\\n  http://localhost:8080/api/v1/directories\n```\n\n#### List directory contents\n\n```bash\ncurl http://localhost:8080/api/v1/files/documents\n```\n\nResponse:\n\n```json\n{\n  \"path\": \"/documents\",\n  \"parent_path\": \"/\",\n  \"files\": [...],\n  \"directories\": [...],\n  \"total_files\": 5,\n  \"total_directories\": 2,\n  \"total_size\": 1048576,\n  \"breadcrumbs\": [...]\n}\n```\n\n#### Delete files and directories\n\nDelete a single file:\n```bash\ncurl -X DELETE http://localhost:8080/api/v1/files/document.txt\n```\n\nDelete an empty directory:\n```bash\ncurl -X DELETE http://localhost:8080/api/v1/files/empty-folder\n```\n\nDelete a directory and all its contents recursively:\n```bash\ncurl -X DELETE \"http://localhost:8080/api/v1/files/folder-with-content?recursive=true\"\n```\n\nResponse for successful deletion:\n```json\n{\n  \"success\": true,\n  \"message\": \"File deleted successfully\",\n  \"path\": \"/folder-with-content\"\n}\n```\n\nResponse for non-empty directory without recursive parameter:\n```json\n{\n  \"error\": true,\n  \"message\": \"Directory not empty\",\n  \"status\": 409\n}\n```\n\n## 🏗️ Architecture\n\nCloudlet follows clean architecture principles with clear separation of concerns:\n\n```\ncloudlet/\n├── cmd/cloudlet/           # Application entry point\n├── config/                 # Configuration management\n├── internal/\n│   ├── database/          # Database utilities and SafeQueryBuilder\n│   ├── handlers/          # HTTP handlers (including specialized upload handlers)\n│   ├── models/            # Data models\n│   ├── repository/        # Data access layer\n│   ├── security/          # Security components (PathValidator)\n│   ├── server/            # HTTP server and routing\n│   ├── services/          # Business logic\n│   ├── storage/           # AtomicFileOperations\n│   ├── transaction/       # TransactionManager\n│   └── utils/             # Utility functions and validators\n├── client/                # React frontend application\n│   ├── src/\n│   │   ├── components/    # React components (Dashboard, FileList, etc.)\n│   │   ├── services/      # API communication layer\n│   │   └── lib/           # Utilities and helpers\n├── web/                   # Built frontend assets (served by Go)\n├── data/                  # SQLite database\n└── storage/               # File storage directory\n```\n\n### Key Components\n\n- **Handlers**: Process HTTP requests and responses with specialized upload handlers\n- **Services**: Contain business logic and orchestrate operations\n  - **FileService**: Core file management with atomic operations\n  - **MultipleUploadService**: Handles batch and concurrent uploads\n  - **StorageService**: Physical file operations with atomic guarantees\n- **Repository**: Handle database operations with SQLite and SafeQueryBuilder\n- **Security**: \n  - **PathValidator**: Prevents directory traversal attacks\n  - **SafeQueryBuilder**: SQL injection prevention\n  - **Validator**: Enhanced input validation and sanitization\n- **Storage**: **AtomicFileOperations**: Thread-safe file operations\n- **Transaction**: **TransactionManager**: Ensures data consistency\n- **Models**: Define data structures and API contracts\n\n#### Frontend Architecture\n\n- **React Components**: Modern functional components with hooks\n  - **Dashboard**: Main interface with file management\n  - **FileList**: Table view with file operations\n  - **FileUploadZone**: Drag \u0026 drop upload with progress\n  - **Modals**: Confirmation dialogs for destructive operations\n- **Services Layer**: API communication with strategy pattern\n  - **uploadStrategy**: Smart upload method selection\n  - **fileService**: Core file operations API calls\n- **UI Components**: shadcn/ui for consistent design system\n- **State Management**: React hooks with real-time notifications\n\n## 🔐 Security \u0026 Performance\n\n### Security Features\n\n- **Path Validation**: Comprehensive protection against directory traversal attacks\n- **SQL Injection Prevention**: SafeQueryBuilder ensures all database queries are secure\n- **File Validation**: Detection and prevention of dangerous file uploads\n- **Input Sanitization**: Enhanced validation across all endpoints\n- **Atomic Operations**: Thread-safe file operations prevent race conditions\n\n### Performance Optimizations\n\n- **Streaming Uploads**: Handle large files efficiently without memory overhead\n- **Chunked Processing**: Break large operations into manageable chunks\n- **Concurrent Operations**: Parallel processing for multiple file operations\n- **Batch Processing**: Optimize multiple file uploads with intelligent batching\n- **Transaction Management**: Ensure database consistency with proper rollback capabilities\n\n### Testing \u0026 Quality\n\n- **Comprehensive Test Suite**: Over 5,800 lines of test coverage\n- **Benchmark Tests**: Performance validation for critical operations\n- **Mock Services**: Robust testing infrastructure\n- **Edge Case Validation**: Security testing against various attack vectors\n\n## 🤝 Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.\n\n### Development Setup\n\n1. **Fork the repository**\n2. **Clone your fork**\n   ```bash\n   git clone https://github.com/yourusername/cloudlet.git\n   ```\n3. **Create a feature branch**\n   ```bash\n   git checkout -b feature/amazing-feature\n   ```\n4. **Make your changes**\n5. **Commit your changes**\n   ```bash\n   git commit -m \"Add amazing feature\"\n   ```\n6. **Push to your branch**\n   ```bash\n   git push origin feature/amazing-feature\n   ```\n7. **Open a Pull Request**\n\n### Code Style\n\n**Backend (Go):**\n- Follow Go conventions and use `gofmt`\n- Write clear, descriptive commit messages\n- Add tests for new features\n- Update documentation as needed\n\n**Frontend (React/TypeScript):**\n- Use TypeScript for type safety\n- Follow React hooks patterns\n- Use shadcn/ui components for consistency\n- Implement proper error handling with user feedback\n- Write responsive and accessible interfaces\n\n## 📋 Roadmap\n\n- [x] **Web UI interface** - Modern React dashboard with drag \u0026 drop uploads\n  - [x] File and directory management\n  - [x] Smart upload strategies (single, multiple, batch, stream)\n  - [x] Recursive directory deletion with confirmation\n  - [x] Real-time progress tracking and notifications\n- [ ] User authentication and authorization\n- [ ] File sharing with expirable links\n- [ ] File versioning\n- [ ] Bulk operations (move, copy multiple files)\n- [ ] File search functionality\n- [x] Docker container support\n- [ ] Cloud storage backends (S3, etc.)\n- [ ] File encryption\n- [ ] API rate limiting\n\n## 🐛 Issues and Support\n\nIf you encounter any issues or have questions:\n\n1. Check the [Issues](https://github.com/anddsdev/cloudlet/issues) page\n2. Search for existing issues before creating a new one\n3. Provide detailed information about your environment and the problem\n4. Include steps to reproduce the issue\n\n## 📄 License\n\nThis project is licensed under the AGPL-3.0 License - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n**Backend:**\n- Built with [Go](https://golang.org/)\n- Database powered by [SQLite](https://sqlite.org/)\n- Configuration with [gopkg.in/yaml.v3](https://gopkg.in/yaml.v3)\n\n**Frontend:**\n- [React](https://reactjs.org/) - UI framework\n- [TypeScript](https://www.typescriptlang.org/) - Type safety\n- [Tailwind CSS](https://tailwindcss.com/) - Styling framework\n- [shadcn/ui](https://ui.shadcn.com/) - Component library\n- [Vite](https://vitejs.dev/) - Build tool and dev server\n- [Lucide React](https://lucide.dev/) - Icon library\n- [React Dropzone](https://react-dropzone.js.org/) - Drag \u0026 drop uploads\n- [Sonner](https://sonner.emilkowal.ski/) - Toast notifications\n\n## 📬 Contact\n\n- GitHub: [@anddsdev](https://github.com/anddsdev)\n- Project Link: [https://github.com/anddsdev/cloudlet](https://github.com/anddsdev/cloudlet)\n\n---\n\n⭐ If you find Cloudlet useful, please consider giving it a star on GitHub!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fanddsdev%2Fcloudlet","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fanddsdev%2Fcloudlet","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fanddsdev%2Fcloudlet/lists"}