Network storage

Your libraries can live on a NAS, over NFS or SMB. Trove recognises a network share when you add the folder and changes how it treats it, so a flaky connection or another computer adding books doesn't catch it out.

Setting it up

1. Mount the share on the server that runs Trove, the usual way for your system (an /etc/fstab entry for NFS or CIFS, for example). Make sure the user Trove runs as can read the folder, and write to it if you want Trove to save metadata into files or organise them.
2. With Docker, pass the mounted folder into the container as a volume, the same way as a local folder:

   volumes:
     - /mnt/nas/books:/books

3. Add the folder to a library. In the library dialog it shows a Network share badge with the kind of filesystem, such as nfs4 or cifs.

What changes for a share

New books are found by checking

A network share doesn't tell the server when another computer adds, renames or removes a file, so Watch folders can't rely on being told. For folders on a share, Trove looks for changes every 60 seconds instead, and does a full re-scan every tenth check. Change the interval with the NETWORK_POLL_SECONDS environment variable.

It's careful about outages: if the share goes offline, can't be read, or suddenly appears to have lost half its books, Trove leaves the library alone until the folder looks normal again, rather than removing books that are only temporarily out of reach.

Files are never written in place

Whenever Trove changes a book file (saving metadata into it, importing from Bookdrop, uploading, or moving and renaming files), it:

1. builds the new file on the server's own disk and checks it's a sound EPUB, PDF, comic or audiobook,
2. copies it onto the share next to the original, under a hidden temporary name,
3. reads the copy back and compares it byte for byte,
4. and only then swaps it in for the original.

If the connection drops part way, the original is untouched and the copy is tried again (up to three times). Leftover temporary files from an interrupted copy are cleaned up later.

File names stay portable

When Trove names files from a file naming pattern, it avoids what SMB and Windows reject: the characters : ? * " < > |, names ending in a space or full stop, and reserved names like CON or LPT1. Renames that only change upper or lower case work on case-insensitive shares too.

Checking your files

The Check Book File Integrity task in Tasks reads every book and reports any that are damaged, checking each entry's checksum in EPUB and comic archives and the structure of PDFs and audiobooks. It's worth running after moving a library onto a NAS.

Keeping Trove out of your files entirely

If you'd rather Trove didn't change your book files, set DISK_TYPE=NETWORK. Trove then keeps metadata and covers in its own database only: it stops writing them into book files, stops writing sidecar files, and won't rename or move files. Reading, scanning and everything else still work. The default, DISK_TYPE=LOCAL, allows all of these, on a share as well as on local disk.

What's been tested

This behaviour has been tested on a real SMB share, including pulling the network in the middle of a large copy. NFS uses the same code but hasn't yet been tried against real hardware; if you use it, keep backups and check with the integrity task.