File Scanning & Importing

Heaper can scan local folders and external storage to create blocks for your files. The original files stay in place — Heaper creates lightweight references with thumbnails and metadata. This is a server only feature to have a central place for your data that is easy to back up.

How File Scanning Works

1. Scan — Heaper's backend walks the filesystem and discovers files and folders
2. Index — For each file, a block is created with metadata (name, size, hash, MIME type, dimensions)
3. Thumbnails — Preview images are generated in multiple sizes (small, medium, large)
4. Deduplicate — Files are identified by their SHA-256 content hash, so duplicates are detected automatically

Mounting Storage (Self-Hosted)

If you're self-hosting, you can mount additional storage directories into the Heaper container. Heaper is a multi-user setup, so the folder structure is as follows. First the user id, then the heap id.

services:
  heaper:
    volumes:
      - /mnt/MyBigDisk:/mnt/storage # general storage mount on your drive
      - /mnt/MySSD:/mnt/thumbnails # fast storage for thumbnails
      - /path/to/your/documents:/mnt/storage/USERID/HEAPID/documents # put a folder in your heap
      - /path/to/your/fullheap:/mnt/storage/USERID/HEAPID # or the whole heap to a folder
      - /path/to/your/photos:/mnt/storage/photos:ro     # Read-only mount

After mounting, trigger a scan to index the new files. The :ro (read-only) flag is only recommended if you do not want to manage/delete/create files through Heaper.

Importing Files

Desktop

• Drag and drop files into the content area
• Use the plus button in the bottom navigation, then choose to Media to upload any file from your filesystem

Mobile

• Use the plus button in the bottom navigation, to select files from your device's file picker
• Use the plus button in the bottom navigation, then choose to Media to upload any file from your gallery.
• Share files from other apps directly into Heaper

File Metadata

For each scanned or imported file, Heaper stores:

Folder Structure

Heaper preserves the folder hierarchy from scanned directories. Just the client maps these different to the synced folders to be more space and write-efficient.

Re-Scanning

When files change on disk, re-scanning updates the metadata and thumbnails. New files are added, and modified files are updated based on their content hash. Deleted files are not automatically removed — this prevents accidental data loss if a drive is temporarily disconnected.