cjw/Oxicloud
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

docs: rewrite README with full feature list, comparison table & docs index

Browse Source 
- Add tagline and CI/Rust/Docker badges
- Add OxiCloud vs NextCloud comparison table with real metrics
  (image size, RAM, cold start, dedup, DB pools, protocols)
- List all implemented features categorised: Storage, Protocols,
  Security, Infrastructure
- Add Client Setup table (WebDAV/CalDAV/CardDAV/WOPI URLs)
- Add Configuration reference table
- Add Documentation index linking all 35 doc pages
- Update Architecture diagram with protocol layer
- Add Project stats (170 files, ~50K LoC, 112 tests)
- Update Quick Start: Docker first, correct Rust version (1.93+)
- Replace outdated 'What's Next' with accurate Roadmap
- Fix language count: 9 (was 3)
This commit is contained in:
Dionisio
2026-02-25 11:29:30 +01:00
parent 6479da35f2
commit 7bfe411661
1 changed files with 200 additions and 69 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+200 -69
View File
@@ -2,128 +2,259 @@
<img src="static/oxicloud-logo.svg" alt="OxiCloud" width="375" /> <img src="static/oxicloud-logo.svg" alt="OxiCloud" width="375" />
</p> </p>
<h3 align="center">Self-hosted cloud storage, calendar &amp; contacts — blazingly fast.</h3>
<div align="center"> <div align="center">
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=for-the-badge)](https://opensource.org/licenses/MIT) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=for-the-badge)](https://opensource.org/licenses/MIT)
[![Latest Release](https://img.shields.io/github/release/diocrafts/OxiCloud.svg?style=for-the-badge)](https://github.com/diocrafts/OxiCloud/releases) [![Latest Release](https://img.shields.io/github/release/diocrafts/OxiCloud.svg?style=for-the-badge)](https://github.com/diocrafts/OxiCloud/releases)
[![CI](https://img.shields.io/github/actions/workflow/status/diocrafts/OxiCloud/ci.yml?branch=main&style=for-the-badge&label=CI)](https://github.com/diocrafts/OxiCloud/actions/workflows/ci.yml)
[![Rust](https://img.shields.io/badge/Rust-1.93+-orange?style=for-the-badge&logo=rust)](https://www.rust-lang.org/)
[![Docker Image Size](https://img.shields.io/docker/image-size/diocrafts/oxicloud?style=for-the-badge&logo=docker)](https://hub.docker.com/r/diocrafts/oxicloud)
[![GitHub Stars](https://img.shields.io/github/stars/diocrafts/OxiCloud?style=for-the-badge&logo=github)](https://github.com/diocrafts/OxiCloud/stargazers) [![GitHub Stars](https://img.shields.io/github/stars/diocrafts/OxiCloud?style=for-the-badge&logo=github)](https://github.com/diocrafts/OxiCloud/stargazers)
[![GitHub Issues](https://img.shields.io/github/issues/diocrafts/OxiCloud?style=for-the-badge)](https://github.com/diocrafts/OxiCloud/issues) [![GitHub Issues](https://img.shields.io/github/issues/diocrafts/OxiCloud?style=for-the-badge)](https://github.com/diocrafts/OxiCloud/issues)
[![GitHub Forks](https://img.shields.io/github/forks/diocrafts/OxiCloud?style=for-the-badge&logo=github)](https://github.com/diocrafts/OxiCloud/network/members)
[![Last Commit](https://img.shields.io/github/last-commit/diocrafts/OxiCloud?style=for-the-badge)](https://github.com/diocrafts/OxiCloud/commits/main) [![Last Commit](https://img.shields.io/github/last-commit/diocrafts/OxiCloud?style=for-the-badge)](https://github.com/diocrafts/OxiCloud/commits/main)
</div> </div>
## A fast, simple alternative to NextCloud <br/>
NextCloud was too slow on my home server. So I built OxiCloud: a file storage system written in Rust that runs on minimal hardware and stays out of your way. NextCloud was too slow on my home server. So I built OxiCloud — a complete cloud platform written in Rust that runs on minimal hardware and stays out of your way.
![OxiCloud Dashboard](doc/images/Captura%20de%20pantalla%202025-03-23%20230739.png) ![OxiCloud Dashboard](doc/images/Captura%20de%20pantalla%202025-03-23%20230739.png)
## Why OxiCloud? <!-- TODO: add animated GIF/demo here -->
| Feature | What you get | ---
|---------|--------------|
| **Low resources** | Runs on 512MB RAM. No PHP, no bloat. | ## OxiCloud vs NextCloud
| **Fast** | Rust with LTO optimization. Sub-second responses. |
| **Clean UI** | Works on desktop and mobile. No clutter. | | Metric | OxiCloud | NextCloud |
| **Easy setup** | One binary, one database, done. | |--------|----------|-----------|
| **Multi-language** | English, Spanish and Persian out of the box. | | **Language** | Rust (compiled, zero-cost abstractions) | PHP (interpreted) |
| **Docker image** | ~40 MB (Alpine, static binary) | ~1 GB+ (Apache + PHP + modules) |
| **Idle RAM** | ~30–50 MB | ~250–512 MB |
| **Cold start** | < 1 s | 5–15 s |
| **CPU at idle** | ~0 % | 1–5 % (cron, background jobs) |
| **Min. hardware** | 1 vCPU / 512 MB RAM | 2 vCPU / 2 GB RAM (recommended) |
| **Concurrent uploads** | Parallel chunked (TUS-like), async I/O | Sequential PHP workers |
| **File dedup** | SHA-256 content-addressable, ref-counting | None (each user = full copy) |
| **DB connections** | Dual pool (user + maintenance) | Single pool, background jobs compete |
| **LTO + PGO** | Fat LTO, codegen-units=1, opt-level=3 | N/A (interpreted) |
| **Dependencies** | Single binary + PostgreSQL | PHP, Apache/Nginx, Redis, Cron, … |
| **WebDAV** | Built-in (RFC 4918, PROPFIND streaming) | Built-in |
| **CalDAV / CardDAV** | Built-in | Via apps |
| **WOPI (Office editing)** | Built-in (Collabora / OnlyOffice) | Via apps |
| **OIDC / SSO** | Built-in (Keycloak, Authentik, …) | Via apps |
> **Note:** NextCloud is a mature, feature-rich ecosystem. OxiCloud targets users who prioritise raw performance, simplicity, and low resource usage over plugin breadth.
---
## Features
### Storage & Files
- **Upload / download / organise** — drag-and-drop, multi-file, grid & list views
- **Chunked uploads** — TUS-like protocol, parallel chunks, resumable, MD5 integrity
- **File deduplication** — SHA-256 content-addressable blobs with automatic ref-counting
- **Adaptive compression** — zstd / gzip selected per MIME type
- **Trash bin** — soft-delete, restore, auto-purge by retention policy
- **Favourites & recent files**
- **Full-text search** — by name, type, date range, size, recursive subtree (ltree)
- **MIME magic-byte detection** — `infer` crate, not just extension guessing
- **Inline preview** — images, PDF, text, audio & video player modal
- **Thumbnails & transcoding** — WebP / AVIF on-the-fly via `image` crate
### Protocols
- **WebDAV** — RFC 4918, streaming PROPFIND, locking, compatible with all major clients
- **CalDAV** — calendar sync (Thunderbird, GNOME Calendar, iOS, DAVx⁵, …)
- **CardDAV** — contacts sync with vCard support
- **WOPI** — edit Office docs in Collabora Online or OnlyOffice
- **REST API** — complete JSON API for all operations
### Security & Auth
- **JWT authentication** with refresh tokens
- **Argon2id** password hashing
- **OIDC / SSO** — Keycloak, Authentik, Authelia, Google, Azure AD…
- **Role-based access** — admin / user, per-folder permissions
- **Storage quotas** per user
- **Shared links** with optional password protection
### Infrastructure
- **Single binary** — no runtime, no interpreter, no framework overhead
- **~40 MB Docker image** (Alpine)
- **Dual DB pool** — dedicated maintenance pool so background tasks never starve user queries
- **LTO-optimised release** — fat LTO, 1 codegen-unit, `opt-level = 3`, stripped
- **Write-behind caching** (moka) — sub-millisecond hot reads
- **112 automated tests** — `cargo test` on every push (CI)
- **9 languages** — EN, ES, DE, FR, IT, PT, NL, ZH, FA
---
## Quick Start ## Quick Start
You need Rust 1.70+, Cargo, and PostgreSQL 13+. ### Docker (recommended)
```bash ```bash
git clone https://github.com/DioCrafts/oxicloud.git git clone https://github.com/DioCrafts/oxicloud.git
cd oxicloud cd oxicloud
# Set up your database connection # Copy and optionally edit environment
echo "DATABASE_URL=postgres://username:password@localhost/oxicloud" > .env
# Build and run
cargo build --release
cargo run --bin migrate --features migrations
cargo run --release
```
Open `http://localhost:8086` in your browser.
### Docker (alternative)
```bash
# Copy example environment file and customize
cp example.env .env cp example.env .env
# Edit .env with your settings (optional - defaults work for quick testing)
docker compose up -d docker compose up -d
``` ```
That's it. The app runs on port 8086. Open **http://localhost:8086**. That's it.
### From source
Requires **Rust 1.93+** and **PostgreSQL 13+**.
```bash
git clone https://github.com/DioCrafts/oxicloud.git
cd oxicloud
# Configure database
echo "DATABASE_URL=postgres://user:pass@localhost/oxicloud" > .env
# Build optimised binary
cargo build --release
# Run migrations and start
cargo run --bin migrate --features migrations
cargo run --release
```
---
## Client Setup
OxiCloud speaks standard protocols — any WebDAV / CalDAV / CardDAV client works:
| Client | Protocol | URL |
|--------|----------|-----|
| Windows Explorer | WebDAV | `http://host:8086/webdav/` |
| macOS Finder | WebDAV | `http://host:8086/webdav/` |
| Nautilus / Dolphin | WebDAV | `dav://host:8086/webdav/` |
| Thunderbird (calendar) | CalDAV | `http://host:8086/caldav/` |
| Thunderbird (contacts) | CardDAV | `http://host:8086/carddav/` |
| DAVx⁵ (Android) | CalDAV + CardDAV | `http://host:8086/` |
| GNOME Calendar | CalDAV | `http://host:8086/caldav/` |
| GNOME Contacts | CardDAV | `http://host:8086/carddav/` |
| Collabora / OnlyOffice | WOPI | See [WOPI docs](doc/wopi-integration.md) |
For detailed setup guides: [WebDAV](doc/webdav-integration-guide.md) · [CalDAV](doc/caldav-technical-spec.md) · [CardDAV](doc/carddav-technical-spec.md) · [OIDC/SSO](doc/oidc-integration.md)
---
## Architecture ## Architecture
OxiCloud uses Clean Architecture with four layers: Clean / Hexagonal architecture — each layer depends only on the one below:
``` ```
┌─────────────────────────────────────────┐ ┌───────────────────────────────────────────────────────────────┐
│ Interfaces │ API routes, handlers │ │ Interfaces │ REST API, WebDAV, CalDAV, CardDAV, WOPI │
├─────────────────────────────────────────┤ ├───────────────────────────────────────────────────────────────┤
│ Application │ Use cases, services │ │ Application │ Use cases, DTOs, port definitions │
├─────────────────────────────────────────┤ ├───────────────────────────────────────────────────────────────┤
│ Domain │ Business logic │ │ Domain │ Entities, business rules, repository traits │
├─────────────────────────────────────────┤ ├───────────────────────────────────────────────────────────────┤
│ Infrastructure│ Database, filesystem │ │ Infrastructure│ PostgreSQL, filesystem, caching, auth │
└─────────────────────────────────────────┘ └───────────────────────────────────────────────────────────────┘
``` ```
Each layer only talks to the one below it. You can swap out the database or add new API endpoints without touching business logic. Swap the database, add a new protocol, or change auth — without touching business logic.
For a deep dive: [Internal Architecture](doc/internal-architecture.md) · [Caching](doc/caching-architecture.md) · [DB Transactions](doc/database-transactions.md)
---
## Configuration
All config via environment variables (see [`example.env`](example.env)):
| Variable | Default | Description |
|----------|---------|-------------|
| `OXICLOUD_STORAGE_PATH` | `./storage` | Root directory for file storage |
| `OXICLOUD_SERVER_PORT` | `8086` | HTTP listen port |
| `OXICLOUD_DB_CONNECTION_STRING` | — | PostgreSQL connection string |
| `OXICLOUD_JWT_SECRET` | random | Token signing key (set in production!) |
| `OXICLOUD_OIDC_ENABLED` | `false` | Enable OpenID Connect SSO |
| `OXICLOUD_WOPI_ENABLED` | `false` | Enable Collabora / OnlyOffice editing |
| `OXICLOUD_ENABLE_AUTH` | `true` | Toggle authentication |
| `OXICLOUD_ENABLE_TRASH` | `true` | Toggle trash / recycle bin |
Full reference: [`example.env`](example.env) · [Deployment guide](doc/deployment.md) · [OIDC examples](doc/oidc-config-examples.md)
---
## Development ## Development
```bash ```bash
cargo build # Build cargo build # Dev build
cargo run # Run locally cargo run # Run locally
cargo test # Run tests cargo test --workspace # 112 tests
cargo clippy # Lint cargo clippy -- -D warnings # Lint (zero warnings policy)
cargo fmt # Format cargo fmt --all --check # Format check
RUST_LOG=debug cargo run # Debug logging
# For debugging
RUST_LOG=debug cargo run
``` ```
## Current Features ### Project stats
- File upload, download, and organization | Metric | Value |
- Folder management with drag-and-drop |--------|-------|
- Trash bin with restore functionality | Rust source files | 170 |
- User authentication with JWT | Lines of code | ~50 000 |
- Personal folders per user | Automated tests | 112 |
- File deduplication | Documentation pages | 35 |
- Write-behind cache for fast uploads
- Search across files and folders
- Favorites and recent files
- Responsive grid/list views
## What's Next ---
I'm working on these when I have time: ## Documentation
- File sharing via links Extensive docs live in [`doc/`](doc/):
- WebDAV for desktop sync
- Basic versioning
- Mobile app improvements
Check [TODO-LIST.md](TODO-LIST.md) for the full list. | Topic | Link |
|-------|------|
| Deployment & Docker | [deployment.md](doc/deployment.md) |
| WebDAV integration | [webdav-integration-guide.md](doc/webdav-integration-guide.md) |
| CalDAV / CardDAV | [caldav-technical-spec.md](doc/caldav-technical-spec.md) · [carddav-technical-spec.md](doc/carddav-technical-spec.md) |
| OIDC / SSO setup | [oidc-integration.md](doc/oidc-integration.md) · [oidc-config-examples.md](doc/oidc-config-examples.md) |
| WOPI (Office editing) | [wopi-integration.md](doc/wopi-integration.md) |
| Chunked uploads | [chunked-uploads.md](doc/chunked-uploads.md) |
| Deduplication | [deduplication.md](doc/deduplication.md) |
| Search | [search.md](doc/search.md) |
| Caching architecture | [caching-architecture.md](doc/caching-architecture.md) |
| Storage quotas | [storage-quotas.md](doc/storage-quotas.md) |
| Trash / recycle bin | [trash-feature-summary.md](doc/trash-feature-summary.md) |
| Internationalisation | [i18n.md](doc/i18n.md) |
| Internal architecture | [internal-architecture.md](doc/internal-architecture.md) |
---
## Roadmap
Check [TODO-LIST.md](TODO-LIST.md) for the full roadmap. Highlights:
- [ ] File versioning & diff viewer
- [ ] End-to-end encryption
- [ ] Desktop sync client (Rust)
- [ ] Android / iOS app
- [ ] OCR & intelligent tagging
- [ ] Automated workflows
---
## Contributing ## Contributing
The project is early stage. There's plenty to improve. The project is actively developed. Contributions welcome!
Read [CONTRIBUTING.md](CONTRIBUTING.md) before submitting a PR. Follow the [Code of Conduct](CODE_OF_CONDUCT.md). Read [CONTRIBUTING.md](CONTRIBUTING.md) before submitting a PR. Follow the [Code of Conduct](CODE_OF_CONDUCT.md).
## License ## License
MIT. See [LICENSE](LICENSE). MIT — see [LICENSE](LICENSE).
--- ---
@@ -141,4 +272,4 @@ MIT. See [LICENSE](LICENSE).
--- ---
Questions? Open an issue. Want to help? PRs welcome. Questions? [Open an issue](https://github.com/DioCrafts/OxiCloud/issues). Want to help? PRs welcome.