### Docker Compose Setup for OxiCloud

Source: https://github.com/diocrafts/oxicloud/blob/main/README.md

Use this command to clone the repository, navigate to the directory, copy the example environment file, and start OxiCloud using Docker Compose. Ensure OXICLOUD_BASE_URL is set in .env if accessing via a domain or reverse proxy.

```bash
git clone https://github.com/DioCrafts/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
```

--------------------------------

### Clone and Start with Docker Compose

Source: https://context7.com/diocrafts/oxicloud/llms.txt

Clone the OxiCloud repository, navigate to the directory, copy the example environment file, and start the services using Docker Compose. Ensure to edit the .env file, particularly OXICLOUD_BASE_URL, before starting.

```bash
git clone https://github.com/DioCrafts/OxiCloud.git
cd OxiCloud
cp example.env .env
# Edit .env — at minimum set OXICLOUD_BASE_URL for external access
docker compose up -d
# Open http://localhost:8086 — complete first-run admin setup there
```

--------------------------------

### POST /api/auth/setup - First-run Admin Setup

Source: https://context7.com/diocrafts/oxicloud/llms.txt

Use this endpoint to create the first administrator account on a fresh OxiCloud installation. Subsequent calls after the first admin is created will result in a 403 Forbidden error.

```bash
curl -s -X POST http://localhost:8086/api/auth/setup \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin",
    "email": "admin@example.com",
    "password": "s3cur3P@ssword!"
  }'
```

--------------------------------

### Install OxiCloud with Docker

Source: https://github.com/diocrafts/oxicloud/blob/main/docs/guide/installation.md

Clone the repository, set up environment variables, and start the services using Docker Compose. Access the application at http://localhost:8086.

```bash
git clone https://github.com/DioCrafts/OxiCloud.git
cd OxiCloud
cp example.env .env
docker compose up -d
```

--------------------------------

### CalDAV Route Structure Examples

Source: https://github.com/diocrafts/oxicloud/blob/main/docs/guide/caldav-carddav.md

These examples illustrate the typical resource paths for CalDAV, including the calendar home, individual calendars, and specific events.

```text
/caldav/
```

```text
/caldav/{calendar_id}/
```

```text
/caldav/{calendar_id}/{ical_uid}.ics
```

--------------------------------

### POST /api/auth/setup — First-run Admin Setup

Source: https://context7.com/diocrafts/oxicloud/llms.txt

This endpoint is used for the initial setup of the first administrator account. It is only active before any admin user has been created and will return a 403 Forbidden status for subsequent calls.

```APIDOC
## POST /api/auth/setup

### Description
One-time endpoint active only before the first admin user exists. Once claimed, subsequent calls return 403. Uses an atomic database flag to prevent race conditions.

### Method
POST

### Endpoint
/api/auth/setup

### Request Body
- **username** (string) - Required - The desired username for the admin.
- **email** (string) - Required - The email address for the admin.
- **password** (string) - Required - The password for the admin.

### Request Example
```json
{
  "username": "admin",
  "email": "admin@example.com",
  "password": "s3cur3P@ssword!"
}
```

### Response
#### Success Response (201 Created)
- **id** (string) - The unique identifier of the created admin user.
- **username** (string) - The username of the admin.
- **email** (string) - The email address of the admin.
- **role** (string) - The role assigned to the user (e.g., "admin").

#### Response Example
```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "username": "admin",
  "email": "admin@example.com",
  "role": "admin"
}
```
```

--------------------------------

### Check Admin Setup Status

Source: https://context7.com/diocrafts/oxicloud/llms.txt

Query the status of the initial administrator setup. This endpoint returns whether the setup has been completed, the number of admin users, and if new registrations are currently allowed.

```bash
curl -s http://localhost:8086/api/auth/status
```

--------------------------------

### Keycloak Provider Example

Source: https://github.com/diocrafts/oxicloud/blob/main/docs/config/oidc.md

Example configuration for integrating with Keycloak as an OIDC provider.

```APIDOC
### Keycloak

```yaml
# docker-compose.yml
services:
  oxicloud:
    environment:
      OXICLOUD_OIDC_ENABLED: "true"
      OXICLOUD_OIDC_ISSUER_URL: "https://keycloak.example.com/realms/your-realm"
      OXICLOUD_OIDC_CLIENT_ID: "oxicloud"
      OXICLOUD_OIDC_CLIENT_SECRET: "your-client-secret"
      OXICLOUD_OIDC_REDIRECT_URI: "https://oxicloud.example.com/api/auth/oidc/callback"
      OXICLOUD_OIDC_FRONTEND_URL: "https://oxicloud.example.com"
      OXICLOUD_OIDC_PROVIDER_NAME: "Keycloak"
```
```

--------------------------------

### Command Line Examples (curl)

Source: https://github.com/diocrafts/oxicloud/blob/main/docs/guide/webdav.md

