📸 ImgVault

A self-hosted photo and video management application designed for Unraid and Docker environments. ImgVault automatically indexes your media library, extracts metadata, generates thumbnails, and provides a fast, modern web UI for browsing, searching, and organizing your photos and videos.

All-in-one: everything (FastAPI backend, SQLite database, Nginx, React frontend) runs inside a single container. No external database, Redis, or sidecar containers required — all metadata and thumbnails are stored locally on your array.

✨ Features

• Automatic Indexing — Parallel multithreaded scan of your photo directory, indexes new/changed files in the background
• Quick Reindex — Skip-hashing scan that picks up only newly added files (seconds instead of hours on large libraries); full reindex still available for metadata refresh
• EXIF Metadata Extraction — Camera, lens, ISO, aperture, shutter speed, GPS coordinates
• Reverse Geocoding — Language-aware resolution of GPS coordinates to country, city, and location names (via Nominatim) with persistent SQLite cache
• WebP Thumbnails — Generates optimized WebP thumbnails for fast grid loading (~30% smaller than JPEG)
• Video Support — Indexes MP4, MOV, AVI, MKV, WebM and more; extracts duration, generates 1-second frame thumbnails via ffmpeg, on-the-fly transcoding for MOV/HEVC, HTTP Range streaming
• HEIC/HEIF Support — Full support for Apple HEIC/HEIF formats with automatic JPEG conversion for browser display
• Smart Cleanup — Finds exact duplicates (by file hash), similar photos (by pHash hamming distance), plus short and oversized videos
• Map View — Browse photos by location on an interactive map with server-side clustering and language-aware location names
• Virtual Albums — Group photos and videos into custom albums without moving files on disk
• Statistics Dashboard — Storage breakdown, camera usage, timeline, and location stats by country/city
• Folder Browsing — Navigate your library by folder structure
• Timeline Slider — Filter photos by date range
• Search — Full-text search across filenames, locations, cameras, and folders
• Photo Viewer — Pinch-to-zoom on mobile, scroll-wheel and double-click zoom on desktop, persistent thumbnail strip, swipe navigation
• Settings Hub — Centralized view for theme, language, reindexing, stats, cleanup and trash
• Trash / Recycle Bin — Soft-delete with auto-purge after 30 days
• PWA Support — Installable as a Progressive Web App with offline thumbnail caching via Service Worker
• Mobile Friendly — Responsive minimalist dark theme with bottom navigation and iOS-aware layout

🏗️ Architecture

ImgVault is a single-container application with three components:

