Library as the file store
This page explains how Library keeps the files of other Foxden apps, which apps use it, and what that means for your storage and your backups.
Library is an app people use for pages and files. It is also the suite's file store: once your server links an app to Library, every file that app keeps is stored in Library, in one place that is deduplicated and backed up with Library. People never see these files in Library's spaces; each app still shows its own files on its own screens.
Which apps keep their files in Library
| App | What it keeps there |
|---|---|
| Fennec | Client documents and each of their versions, uploaded proposals, partner agreements. |
| Corsac | Original documents, sealed documents, certificates, signature images, logos. |
| Pampas | Respondents' uploads, exports, share images, fonts. |
| Culpeo | Images pasted into conversations. |
| Foxden Admin | Files an AI assistant uploads through the gateway, kept for seven days. |
Arctic and Cape keep their own files, including meeting and call recordings, in their own volumes. Library's own pages and files are in the same store.
How an app decides where to write
Every app gets its file store from one shared function, productObjectStore, which decides on every call:
- Linked to Library: the app has the secret for its link to Library (named
files:<app>) and knows Library's address. Every new file goes to Library. Files the app wrote before it was linked are still read from its own folder. - Not linked: the app writes to its own folder, as an app running alone does.
The secret is derived from the server's box key when both apps are installed together with foxden, or set by hand (LIBRARY_FILES_SECRET in the app, the matching FILES_SECRET_<APP> in Library). foxden link set writes both ends; Server › Products in Admin offers the same. Because the decision is made on every call, an app needs no restart beyond the one that loads its new settings.
What Library does with a file
The request and its checks are traced in Key flows, end to end. In short:
- Each app reaches only its own files. The app signs each request with its own link secret, and Library files the bytes under that app's name. Another app's secret cannot read or write them.
- A file is written once. Writing to a name that exists is refused, so a file is never replaced. A new version is a new file.
- The bytes are checked. The app signs the SHA-256 of the bytes, and Library refuses bytes that hash to anything else.
- Identical bytes are stored once, whichever app or page they belong to.
- Deleting is delayed. Deleting removes the name at once; the bytes are removed by Library's sweeper after the retention period (35 days unless you set
LIBRARY_BLOB_RETENTION_DAYS), so restoring a database snapshot that still names a file finds it. - The size limit is Library's (
LIBRARY_MAX_FILE_MB, 500 MB unless you change it).
Where the bytes are on disk
Library keeps every file in its store: a Docker volume by default, or an S3-compatible bucket when you set all four of Library's S3 keys. Plan Library's disk for every linked app's files, not only Library's own. See Running Library and Server sizes.
Backups
Library's nightly backup holds its database (encrypted with the backup passphrase), a list of every file the database names (other apps' files included), and a copy of those files. It fails if a named file is missing, rather than writing a backup that cannot be restored.
The copy of the files is kept as plain files in Library's backups folder, not encrypted with the passphrase. The off-site copy that foxden backup offsite set and Admin's Backups page set up sends Library's database backup, not the files. To keep the files off the server too, set up an encrypted rclone remote (rclone's crypt type) and name it on the server:
foxden config set LIBRARY_FILES_REMOTE <remote>: --product libraryUntil both off-site copies are set, Library's backup log says each backup is local only.
Once an app is linked, its new files are in Library's backup, not in the app's own. Restore Library with the apps that keep files in it, and keep Library's retention period longer than the number of days your backups are kept (14 unless you change it). See Back up and restore.