Examples of common WebDAV operations using the curl command-line tool.

```APIDOC
## Command Line (curl)

```bash
# List root directory
curl -u user:pass -X PROPFIND https://your-server:8086/webdav/ \
  -H "Depth: 1"

# Download a file
curl -u user:pass https://your-server:8086/webdav/document.pdf -o document.pdf

# Upload a file
curl -u user:pass -T localfile.txt https://your-server:8086/webdav/remotefile.txt

# Create a folder
curl -u user:pass -X MKCOL https://your-server:8086/webdav/new-folder/
```
```

--------------------------------

### Google Provider Example

Source: https://github.com/diocrafts/oxicloud/blob/main/docs/config/oidc.md

Example configuration for integrating with Google as an OIDC provider.

```APIDOC
### Google

```bash
OXICLOUD_OIDC_ISSUER_URL="https://accounts.google.com"
OXICLOUD_OIDC_PROVIDER_NAME="Google"
```
```

--------------------------------

### Start Storage Migration

Source: https://context7.com/diocrafts/oxicloud/llms.txt

Initiates the storage backend migration process.

```APIDOC
## POST /api/admin/storage/migration/start

### Description
Starts the storage backend migration.

### Method
POST

### Endpoint
/api/admin/storage/migration/start
```

--------------------------------

### Authentik Provider Example

Source: https://github.com/diocrafts/oxicloud/blob/main/docs/config/oidc.md

Example configuration for integrating with Authentik as an OIDC provider.

```APIDOC
### Authentik

```bash
OXICLOUD_OIDC_ISSUER_URL="https://authentik.example.com/application/o/oxicloud/"
OXICLOUD_OIDC_PROVIDER_NAME="Authentik"
```
```

--------------------------------

### Download a File (GET)

Source: https://github.com/diocrafts/oxicloud/blob/main/docs/guide/webdav.md

Instructions for downloading a file using the GET method.

```APIDOC
## Download a file

```http
GET /webdav/projects/document.pdf HTTP/1.1
Authorization: Basic base64(username:password)
```
```

--------------------------------

### CardDAV Route Structure Examples

Source: https://github.com/diocrafts/oxicloud/blob/main/docs/guide/caldav-carddav.md

These examples show the typical resource paths for CardDAV, including the address book home, individual address books, and specific contacts.

```text
/carddav/
```

```text
/carddav/{addressBookId}/
```

```text
/carddav/{addressBookId}/{contactId}.vcf
```

--------------------------------

### Start Storage Backend Migration

Source: https://context7.com/diocrafts/oxicloud/llms.txt

Initiates the process of migrating the storage backend. Requires admin authentication.

```bash
curl -s -X POST http://localhost:8086/api/admin/storage/migration/start \
  -H "Authorization: Bearer $ADMIN_TOKEN"
```

--------------------------------

### Linux Client Setup (Dolphin/KDE)

Source: https://github.com/diocrafts/oxicloud/blob/main/docs/guide/webdav.md

Connect to the WebDAV server using Dolphin or the KDE Files application. Use 'webdavs://' for secure connections.

```text
webdavs://your-server:8086/webdav/
```

--------------------------------

### Wire Storage Backend Selection in DI (Rust)

Source: https://github.com/diocrafts/oxicloud/blob/main/TODO-STORAGE-BACKENDS.prompt.md

Demonstrates how to dynamically select and initialize the appropriate blob storage backend (Local or S3) based on the application configuration within the dependency injection setup in `src/common/di.rs`.

```rust
// Build storage backend based on config
let blob_backend: Arc<dyn BlobStorageBackend> = match self.config.storage.backend {
    StorageBackendType::Local => {
        Arc::new(LocalBlobBackend::new(&self.storage_path))
    }
    StorageBackendType::S3 => {
        let s3_config = self.config.storage.s3.as_ref()
            .expect("S3 config required when backend=s3");
        Arc::new(S3BlobBackend::new(s3_config).await?)
    }
};

blob_backend.initialize().await?;

let dedup_service = Arc::new(DedupService::new(
    blob_backend.clone(),
    db_pool.clone(),
    maintenance_pool.clone(),
));
```

--------------------------------

### Install OxiCloud from Source

Source: https://github.com/diocrafts/oxicloud/blob/main/docs/guide/installation.md

Clone the repository, configure environment variables, build the release version, and run the application. Requires Rust 1.93+ and PostgreSQL 13+. Note that DATABASE_URL is for build-time checks, while OXICLOUD_DB_CONNECTION_STRING is for runtime.

```bash
git clone https://github.com/DioCrafts/OxiCloud.git
cd OxiCloud
cp example.env .env

# Edit .env and set OXICLOUD_DB_CONNECTION_STRING for runtime
export DATABASE_URL=postgres://user:pass@localhost:5432/oxicloud

cargo build --release
cargo run --release
```

