Caching and Storage
Wallpaper Server keeps external originals in their source folders. A normal delete hides an external image; it does not unlink the source. Managed uploads move to recoverable private trash. Only explicit purge destroys a trashed upload.
What is stored where
Section titled “What is stored where”| Location | Contents | Backup policy |
|---|---|---|
wallpaper_folders |
Your original images | Back up originals. |
uploads_dir |
Uploaded originals and private .trash |
Back up the entire directory, including trash. |
data_dir/library.json |
Favourites, tags, identities, collections, rotation state and recovery intents | Durable private data; never clear it as cache. |
cache_dir |
Immutable original copies, thumbnails/ and disposable variants/ |
Rebuilt by a successful refresh; not an original-image backup. |
Paths are configurable; see the configuration reference. Use a single server process per data/cache directory.
Refresh and image snapshots
Section titled “Refresh and image snapshots”A refresh stages new original copies and JPEG thumbnails under private immutable
UUID filenames. It reconciles stable identities and persists metadata before
publishing the new index. Readers retain the previous snapshot during a failed
scan; a public image’s old cached bytes cannot be overwritten by a newly scanned
hidden image. Public /wallpapers/ID.ext URLs remain stable and resolve through
the visibility-checked index, not directly to arbitrary cache filenames.
Unchanged source revisions reuse analysis and cached files. Revision checks use size, modification time and available filesystem identity/change-time fields. Ambiguous duplicate moves never guess at ownership; see stable identity and monitoring.
Successful refreshes retain the current and previous cache snapshots and reclaim older UUID generations. Interrupted staging is reclaimed on later refreshes. Legacy ID-named caches and unrelated files are not automatically deleted. Original/thumbnail storage grows with the library; it has no fixed byte quota.
Rendered device variants have a separate 256 MiB / 1,024-entry budget, including temporary encodes. Oldest-written derivatives are evicted automatically. All image routes, including raw cache URLs, use private, no-store HTTP responses; this does not disable the server’s internal disk cache.
To clear cache, stop the service, remove only the configured image cache, and
restart or perform a successful refresh before serving requests. Never delete
data_dir or uploads_dir as part of cache cleanup.
Trash and interrupted operations
Section titled “Trash and interrupted operations”Delete and restore persist a recovery intent before moving an upload. Startup and refresh reconcile interrupted transitions without overwriting a destination collision. Recovery metadata and uploaded bytes must therefore be backed up and restored together. Old orphan trash files created before recovery intents existed cannot automatically recover their original paths.
Files are synced before atomic replacement. POSIX directory-sync errors remain commit errors. Windows validates directory access but does not attempt POSIX-style sync on read-only directory handles: process-interruption recovery is supported, not a guarantee against machine power loss. Network and unusual filesystems must support the required atomic operations; failures are reported, not silently accepted as successful commits.