┌─────────────────────────────────────┐
│           Docker Container          │
│                                     │
│  ┌──────────┐    ┌───────────────┐  │
│  │  Nginx   │───▶│  FastAPI      │  │
│  │  :8080   │    │  :3001        │  │
│  │          │    │               │  │
│  │ Static   │    │ /api/*        │  │
│  │ Files    │    │ Indexer       │  │
│  └──────────┘    │ Geocoder      │  │
│                  │ SQLite DB     │  │
│                  └───────────────┘  │
└─────────────────────────────────────┘

🚀 Installation

Docker Compose (Recommended)

version: "3.8"
services:
  imgvault:
    image: imgvault:latest
    build: .
    container_name: imgvault
    ports:
      - "8180:8080"
    volumes:
      - /path/to/your/photos:/data/photos:rw
      - imgvault_db:/data/db
      - imgvault_thumbs:/data/thumbnails
      - imgvault_transcoded:/data/transcoded
      - imgvault_converted:/data/converted
      - imgvault_trash:/data/trash
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/api/health"]
      interval: 30s
      timeout: 5s
      start_period: 60s

volumes:
  imgvault_db:
  imgvault_thumbs:
  imgvault_transcoded:
  imgvault_converted:
  imgvault_trash:

Unraid (Community Applications)

The easiest way to install on Unraid is via the bundled CA template.

1. In Unraid, open the Apps tab → Install from URL (or paste this template URL into a new container):

   https://raw.githubusercontent.com/Tjindarr/ImgVault/main/templates/imgvault.xml
   

2. Defaults are already set:

   Field	Value
   Repository	ghcr.io/tjindarr/imgvault:latest
   WebUI Port	Host 8180 → Container 8080
   Photos	/mnt/user/Pictures → /data/photos
   Appdata	/mnt/user/appdata/imgvault/* → /data/db,thumbnails,transcoded,converted,trash

3. Adjust the Photos path to point at your media library, then click Apply. The UI is available at http://<UNRAID_IP>:8180.

Manual volume mappings (if not using the template):

Port: 8180 → 8080

Building from Source

# Clone the repository
git clone https://github.com/Tjindarr/ImgVault.git
cd imgvault

# Build the Docker image
docker build -t imgvault .

# Run it
docker run -d \
  --name imgvault \
  -p 8180:8080 \
  -v /path/to/photos:/data/photos \
  -v imgvault_db:/data/db \
  -v imgvault_thumbs:/data/thumbnails \
  -v imgvault_transcoded:/data/transcoded \
  -v imgvault_converted:/data/converted \
  -v imgvault_trash:/data/trash \
  imgvault

⚙️ Configuration

All configuration is done via environment variables:

📡 API Reference

All endpoints are prefixed with /api/.

Health & Status

Indexing

Photos

Folders

Statistics

Map

Cleanup

Trash

🗂️ Supported Formats

Images

.jpg .jpeg .png .gif .bmp .webp .tiff .tif .heic .heif .avif

Videos

.mp4 .mov .avi .mkv .webm .m4v .wmv .flv

Note: HEIC/HEIF, TIFF, BMP, and AVIF images are automatically converted to JPEG for browser display. MOV, AVI, MKV, WMV, and FLV videos are transcoded to MP4 on first play.

🧠 Technical Details

Indexing Pipeline

1. File Discovery — Recursively scans PHOTOS_DIR for supported media files
2. Change Detection — Compares file hash (size + mtime + first 8KB) against stored hashes; skips unchanged files. Quick mode skips hashing entirely and only processes paths not yet in the database
3. Parallel Processing — Multithreaded worker pool extracts metadata and generates thumbnails concurrently
4. Metadata Extraction — EXIF data via exifread (JPEG/TIFF) or Pillow (HEIC/PNG/WebP)
5. Thumbnail Generation — WebP thumbnails at 400×400 max using Pillow (images) or ffmpeg 1-second frame extraction (videos)
6. Perceptual Hashing — Computes pHash via imagehash for content-based similarity detection
7. Reverse Geocoding — GPS coordinates → country/city/location via Nominatim API with SQLite-backed cache (~1km grid)
8. Database Upsert — Stores all metadata in SQLite with WAL mode for concurrent reads

Similarity Detection

• Exact Duplicates: Matched by file_hash (identical file content)
• Similar Photos: Matched by pHash hamming distance ≤ 10 (configurable), detecting visually similar images regardless of resolution, format, or minor edits

Performance Optimizations

• SQLite WAL mode for concurrent read/write
• Composite indexes on (country, city), (folder), (date_taken), (phash)
• Server-side map clustering — Groups thousands of markers into clusters via SQL aggregation
• Persistent geocode cache — Avoids redundant Nominatim API calls across reindexes
• Service Worker caching — Thumbnails cached for 30 days (up to 5,000 entries), API metadata cached for 5 minutes
• WebP thumbnails — ~30% smaller than JPEG equivalents

🛠️ Development

Prerequisites

• Node.js 20+
• Python 3.12+
• ffmpeg / ffprobe

Frontend

npm install
npm run dev

The dev server runs on http://localhost:8080 and proxies /api/ requests to the backend at :3001.

Backend

cd backend
pip install -r requirements.txt
export PHOTOS_DIR=/path/to/your/photos
export THUMB_DIR=/tmp/thumbs
export DB_PATH=/tmp/snapvault.db
python -m uvicorn main:app --host 0.0.0.0 --port 3001 --reload

Running Tests

npm run test          # Unit tests (Vitest)
npx playwright test   # E2E tests (Playwright)

📄 License

MIT — see LICENSE.