--------------------------------

### Linux Client Setup (Nautilus/Files)

Source: https://github.com/diocrafts/oxicloud/blob/main/docs/guide/webdav.md

Connect to the WebDAV server using Nautilus or the Files application in Linux. Use 'davs://' for secure connections.

```text
davs://your-server:8086/webdav/
```

--------------------------------

### Download a File (GET)

Source: https://github.com/diocrafts/oxicloud/blob/main/docs/guide/webdav.md

Use the GET method to download a file from the WebDAV server. Include the Authorization header for authentication.

```http
GET /webdav/projects/document.pdf HTTP/1.1
Authorization: Basic base64(username:password)
```

--------------------------------

### Minimal .env Configuration

Source: https://github.com/diocrafts/oxicloud/blob/main/docs/config/index.md

This is the minimum set of environment variables required to start OxiCloud. All other settings will use their default values.

```bash
OXICLOUD_DB_CONNECTION_STRING=postgres://postgres:postgres@postgres:5432/oxicloud
OXICLOUD_STORAGE_PATH=/app/storage
OXICLOUD_SERVER_HOST=0.0.0.0
OXICLOUD_SERVER_PORT=8086
```

--------------------------------

### Example Client Request for Transcoding

Source: https://github.com/diocrafts/oxicloud/blob/main/docs/guide/thumbnails-and-transcoding.md

A client requests a file, advertising WebP support in the Accept header. The server checks its cache, transcodes if necessary, and returns the most optimal asset.

```http
Client: GET /api/files/abc-123/download
Accept: image/webp, image/png, */*

Server: checks cache -> transcodes if needed -> returns the smaller asset
```

--------------------------------

### Docker Compose Configuration

Source: https://github.com/diocrafts/oxicloud/blob/main/docs/config/deployment.md

Example Docker Compose file for deploying OxiCloud with PostgreSQL. Remove the 'build:' stanza if deploying from a registry.

```yaml
services:
  postgres:
    image: postgres:18.2-alpine3.23
    restart: always
    environment:
      POSTGRES_DB: oxicloud
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
    ports:
      - "5432:5432"
    networks:
      - oxicloud
    volumes:
      - pg_data:/var/lib/postgresql/
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 5s
      retries: 5

  oxicloud:
    image: diocrafts/oxicloud:latest
    restart: always
    build:
      context: .
      dockerfile: Dockerfile
    ports:
      - "8086:8086"
    networks:
      - oxicloud
    env_file:
      - .env
    volumes:
      - storage_data:/app/storage
    depends_on:
      postgres:
        condition: service_healthy

networks:
  oxicloud:
    driver: bridge

volumes:
  pg_data:
  storage_data:
```

--------------------------------

### DAVx⁵ Android Setup for CalDAV/CardDAV

Source: https://github.com/diocrafts/oxicloud/blob/main/docs/guide/caldav-carddav.md

Instructions for setting up DAVx⁵ on Android to automatically discover and sync both CalDAV and CardDAV data from OxiCloud.

```text
https://your-server:8086/
```

--------------------------------

### Running OxiCloud from Source

Source: https://github.com/diocrafts/oxicloud/blob/main/README.md

This guide outlines the steps to run OxiCloud directly from its source code. It requires Rust 1.93+ and PostgreSQL. Update database connection strings in .env if PostgreSQL is not running in Docker.

```bash
git clone https://github.com/DioCrafts/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
```

--------------------------------

### WebDAV Directory Listing

Source: https://context7.com/diocrafts/oxicloud/llms.txt

Access files via WebDAV using RFC 4918 compliant methods. This example shows how to list directory contents using a PROPFIND request with Depth: 1.

```bash
curl -u alice:password -X PROPFIND https://cloud.example.com/webdav/ \
  -H "Depth: 1" \
  -H "Content-Type: application/xml" \
  -d '<?xml version="1.0" encoding="utf-8"?><D:propfind xmlns:D="DAV:"><D:allprop/></D:propfind>'
```

--------------------------------

### Get Photos Sorted by Capture Date

Source: https://context7.com/diocrafts/oxicloud/llms.txt

Lists all image and video files owned by the user, sorted chronologically by capture date (EXIF). Supports pagination.

```bash
curl -s -H "Authorization: Bearer $TOKEN" \
  "http://localhost:8086/api/photos"
```

```bash
curl -s -H "Authorization: Bearer $TOKEN" \
  "http://localhost:8086/api/photos?limit=50&offset=0"
```

--------------------------------

### Move Files using cURL

Source: https://github.com/diocrafts/oxicloud/blob/main/docs/guide/batch-operations.md

Example using cURL to move multiple files into a specified folder via the batch endpoint.

```bash
# Move three files into a folder
curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"file_ids":["id-1","id-2","id-3"],"target_folder_id":"folder-abc"}' \
  "https://oxicloud.example.com/api/batch/files/move"
```

