Simple Private Image Server

SPIS (Simple Private Image Server) is a lean, high‑performance web service designed to serve large collections of media files from a private file system. Unlike feature‑heavy gallery solutions, SPIS focuses on speed, minimalism, and zero external dependencies. It is written in Rust and leverages async I/O to handle thousands of concurrent image requests with sub‑millisecond latency, making it ideal for embedded deployments such as Raspberry Pi Compute Modules or edge devices.

Architecture & Technical Stack

• Language: Rust 1.70+ – guarantees memory safety and zero‑cost abstractions.
• Web Framework: axum (async, request‑routing) combined with tower middleware for rate limiting and logging.
• File System: Direct FS access; no relational or NoSQL database. Metadata is derived on‑the‑fly from file paths and extended attributes, allowing instant indexing of 40k+ images on a single disk.
• Image Processing: image crate for thumbnail generation and format conversion; thumbnails are cached in memory using a LRU cache to avoid disk I/O on repeat requests.
• PWA Support: Service workers and manifest files are served statically, enabling offline browsing and “add to home screen” functionality on mobile browsers.

The server exposes a REST‑style API under /api for programmatic access (listing, filtering by date/favorites, marking favorites) and a thin SPA front‑end built with vanilla JavaScript. The API uses JSON and supports pagination, eager loading of thumbnails, and WebSocket push for real‑time updates when new media is added to the watched directory.

Core Capabilities

• Endless Scrolling: The API supports cursor‑based pagination, letting the front‑end fetch additional pages as the user scrolls.
• Favorites & Filtering: Users can toggle favorites, which are stored as simple text files or extended attributes; filtering by year/month/favorites is performed server‑side with minimal CPU overhead.
• Instant File Discovery: A background worker watches the media directory (notify crate) and triggers thumbnail regeneration whenever a new file appears, ensuring zero latency between upload and visibility.
• PWA & Mobile Optimisation: The static assets are served with aggressive caching headers; the service worker pre‑caches the initial page and thumbnails for offline access.

Deployment & Infrastructure

SPIS ships as a single statically linked binary, eliminating the need for runtime dependencies. It can be run natively or inside Docker; a minimal docker-compose.yml is included in the repo. For production, the recommended stack is:

1. Reverse Proxy: Nginx or Caddy with TLS termination.
2. Systemd Service: On Debian/Raspberry Pi, a simple unit file ensures the binary restarts on failure.
3. Autoscaling: The stateless design allows horizontal scaling behind a load balancer if the media repository is network‑mounted.

Because SPIS does not maintain an internal database, scaling is limited only by the underlying storage throughput. This makes it trivial to clone a Docker image and run multiple replicas that share the same media directory over NFS or SMB.

Integration & Extensibility

• Plugin System: While SPIS currently exposes a minimal plugin hook, the codebase is structured to allow future extensions (e.g., OAuth authentication or custom metadata stores) without breaking the core.
• Webhooks: The API can emit events via HTTP callbacks when new media is detected, enabling downstream services (e.g., indexing or backup scripts) to react automatically.
• Configuration Templating: Environment variables and a simple templating engine (tera) let developers inject dynamic values (e.g., media path, port) into the config at startup.

Developer Experience

• Zero‑config: The server starts with sensible defaults; optional flags or env vars override them. Running spis help lists all options.
• Comprehensive Docs: The README covers CLI usage, Docker deployment, and advanced configuration. Inline comments in the source are plentiful, and the test suite exercises most public APIs.
• Community & Licensing: MIT‑licensed, so you can embed SPIS in proprietary projects. The GitHub repo has an active issue tracker and pull‑request flow, making contributions straightforward.

Use Cases

1. Personal Photo Vault – Host a private gallery on a Raspberry Pi, accessible over LAN or VPN, with instant updates when new photos are dropped.
2. Embedded Surveillance – Serve camera snapshots from an edge device, allowing real‑time browsing on a mobile phone without cloud services.
3. Static Site Image Proxy – Use SPIS as an image CDN for a static site, benefiting from local caching and fast delivery without external billing.

Advantages Over Alternatives

• Performance: Async Rust guarantees low CPU usage and high throughput, outperforming typical Node.js or Python backends for image serving.
• Simplicity: No database, no ORM; a single binary plus optional reverse proxy is all that’s needed.
• Scalability: Statelessness and minimal I/O make horizontal scaling trivial, while the lightweight footprint keeps memory usage below 50 MiB on a Pi CM4.
• Licensing: MIT allows unrestricted use, even in closed‑source applications, unlike some GPL‑licensed gallery solutions.

In summary, SPIS delivers a developer‑friendly, production‑ready photo server that excels where speed, low overhead, and straightforward deployment are paramount.