DOCSEARCHbyAlgolia
Submit Docs

OxiCloud Documentation

repository·main·Indexed 25 days ago

https://github.com/atalayalabs/oxicloud

A fast, self-hosted cloud suite for files, calendars, contacts, and office editing. OxiCloud prioritizes standard protocols including WebDAV, CalDAV, and CardDAV as a lightweight alternative to PHP-based stacks. It features support for PMTiles vector basemaps in the Places photo map, OIDC/SSO authentication, and WOPI for office editing. The suite can be deployed via Docker Compose, run from source using Rust 1.93+ and PostgreSQL, or managed via a NixOS module.

Tokens
120.7K
Snippets
268
Records
714
Agent score
85%

What's inside OxiCloud

  1. Overview of OxiCloud features

    main

    OxiCloud is a self-hosted cloud storage solution designed for speed and efficiency. Key features include:

    • Performance: Single Rust binary, ~40 MB Docker image, <1s cold start, and 30–50 MB idle RAM.
    • File Management: Supports chunked uploads, BLAKE3 deduplication, trash, favorites, full-text search, and thumbnails.
    • Protocol Support: RFC-compliant WebDAV, CalDAV, and CardDAV for files, calendars, and contacts.
    • Office Editing: WOPI support for editing documents in Collabora Online or OnlyOffice via the browser.
    • Security: Uses JWT + Argon2id, supports OIDC/SSO (Keycloak, Authentik, Azure AD), role-based access, and shared links.
    • Localization: Supports 14 languages including EN, ES, DE, FR, IT, PT, NL, ZH, JA, KO, AR, HI, FA, and RU.

  2. Overview of OxiCloud features and capabilities

    main

    OxiCloud is a high-performance, self-hosted cloud platform written in Rust designed for minimal hardware. It provides a single-binary solution for file storage, calendar sync, contacts sync, and office document editing.

    Core Capabilities

    • Storage & Files: Personal and shared drives with quotas, chunked/resumable uploads (TUS-like), BLAKE3 content-addressable deduplication, adaptive compression (zstd/gzip), and a trash bin with auto-purge.
    • Protocols: Supports WebDAV (RFC 4918), CalDAV (calendar sync), CardDAV (contacts sync), WOPI (for Collabora Online / OnlyOffice), and a complete REST JSON API.
    • Security: Uses JWT and Argon2id hashing. Supports OIDC/SSO (Keycloak, Authentik, Authelia, Google, Azure AD), role-based access, and password-protected shared links.
    • Infrastructure: Lightweight (~40 MB Docker image), dual DB pool to prevent query starvation, and write-behind caching (moka) for low-latency reads.

  3. Understand the Drive-based storage model

    main

    OxiCloud uses a 'Drive' model for storage organization. Every drive consists of a metadata row and exactly one root folder where parent_id IS NULL and drive_id matches the drive's UUID.

    There are two types of drives:

    • Personal Drives: Owned by a single user. The default personal drive is automatically created for each user (formerly the 'My Folder - <username>' wrapper).
    • Shared Drives: Can have multiple owners (users or groups) and are used for collaborative storage.

    From a client perspective, folder creation remains consistent via POST /api/folders { name, parent_id: <id> }. The drive's root folder is treated as just another folder ID.

  4. Optimization of admin-user count (SQL `COUNT(*)` vs hydration)

    main

    The count_admin_users endpoint (used during system status/initialization) has been optimized to use a scalar SELECT COUNT(*) instead of fetching and hydrating full user rows.

    Previously, the system fetched every admin's full 21-column row (including large avatar images and JSONB preferences) just to call .len() on the resulting list. The new implementation uses count_users_by_role to perform the count directly in the database, reducing allocations from 25 to 0 and drastically reducing the wire payload size.

  6. Understand Drive Types and Capabilities

    main

    OxiCloud uses different drive kind values to manage membership and permissions.

    • Personal Drives (kind='personal'):
      • Default: Linked to a user via default_for_user. Single-user ownership. Deleting the user cascades to the drive. API-level deletion is refused.
      • Secondary: default_for_user is NULL. Still single-user, but managed via application-layer cleanup on user deletion.
      • Note: Personal drives do not have a per-drive quota_bytes limit; they are capped by the user's total storage envelope.
    • Shared Drives (kind='shared'):
      • Supports multiple users and groups.
      • Supports add_member and remove_member operations.
      • Has an explicit quota_bytes ceiling set by admins.
      • Deleting a shared drive cascades to its contents.

  7. Performance improvements in Content-cache serve fast path

    main

    The content-cache serve fast path (used during video scrubbing) has been optimized to prevent unnecessary allocations during cache hits. Previously, file_retrieval_service::optimized_inner and get_file_range_preloaded eagerly built owned arguments (like quoted etags and cache keys) before probing the cache.

    Now, the system probes the cache using a borrow (cache.get(&hash)) first. Only on a cache miss does it build the owned arguments and call load_and_cache. This reduces allocations from ~6 to 0 per cache hit, significantly improving performance during high-frequency operations like video seeking.

  8. Understand Batch Concurrency and Error Handling

    main

    Batch operations are managed by BatchOperationService using a tokio::sync::Semaphore. To prevent large batches from starving the application, OxiCloud defaults to a concurrency cap of max_concurrent_files = 10.

    Individual item failures are collected in the failed array in the response; a single item failure does not cancel the entire batch unless the request itself cannot be processed.

  9. Understand OxiCloud ReBAC Authorization

    main

    OxiCloud uses Relationship-Based Access Control (ReBAC) to manage permissions. Access is expressed as a typed triple: Subject has Role on Resource.

    Unlike global RBAC, ReBAC allows for per-resource sharing (e.g., "Alice can edit this folder but not that one"). Permissions are not stored directly in the database; instead, the database stores a Role, which the AuthorizationEngine (specifically PgAclEngine) expands into a set of atomic Permissions at runtime.

    Key Concepts:

    • Grants are facts: Each grant is a specific relationship between a subject and a resource, optionally with an expiration.
    • Uniform Model: The same model covers users, groups, anonymous share-links, and federated identities as Subjects. It also covers files, folders, drives, calendars, address books, and playlists as Resources.
    • Owner Short-circuit: The resource owner always passes authorization checks without requiring an explicit row in the role_grants table.

  10. Understand the OxiCloud Security Model

    main

    OxiCloud implements several security layers to protect user data and prevent common attacks:

    • Password Hashing: Local passwords are hashed using Argon2id.
    • DAV Access: WebDAV, CalDAV, and CardDAV surfaces (/webdav/, /caldav/, /carddav/) only accept app passwords. Primary account passwords will be refused by design.
    • Access Control: Permissions are managed via role-based access control (RBAC) with admin and user roles.
    • Session Management: Refresh tokens are used to support session renewal without requiring frequent re-logins.
    • Anti-Enumeration: The login endpoint returns identical 403 responses for both invalid usernames and invalid passwords to prevent account enumeration.
    • Magic-Link Privacy: The magic-link send endpoint returns a uniform 200 status regardless of whether the account exists. Verification of account existence must be performed via the audit log.
    • OIDC Security: In deployments where OIDC is enabled, magic-link login is hard-disabled to prevent bypassing Identity Provider (IdP) Multi-Factor Authentication (MFA).

  11. Understand OxiCloud storage safety guarantees

    main

    OxiCloud ensures file integrity through a dual-layer approach that separates metadata management from content storage:

    1. Metadata Safety: Managed via PostgreSQL ACID transactions. This ensures that file names, folder structures, MIME types, quotas, and trash states are updated atomically. Foreign keys and unique constraints prevent orphaned references or illegal duplicates.
    2. Content Safety: Managed via atomic blob writes. Content is stored as content-addressed blobs. To prevent corruption, OxiCloud uses a temporary file pattern: writing to a temp file, performing an fsync, and then renaming the file to its final content-addressed path.

    This architecture ensures that operations either complete fully or fail cleanly, preventing data corruption during crashes or power loss.

  12. Understand Face Indexing and Clustering scope

    main

    Face indexing in OxiCloud is bound to the same scope as the Photos API.

    Storage Layer

    Face fingerprints are stored per-blob and are content-addressable using blob_hash (BLAKE3). They are independent of user_id or drive_id to allow for global deduplication. If a photo is uploaded to multiple drives, only one fingerprint set is computed.

    Clustering Layer

    Clustering (grouping faces) is performed per-drive.

    • Shared Drives: If multiple users have access to a shared drive with include_in_photo_index = true, they will see the same merged clusters (e.g., a 'Grandma' cluster containing photos uploaded by different members).
    • Personal Isolation: Clusters are scoped to the drive. A user's personal drive cluster is only visible to the owner.
    • No Auto-Merging: Labels applied to a cluster in a Personal drive (e.g., labeling a face as 'Grandma') do not propagate to clusters in shared drives. This prevents private classifications from being accidentally shared.