--------------------------------

### Helm Install Command

Source: https://github.com/diocrafts/oxicloud/blob/main/docs/config/deployment.md

Command to install or upgrade OxiCloud using Helm. Ensure you have a Kubernetes cluster, default StorageClass, Ingress Controller, and Helm 3+ installed.

```bash
helm upgrade --install oxicloud charts/oxicloud \
  -f charts/oxicloud/values.yaml
```

--------------------------------

### GET /api/auth/me — Get Current User Info

Source: https://context7.com/diocrafts/oxicloud/llms.txt

Retrieves information about the currently authenticated user, including their storage usage.

```APIDOC
## GET /api/auth/me

### Description
Gets current user info, including updated storage usage.

### Method
GET

### Endpoint
/api/auth/me

### Authentication
Requires a valid JWT access token in the `Authorization` header (e.g., `Bearer <token>`).

### Response
#### Success Response (200 OK)
- **id** (string) - The user's unique identifier.
- **username** (string) - The user's username.
- **email** (string) - The user's email address.
- **role** (string) - The user's role.
- **storage_usage_bytes** (integer) - The amount of storage used by the user in bytes.
```

--------------------------------

### GET /api/auth/me - Get Current User Info

Source: https://context7.com/diocrafts/oxicloud/llms.txt

Retrieve information about the currently authenticated user, including updated storage usage details. Requires an Authorization header with a Bearer token.

```bash
curl -s -H "Authorization: Bearer $TOKEN" http://localhost:8086/api/auth/me
```

--------------------------------

### S3 Client Construction with Custom Endpoints

Source: https://github.com/diocrafts/oxicloud/blob/main/TODO-STORAGE-BACKENDS.prompt.md

Demonstrates how to construct an S3 client, supporting custom endpoints for S3-compatible providers.

```rust
impl S3BlobBackend {
    pub async fn new(config: &S3StorageConfig) -> Result<Self, DomainError> {
        let mut s3_config_builder = aws_sdk_s3::config::Builder::new()
            .region(aws_sdk_s3::config::Region::new(config.region.clone()))
            .credentials_provider(
                aws_sdk_s3::config::Credentials::new(
                    &config.access_key,
                    &config.secret_key,
                    None, None, "oxicloud",
                )
            )
            .behavior_version_latest();

        if let Some(endpoint) = &config.endpoint_url {
            s3_config_builder = s3_config_builder
                .endpoint_url(endpoint)
                .force_path_style(config.force_path_style);
        }

        let client = aws_sdk_s3::Client::from_conf(s3_config_builder.build());
        Ok(Self { client, bucket: config.bucket.clone() })
    }
}
```

--------------------------------

### Get Server Version

Source: https://context7.com/diocrafts/oxicloud/llms.txt

Retrieves the running OxiCloud version information.

```APIDOC
## GET /api/version

### Description
Returns the running OxiCloud version.

### Method
GET

### Endpoint
/api/version

### Response
#### Success Response (200)
- **name** (string) - The name of the application.
- **version** (string) - The current version of the application.
```

--------------------------------

### Create a Folder (MKCOL)

Source: https://github.com/diocrafts/oxicloud/blob/main/docs/guide/webdav.md

Steps to create a new folder using the MKCOL method.

```APIDOC
## Create a folder

```http
MKCOL /webdav/projects/new-folder HTTP/1.1
```
```

--------------------------------

### Get EXIF / media metadata

Source: https://context7.com/diocrafts/oxicloud/llms.txt

Retrieves EXIF or other media-specific metadata for a file.

```APIDOC
## GET /api/files/:id/metadata

### Description
Retrieves EXIF or other media-specific metadata for a file.

### Method
GET

### Endpoint
/api/files/$FILE_ID/metadata

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the file.

### Request Example
```bash
curl -s -H "Authorization: Bearer $TOKEN" \
  "http://localhost:8086/api/files/$FILE_ID/metadata"
```
```

--------------------------------

### Create Playlist

Source: https://context7.com/diocrafts/oxicloud/llms.txt

Creates a new audio playlist with a given name and description. Returns the playlist ID.

```bash
PLAYLIST=$(curl -s -X POST http://localhost:8086/api/playlists \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Road Trip Mix", "description": "Summer 2024"}')
PID=$(echo $PLAYLIST | jq -r '.id')
```

--------------------------------

### Get Server Version

Source: https://context7.com/diocrafts/oxicloud/llms.txt

Retrieves the running OxiCloud version information. This is a public endpoint.

```bash
curl -s http://localhost:8086/api/version
```

--------------------------------

### Get Dashboard Statistics

Source: https://context7.com/diocrafts/oxicloud/llms.txt

Retrieves overall system statistics. Requires admin authentication.

