Edouard Vanbelle
2b52d233f0
`AzureBlobBackend` inherited the trait's `operation_not_supported`
default for `list_blob_hashes`, so every `backend_consistency` run on
Azure fell back to a per-row probe. That fallback walks `storage.blobs`
asking "are these bytes there", which structurally cannot find orphans:
bytes no row claims are invisible to anything starting from the
database, because you need a hash to ask about one and discovering
unknown hashes IS enumeration. Azure had half the coverage of local and
S3, in the direction that wastes space.
## Enumeration
The obstacle was the cursor contract. The caller advances ONE cursor
across both sides of the merge-join, feeding the same value to the
backend and to `WHERE hash > $1`, so the cursor IS a blob hash. S3
satisfies that with `StartAfter`. Azure has no equivalent on this SDK:
REST 2023-05-03 added `startFrom`, but `azure_storage_blobs` 0.21 never
sends it — `ListBlobs` exposes only prefix, delimiter, max_results and
an opaque marker that cannot be derived from a hash.
Resume rides on `prefix` instead. Names are `{hash[0..2]}/{hash}.blob`,
which partitions the container into 256 shards that are themselves in
hash order, so walking 00/…ff/ yields exactly the global order the
merge-join needs and a cursor names the shard to restart in.
Re-listing on resume is bounded by shard width rather than by the whole
container — the cost a client-side skip over a flat listing would pay on
every page. `marker` pages within one call and never escapes as the
cursor, the same treatment the S3 impl gives its continuation token.
One asymmetry against S3, deliberate: constraining to `{2-hex}/` means
foreign files outside that shape never reach `unknowns`. Safe in the
direction that matters — an orphan is a blob we wrote and stopped
referencing, so it always has the canonical name — and it buys O(N)
enumeration instead of O(N²/limit).
`hash_from_blob_name` mirrors S3's parser, shard-equals-prefix check
included: without it a mis-sharded name would round-trip to a
`blob_name` we never wrote, reporting a live blob no read path can find.
Tested for round-trip, for nine non-canonical shapes, and for the
ordering premise the merge-join rests on.
## Removing the fallback
With Azure enumerating, nothing shipped answers
`operation_not_supported`. The fallback's other stated justification —
mid-migration — never applied: it named a `MigrationBlobBackend` that
does not exist, and `SwappableBlobBackend::list_blob_hashes` forwards to
whatever is currently active, as do the Encrypted, Cached and Retry
wrappers.
What still reached it was a transient failure (auth blip, throttle,
network) relabelled as a capability limit, on a run that then read as
clean while having silently lost orphan coverage. So it was not merely
dead, it produced the wrong outcome — the only one it could. It also had
zero test coverage across 227 lines.
Now any `Err` from `list_blob_hashes` fails the run. That is louder than
an anomaly on a green run, which was the fallback's own goal. The trait
default still returns `operation_not_supported`, so a genuinely
unenumerable backend would fail every run — detectable, not silent, and
the point at which to bring the fallback back with tests.
## Also here
A doc note on `get_blob_range_stream` explaining why the Azurite
migration hang is not worked around: `azure_core` 0.21's
`Range::as_headers` attaches `x-ms-range-get-content-crc64` to any range
under 4 MiB with no opt-out, Azurite 500s on it, and `azure_core`
retries a deterministic error forever. The reachable path is
`backend_migration` → `EncryptedBlobBackend::head_check` →
`get_blob_range_stream(hash, 0, HEADER_SIZE)` — a pre-write probe on the
TARGET, so it fires on the first blob while `migration_readonly` refuses
writes app-wide. Working around it would trade production read
amplification for emulator support; the fix is the official SDK, where
`range_get_content_crc64` is an explicit field.
`RUSTSEC-2026-0275` is ignored on the same reasoning — `azure_core` 0.21
logs the `authorization` header at debug, the advisory's "upgrade to
>=0.22.0" names a version that does not exist, and the real remedy is
that same migration. Reachable only via an explicit
`RUST_LOG=…,azure_core=debug`; the entry says not to run that against a
real account.
`docs/plan/jobs-handling-recoverable-error.md` covers the other half —
a bounded retry should have turned that hang into a Paused run with a
reason, whatever the SDK does.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
A fast self-hosted cloud for people who want files, calendars, contacts, and office editing without dragging a heavy stack behind them.
Documentation · Quick Start · Star OxiCloud · Request a Feature · Supported Clients · Project Status
If OxiCloud saves you setup time, RAM, or complexity, give it a star. If something is missing, ask for a feature or request a docs improvement.
Why People Try OxiCloud
OxiCloud is aimed at self-hosters, home labs, and small teams who want the useful parts of a cloud suite without the operational drag of a traditional PHP stack.
What pulls people in:
- Standard protocols first: WebDAV, CalDAV, and CardDAV are built in
- Useful product surface already there: files, previews, sharing, trash, search, favorites, and recent items
- Modern auth and admin basics: OIDC/SSO, quotas, roles, and shared links
- Better interoperability: native desktop and mobile clients work without custom sync tooling for basic access
- Lower deployment friction: Docker Compose, environment-based configuration, Helm chart, and Nix module
OxiCloud is not trying to mirror the full plugin ecosystem of Nextcloud. It is designed for a smaller stack, fast startup, and standards-based interoperability.
Quick Start
Docker Compose
Requires Docker and Docker Compose.
git clone https://github.com/AtalayaLabs/OxiCloud.git
cd OxiCloud
cp example.env .env
# If users will access OxiCloud through a domain or reverse proxy,
# set OXICLOUD_BASE_URL in .env before the first login.
docker compose up -d
Open http://localhost:8086.
Prebuilt binary
Binary releases (Linux musl amd64/arm64, macOS Intel/Apple Silicon)
are attached to every tagged release on GitHub — the whole SPA + all
operator subcommands + migrations bake into a single self-contained
executable. See docs/install/binary.md for
the download / verify / systemd walkthrough.
cargo binstall oxicloud works too once a release is out.
Run from source
Requires Rust 1.93+ and PostgreSQL.
git clone https://github.com/AtalayaLabs/OxiCloud.git
cd OxiCloud
cp example.env .env
# If PostgreSQL runs on your host instead of Docker, update both
# OXICLOUD_DB_CONNECTION_STRING and DATABASE_URL to use localhost:5432.
cargo run
Deployment details: deployment guide · example.env
What You Get
| Area | Included |
|---|---|
| Files | Multi-file upload, folders, inline previews, thumbnails, chunked uploads, deduplication, trash |
| Sync and clients | WebDAV, CalDAV, CardDAV, native OS clients, Thunderbird, DAVx5 |
| Security | JWT auth, Argon2id, OIDC/SSO, shared links, quotas, admin/user roles |
| Integrations | REST API and WOPI for Collabora or OnlyOffice |
| Operations | Docker image, Docker Compose, env-driven config, PostgreSQL backend |
| Project tooling | Architecture docs, Helm chart, Nix module, CI |
Supported Clients
OxiCloud uses standard DAV protocols, so it works with native clients instead of requiring a custom sync stack for basic access.
| Use case | URL |
|---|---|
| Files via WebDAV | https://your-host/webdav/ |
| Calendars via CalDAV | https://your-host/caldav/ |
| Contacts via CardDAV | https://your-host/carddav/ |
Common clients that work well:
- macOS Finder
- Windows Explorer
- GNOME Files and KDE Dolphin
- Thunderbird
- Apple Calendar and Contacts
- DAVx5 on Android
Client setup guides: DAV client setup · WebDAV guide · CalDAV & CardDAV guide
Project Status
OxiCloud is actively developed and already covers the core self-hosted cloud workflow.
| Capability | Status | Notes |
|---|---|---|
| File storage and web UI | Ready | Uploads, previews, sharing, trash, and search |
| WebDAV | Ready | Standard file access for desktop and mobile clients |
| CalDAV and CardDAV | Ready | Working with Thunderbird, Apple clients, and others |
| OIDC / SSO | Ready | Documentation and config examples included |
| WOPI office editing | Ready | Works with Collabora or OnlyOffice |
| DAVx5 Android support | Partial | File sync works well; calendar and contact behavior is still being refined |
| Desktop sync client | Planned | Not yet available |
| Mobile apps | Planned | Not yet available |
| End-to-end encryption | Planned | Roadmap item |
Roadmap: TODO-LIST.md
Help Shape OxiCloud
If you want OxiCloud to get better faster, use the repo like a product feedback loop, not just a code dump.
- Give it a star if you want more people to discover the project: Star OxiCloud
- Propose missing functionality: feature request
- Point out confusing onboarding or weak docs: documentation request
- Report breakage or regressions: bug report
- Build it with us: CONTRIBUTING.md
The best feature ideas usually come from real deployment pain. If you hit friction, open an issue and describe the workflow you want.
Architecture and Deployment
OxiCloud follows a clean, hexagonal architecture so protocol handlers, business logic, and infrastructure stay separated.
- Backend: Rust + Axum
- Database: PostgreSQL
- Configuration: environment variables
- Default deployment: Docker Compose
- Additional packaging: Helm chart and Nix module
Architecture docs: internal architecture · caching architecture · database transactions · storage safety
Configuration and Integrations
Start with example.env. The most important settings are:
OXICLOUD_BASE_URLfor reverse proxies, domains, and external accessOXICLOUD_DB_CONNECTION_STRINGfor PostgreSQLOXICLOUD_OIDC_ENABLEDand related settings for SSOOXICLOUD_WOPI_ENABLEDand discovery URL for office editingMIMALLOC_PURGE_DELAY=0for lower idle RSS in constrained environments
Integration docs: OIDC setup · OIDC architecture · OIDC config examples · WOPI integration
Documentation
- Docs site: AtalayaLabs.github.io/OxiCloud
- Deployment: docs/config/deployment.md
- Batch operations: docs/guide/batch-operations.md
- Search: docs/guide/search.md
- Thumbnails and transcoding: docs/guide/thumbnails-and-transcoding.md
- Deduplication: docs/guide/deduplication.md
Development
cargo fmt --all --check
cargo clippy --all-features --all-targets -- -D warnings
cargo test --workspace
Contributing
Contributions are welcome. Read CONTRIBUTING.md before opening a pull request and CODE_OF_CONDUCT.md for community expectations.
If you are not ready to code yet, starring the project and opening a precise feature request is still a meaningful contribution.
Contributors
OxiCloud is a community-driven project, and we appreciate all contributions. Check out the Contributors page to see the amazing people who have helped make OxiCloud better.
Star History
License
OxiCloud is a trademark of the OxiCloud project. All other trademarks are the property of their respective owners.