Using Shared Cache

Shared Cache is an on-prem server that enables teams to securely share files that have been accessed by other team members within the same LAN.

As an example:

1. Team Member 1 access large_video.mp4 while connected to the shared cache

2. ShadeFS begins serving that file to Team Member 1 from the cloud

3. In the background, the shared cache also begins caching large_video.mp4

4. The shared cache fully finishes caching large_video.mp4

5. Team Member 2 now accesses large_video.mp4 in ShadeFS

6. The shared cache runs permission checks to validate Team Member 2 has access to large_video.mp4

7. large_video.mp4 is immediately served at the maximum speed of the LAN from the shared cache

In this setup, the second access is both served at the maximum speed making playback largely instant and avoids using bandwidth against the cloud. Large shared cache instances can almost entirely avoid cloud round trips except for the first access.

Download & Setup

Shared Cache is a terminal executable with no UI. You can get a version to download by asking us. The defaults are generally correct for most setups meaning for most people it's typically just a double click to launch.

S3 Support

Shared Cache supports using both a local (disk) backend and an on prem S3 target for caching data. This can be enabled by passing --storage-backend=s3 with the endpoint, bucket, region, access, and secret.

Configuration Options

Usage: shared-cache [options]

Options:
  --port <number>                    Server port (default: 8003)
  --fs-ws-url <url>                  Upstream ShadeFS WebSocket URL (default: wss://fs.shade.inc)
  --fs-api-url <url>                 Upstream ShadeFS API URL (default: https://fs.shade.inc)
  --local-cache-location <path>            Cache storage directory (default: ./cache)
  --database-location <path>         SQLite database file path (default: ./shared_cache.db)
  --max-cache-size <bytes>           Maximum cache size in bytes (default: 500GB)
  --cache-check-interval <ms>        Cache cleanup interval in milliseconds (default: 300000)
  --storage-backend <type>           Storage backend: filesystem or s3 (default: filesystem)
  --discovery-server-name <name>     mDNS service name (default: Default Name)

  S3 Storage Options (when --storage-backend=s3):
  --s3-endpoint <url>                S3 endpoint URL
  --s3-bucket <name>                 S3 bucket name
  --s3-region <region>               S3 region
  --s3-access-key-id <key>           S3 access key ID
  --s3-secret-access-key <secret>    S3 secret access key
  --s3-path-prefix <prefix>          S3 key prefix (optional)

  Advanced Options:
  --download-worker-count <number>   Number of download workers (default: 5)
  --download-concurrent-chunks <n>   Concurrent chunks per worker (default: 4)
  --download-chunk-size <bytes>      Download chunk size (default: 128MB)
  --upload-concurrent-chunks <n>     Concurrent upload chunks (default: 4)
  --upload-chunk-size <bytes>        Upload chunk size (default: 64MB)
  --version, -v                      Show version information
  --help, -h                         Show this help message

Environment Variables:
  All options can also be set via environment variables using SCREAMING_SNAKE_CASE.
  Example: PORT, FS_WS_URL, CACHE_LOCATION, MAX_CACHE_SIZE_BYTES, etc.

Examples:
  ./shared-cache --port 8080 --local-cache-location /var/cache/shade
  ./shared-cache --storage-backend s3 --s3-bucket my-bucket --s3-region us-east-1
  PORT=8080 LOCAL_CACHE_LOCATION=/var/cache/shade ./shared-cache

Joining the Shared Cache

Because the permissions are handled by the Shared Cache, joining is incredibly easy and requires no password. The shared cache advertises using bonjour. In most cases clients on the same network detect it and a modal will pop up asking if they would like to join.

If no modal appears, the cache can be joined directly by going to Settings → Shared Cache → Connect Manually and typing in the address. An example input might look like http://192.168.1.45:8003