```bash
curl -s -H "Authorization: Bearer $ADMIN_TOKEN" \
  http://localhost:8086/api/admin/dashboard
```

--------------------------------

### Get folder contents

Source: https://context7.com/diocrafts/oxicloud/llms.txt

Retrieves the contents of a specified folder, including both files and subfolders.

```APIDOC
## GET /api/folders/{folder_id}/listing

### Description
Gets the contents of a folder, combining files and subfolders.

### Method
GET

### Endpoint
/api/folders/$FOLDER_ID/listing

### Parameters
#### Path Parameters
- **folder_id** (string) - Required - The ID of the folder to list contents for.

### Request Example
```bash
curl -s -H "Authorization: Bearer $TOKEN" "http://localhost:8086/api/folders/$FOLDER_ID/listing"
```
```

--------------------------------

### Get Folder Contents

Source: https://context7.com/diocrafts/oxicloud/llms.txt

Fetches all files and subfolders within a specified folder. Requires authentication.

```bash
curl -s -H "Authorization: Bearer $TOKEN" \
  "http://localhost:8086/api/folders/$FOLDER_ID/listing"
```

--------------------------------

### Create a folder using WebDAV

Source: https://context7.com/diocrafts/oxicloud/llms.txt

Create a new folder on the WebDAV server using the MKCOL method.

```bash
curl -u alice:password -X MKCOL \
  "https://cloud.example.com/webdav/Documents/NewFolder/"
```

--------------------------------

### List Directory Contents (PROPFIND)

Source: https://github.com/diocrafts/oxicloud/blob/main/docs/guide/webdav.md

How to list the contents of a directory or retrieve file properties using the PROPFIND method with a Depth header.

```APIDOC
## List a directory

Use `PROPFIND` with a `Depth` header:

```http
PROPFIND /webdav/projects/ HTTP/1.1
Depth: 1
Content-Type: application/xml

<?xml version="1.0" encoding="utf-8" ?>
<D:propfind xmlns:D="DAV:">
  <D:allprop/>
</D:propfind>
```

Successful directory listings return `207 Multi-Status`.
```

--------------------------------

### Get User Quota and Usage

Source: https://github.com/diocrafts/oxicloud/blob/main/docs/architecture/storage-quotas.md

Retrieves the current storage quota and usage for a specific user.

```APIDOC
## GET /api/admin/users/{id}/quota

### Description
Get user's quota and current usage.

### Method
GET

### Endpoint
/api/admin/users/{id}/quota

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the user.

### Response
#### Success Response (200)
- **quota** (integer) - The storage quota in bytes (0 for unlimited).
- **used** (integer) - The current storage used in bytes.
```

--------------------------------

### Create a Folder (MKCOL)

Source: https://github.com/diocrafts/oxicloud/blob/main/docs/guide/webdav.md

Use the MKCOL method to create a new folder on the WebDAV server.

```http
MKCOL /webdav/projects/new-folder HTTP/1.1
```

--------------------------------

### Get File Metadata

Source: https://context7.com/diocrafts/oxicloud/llms.txt

Retrieves EXIF or other media metadata associated with a file. Requires the file ID.

```bash
curl -s -H "Authorization: Bearer $TOKEN" \
  "http://localhost:8086/api/files/$FILE_ID/metadata"
```

--------------------------------

### Enable WOPI Integration

Source: https://github.com/diocrafts/oxicloud/blob/main/docs/config/wopi.md

Set OXICLOUD_WOPI_ENABLED to true to activate WOPI integration. Configure the discovery URL for the WOPI client.

```bash
OXICLOUD_WOPI_ENABLED=true
OXICLOUD_WOPI_DISCOVERY_URL="http://collabora:9980/hosting/discovery"
```

--------------------------------

### List Available Locales

Source: https://github.com/diocrafts/oxicloud/blob/main/docs/guide/i18n.md

Use this curl command to get a list of all supported locales from the OxiCloud API.

```bash
# List locales
curl "https://oxicloud.example.com/api/i18n/locales"
```

--------------------------------

### Mount WebDAV in Windows

Source: https://context7.com/diocrafts/oxicloud/llms.txt

Map the WebDAV server as a network drive in Windows using the 'net use' command.

```bash
net use Z: https://cloud.example.com/webdav/ /user:alice password
```

--------------------------------

### Get Audio Metadata

Source: https://context7.com/diocrafts/oxicloud/llms.txt

Retrieves metadata for a specific audio file, including title, artist, album, and duration.

```APIDOC
## GET /api/playlists/audio-metadata/{fileId}

### Description
Retrieves metadata for an audio file.

### Method
GET

### Endpoint
/api/playlists/audio-metadata/{fileId}

### Path Parameters
- **fileId** (string) - Required - The ID of the audio file.

### Response
#### Success Response (200)
- **title** (string) - The title of the song.
- **artist** (string) - The artist of the song.
- **album** (string) - The album of the song.
- **duration_secs** (integer) - The duration of the audio in seconds.
```

--------------------------------

### Get Shares for Specific Item

Source: https://context7.com/diocrafts/oxicloud/llms.txt

Lists all share links associated with a particular file or folder. Requires authentication.

```bash
curl -s -H "Authorization: Bearer $TOKEN" \
  "http://localhost:8086/api/shares?item_id=file-uuid&item_type=file"
```

--------------------------------

### Compose Blob Storage Backends with Decorators

Source: https://github.com/diocrafts/oxicloud/blob/main/TODO-STORAGE-BACKENDS.prompt.md

Demonstrates how different blob storage backends are composed using a decorator pattern. This allows for features like encryption, caching, and migration to be added optionally and in any order.

```rust
let base_backend: Arc<dyn BlobStorageBackend> = match config {
    Local => Arc::new(LocalBlobBackend::new(...)),
    S3 => Arc::new(S3BlobBackend::new(...).await?),
    Azure => Arc::new(AzureBlobBackend::new(...).await?),
};

// Phase 4: Optional encryption layer
let backend = if encryption_enabled {
    Arc::new(EncryptedBlobBackend::new(base_backend, key))
} else {
    base_backend
};

// Phase 4: Optional cache layer (only for remote backends)
let backend = if cache_enabled && !matches!(config, Local) {
    Arc::new(CachedBlobBackend::new(backend, cache_config))
} else {
    backend
};

// Phase 3: Optional migration wrapper
let backend = if migration_in_progress {
    Arc::new(MigrationBlobBackend::new(old_backend, backend, state))
} else {
    backend
};

// Finally: DedupService uses the composed backend
let dedup_service = Arc::new(DedupService::new(backend, pool, maintenance_pool));
```

--------------------------------

### Move or Copy a Resource (MOVE/COPY)

Source: https://github.com/diocrafts/oxicloud/blob/main/docs/guide/webdav.md

How to move or rename files/folders using MOVE, and how to copy them using COPY.

```APIDOC
## Move or copy

```http
MOVE /webdav/old-location.pdf HTTP/1.1
Destination: https://your-server/webdav/new-location.pdf
```

```http
COPY /webdav/original.pdf HTTP/1.1
Destination: https://your-server/webdav/copy.pdf
```
```

--------------------------------

### Get Storage Settings

Source: https://github.com/diocrafts/oxicloud/blob/main/TODO-STORAGE-BACKENDS.prompt.md

Retrieves the current storage settings from the database. Secrets are masked, and environment overrides are indicated.

```APIDOC
## GET /settings/storage

### Description
Retrieves the current storage settings. Secrets are masked, and environment overrides are listed.

### Method
GET

### Endpoint
/settings/storage

### Response
#### Success Response (200)
- **backend** (string) - The storage backend type ('local' or 's3').
- **s3_endpoint_url** (string) - The S3 endpoint URL (optional).
- **s3_bucket** (string) - The S3 bucket name.
- **s3_region** (string) - The S3 region.
- **s3_access_key_set** (boolean) - Indicates if the S3 access key is set (masked).
- **s3_secret_key_set** (boolean) - Indicates if the S3 secret key is set (masked).
- **s3_force_path_style** (boolean) - Whether to use path-style access for S3.
- **env_overrides** (array of strings) - List of fields that are locked by environment variables.
- **current_backend** (string) - The currently active backend.
- **total_blobs** (u64) - Total number of blobs stored.
- **total_bytes_stored** (u64) - Total bytes stored.
- **dedup_ratio** (f64) - Deduplication ratio.

### Response Example
{
  "backend": "s3",
  "s3_endpoint_url": null,
  "s3_bucket": "my-bucket",
  "s3_region": "us-east-1",
  "s3_access_key_set": true,
  "s3_secret_key_set": true,
  "s3_force_path_style": false,
  "env_overrides": ["storage.s3.region"],
  "current_backend": "s3",
  "total_blobs": 1000,
  "total_bytes_stored": 1073741824,
  "dedup_ratio": 0.5
}
```

--------------------------------

### Create Playlist

Source: https://context7.com/diocrafts/oxicloud/llms.txt

Creates a new audio playlist with a specified name and description.

```APIDOC
## POST /api/playlists

### Description
Creates a new audio playlist.

### Method
POST

### Endpoint
/api/playlists

### Request Body
- **name** (string) - Required - The name of the playlist.
- **description** (string) - Optional - A description for the playlist.
```

--------------------------------

### Autocomplete Suggestions

Source: https://github.com/diocrafts/oxicloud/blob/main/docs/guide/search.md

Get lightweight autocomplete suggestions for search queries. This endpoint is optimized for quick, partial-match results.

```APIDOC
## GET /api/search/suggest

### Description
Provides lightweight autocomplete suggestions for search queries. Can be scoped to a specific folder.

### Method
GET

### Endpoint
/api/search/suggest

### Parameters
#### Query Parameters
- **query** (string) - Required - The partial search term for suggestions.
- **limit** (integer) - Optional - The maximum number of suggestions to return, defaults to `10`.
- **folder_id** (string) - Optional - Restrict suggestions to a specific folder ID.

### Request Example
```bash
curl -H "Authorization: Bearer $TOKEN" \
  "https://oxicloud.example.com/api/search/suggest?query=rep&limit=10"
```

### Response
#### Success Response (200)
- **suggestions** (array of strings) - A list of suggested search terms or file/folder names.

#### Response Example
```json
{
  "suggestions": [
    "report.pdf",
    "reporting_template.docx",
    "repository_structure.txt"
  ]
}
```
```

--------------------------------

### Build and Run from Source

Source: https://context7.com/diocrafts/oxicloud/llms.txt

Build and run OxiCloud directly from source code. This method requires Rust 1.93+ and a PostgreSQL database to be set up.

```bash
cargo run
```

--------------------------------

### Get OpenAPI Specification

Source: https://context7.com/diocrafts/oxicloud/llms.txt

Fetches the OpenAPI JSON specification for the API, useful for understanding the API structure and generating clients.

```bash
curl -s http://localhost:8086/api/openapi.json | jq '.info'
```

--------------------------------

### Get Current Authenticated User

Source: https://github.com/diocrafts/oxicloud/blob/main/docs/config/authentication.md

Retrieves information about the currently authenticated user, including their identity, role, and storage details.

```APIDOC
## GET /api/auth/me

### Description
Return the current authenticated user.

### Method
GET

### Endpoint
/api/auth/me

### Response
#### Success Response (200)
Returns the authenticated user's identity, role, and storage information.
```

--------------------------------

### Create Folder

Source: https://context7.com/diocrafts/oxicloud/llms.txt

Creates a new folder. If `parent_id` is null, the folder is created in the user's home directory. The response includes the new folder's ID.

```bash
curl -s -X POST http://localhost:8086/api/folders \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Projects", "parent_id": null}'
```

--------------------------------

### Create User

Source: https://context7.com/diocrafts/oxicloud/llms.txt

Creates a new user account. Requires admin authentication and JSON payload with user details.

```bash
curl -s -X POST http://localhost:8086/api/admin/users \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"username": "bob", "email": "bob@example.com", "password": "TempPass1!", "role": "user"}'
```

--------------------------------

### Enable User Storage Quotas

Source: https://github.com/diocrafts/oxicloud/blob/main/docs/architecture/storage-quotas.md

Set this environment variable to true to enable per-user storage quotas.

```bash
OXICLOUD_ENABLE_USER_STORAGE_QUOTAS=true
```

--------------------------------

### List calendars using CalDAV

Source: https://context7.com/diocrafts/oxicloud/llms.txt

Use curl with PROPFIND to list calendars. Requires XML content specifying the properties to retrieve.

```bash
curl -u alice:password -X PROPFIND https://cloud.example.com/caldav/ \
  -H "Depth: 1" \
  -H "Content-Type: application/xml" \
  -d '<?xml version="1.0"?><D:propfind xmlns:D="DAV:"><D:allprop/></D:propfind>'
```

--------------------------------

### Delete Folders Recursively using cURL

Source: https://github.com/diocrafts/oxicloud/blob/main/docs/guide/batch-operations.md

Example using cURL to delete multiple folders recursively via the batch endpoint.

```bash
# Delete multiple folders recursively
curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"folder_ids":["old-1","old-2"],"recursive":true}' \
  "https://oxicloud.example.com/api/batch/folders/delete"
```

--------------------------------

### Download Folder as ZIP

Source: https://context7.com/diocrafts/oxicloud/llms.txt

Downloads the entire contents of a folder as a single ZIP archive. Requires authentication.

```bash
curl -s -H "Authorization: Bearer $TOKEN" \
  "http://localhost:8086/api/folders/$FOLDER_ID/download" -o folder.zip
```

--------------------------------

### Get Audio Metadata

Source: https://context7.com/diocrafts/oxicloud/llms.txt

Retrieves metadata for a specific audio file, such as title, artist, album, and duration. Requires the file ID.

```bash
curl -s -H "Authorization: Bearer $TOKEN" \
  "http://localhost:8086/api/playlists/audio-metadata/$FILE_ID"
```

--------------------------------

### Enable OIDC in .env configuration

Source: https://context7.com/diocrafts/oxicloud/llms.txt

Configure Oxicloud for OpenID Connect single sign-on by setting environment variables in the .env file. This enables integration with identity providers like Keycloak, Google, or Azure AD.

```bash
OXICLOUD_OIDC_ENABLED=true
OXICLOUD_OIDC_ISSUER_URL="https://authentik.example.com/application/o/oxicloud/"
OXICLOUD_OIDC_CLIENT_ID="oxicloud-client"
OXICLOUD_OIDC_CLIENT_SECRET="your-secret"
OXICLOUD_OIDC_REDIRECT_URI="https://cloud.example.com/api/auth/oidc/callback"
OXICLOUD_OIDC_SCOPES="openid profile email"
OXICLOUD_OIDC_FRONTEND_URL="https://cloud.example.com"
OXICLOUD_OIDC_AUTO_PROVISION=true          # Create users on first login
OXICLOUD_OIDC_ADMIN_GROUPS="oxicloud-admins"
OXICLOUD_OIDC_DISABLE_PASSWORD_LOGIN=false  # Allow both login methods
OXICLOUD_OIDC_PROVIDER_NAME="Authentik"
```

--------------------------------

### Get Dashboard Statistics

Source: https://context7.com/diocrafts/oxicloud/llms.txt

Retrieves key statistics for the OxiCloud dashboard, such as total users, active users, total files, and storage usage.

```APIDOC
## GET /api/admin/dashboard

### Description
Retrieves statistics for the OxiCloud dashboard.

### Method
GET

### Endpoint
/api/admin/dashboard

### Response
#### Success Response (200)
- **total_users** (integer) - Total number of users.
- **active_users** (integer) - Number of active users.
- **total_files** (integer) - Total number of files stored.
- **storage_used_bytes** (integer) - Total storage used in bytes.
```

--------------------------------

### Configure S3-Compatible Object Storage

Source: https://context7.com/diocrafts/oxicloud/llms.txt

Configures the object storage backend to use S3-compatible storage. Requires admin authentication and detailed S3 configuration parameters.

```bash
curl -s -X PUT http://localhost:8086/api/admin/settings/storage \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "backend": "s3",
    "bucket": "my-oxicloud-bucket",
    "region": "us-east-1",
    "endpoint": "https://s3.amazonaws.com",
    "access_key": "AKIAIOSFODNN7EXAMPLE",
    "secret_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
  }'
```

--------------------------------

### Rust Backend Build and Development Commands

Source: https://github.com/diocrafts/oxicloud/blob/main/CLAUDE.md

Common Cargo commands for building, running, testing, and linting the Rust backend. Includes commands for optimized builds, running with debug logging, and regenerating OpenAPI specifications.

```bash
cargo build                          # Dev build
```

```bash
cargo build --release                # Optimized release build
```

```bash
cargo run                            # Run server (port 8086)
```

```bash
cargo test --workspace               # Run all tests (~208)
```

```bash
cargo test <test_name>               # Run a single test by name
```

```bash
cargo test --features test_utils     # Run tests that use mockall mocks
```

```bash
cargo clippy -- -D warnings          # Lint (zero warnings policy)
```

```bash
cargo fmt --all --check              # Format check
```

```bash
cargo fmt --all                      # Auto-format
```

```bash
RUST_LOG=debug cargo run             # Run with debug logging
```

```bash
cargo run --bin generate-openapi     # Regenerate resources/gen/openapi.json
```

--------------------------------

### CardDAV well-known discovery

Source: https://context7.com/diocrafts/oxicloud/llms.txt

Perform a GET request to the well-known CardDAV URI to discover the CardDAV service. The -L flag follows redirects.

```bash
curl -u alice:password https://cloud.example.com/.well-known/carddav -L
```

--------------------------------

### User Registration

Source: https://github.com/diocrafts/oxicloud/blob/main/docs/config/authentication.md

Creates a new local user account by providing username, email, and password.

```APIDOC
## POST /api/auth/register

### Description
Create a local user account.

### Method
POST

### Endpoint
/api/auth/register

### Request Body
- **username** (string) - Required - The desired username.
- **email** (string) - Required - The user's email address.
- **password** (string) - Required - The user's password.

### Request Example
```json
{
  "username": "testuser",
  "email": "test@example.com",
  "password": "SecurePassword123"
}
```
```

--------------------------------

### CalDAV well-known discovery

Source: https://context7.com/diocrafts/oxicloud/llms.txt

Perform a GET request to the well-known CalDAV URI to discover the CalDAV service. The -L flag follows redirects.

```bash
curl -u alice:password https://cloud.example.com/.well-known/caldav -L
```

--------------------------------

### Create User

Source: https://context7.com/diocrafts/oxicloud/llms.txt

Creates a new user account with the specified username, email, password, and role.

```APIDOC
## POST /api/admin/users

### Description
Creates a new user.

### Method
POST

### Endpoint
/api/admin/users

### Request Body
- **username** (string) - Required - The username for the new user.
- **email** (string) - Required - The email address for the new user.
- **password** (string) - Required - The password for the new user.
- **role** (string) - Required - The role for the new user (e.g., 'user', 'admin').
```