Skip to content

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Pixelvault

A self-hosted media server. Point it at directories of images and videos — it indexes them into PostgreSQL, generates thumbnails (AVIF/WebP/JPEG) via libvips, and presents everything through a clean browser UI. The web UI is an admin-only console; regular users back up photos through a mobile app (native Android, planned) straight into the library, and never see the web app.

Features

  • Index photos and videos from one or more filesystem roots
  • Both scanned and uploaded files are auto-organized into <year>/<month>/ folders by taken date (EXIF, falling back to file time), with automatic filename-collision handling
  • Manual API-triggered scan (no file watcher)
  • Authenticated upload endpoint for mobile/device backup clients, content-hash deduplicated (uploading the same photo twice is a no-op)
  • Accounts: an admin manages users and devices from the web console; every account (admin or not) can browse the library and upload via device token, but only an admin can log into the web UI itself
  • Thumbnails generated on-demand in AVIF / WebP / JPEG via content negotiation
  • HEIC/HEIF decode support via libheif
  • Video poster frames via ffmpeg
  • HTTP Range support for video seeking
  • Cursor-paginated REST API (stable asset IDs, no paths exposed)
  • Docker-first — no local Rust, libvips, ffmpeg, or Postgres installation needed

Quick Start (Development)

Prerequisites: Docker + Docker Compose

# 1. Clone and enter the repo
git clone <repo> pixelvault && cd pixelvault

# 2. Drop some images/videos into sample_media/
cp ~/Pictures/*.jpg sample_media/

# 3. Start everything (Postgres + backend with hot reload)
docker compose -f docker/docker-compose.dev.yml up

# 4. Open a new terminal and start the frontend dev server
cd frontend
npm install
npm run dev
# → http://localhost:5173

The dev compose file seeds a default admin (admin@example.com / dev_admin_password — dev only, never use these values outside local dev). Log in, then:

# 5. Trigger a scan (needs the admin session/cookie, or use the UI)
curl -X POST http://localhost:3000/api/scan -b <cookie jar>

# 6. Browse your library at http://localhost:5173

The backend auto-restarts on Rust file changes via cargo-watch.

Production Deployment

1. Generate the sqlx offline query cache (first time only, or after changing a query)

The production Docker build is fully offline — it doesn't need a live database. But it needs a pre-generated query cache from your development database.

./scripts/generate-sqlx-cache.sh
# Commits the .sqlx/ directory output to your repo
git add .sqlx/ && git commit -m "chore: add sqlx offline cache"

2. Configure environment

cp docker/.env.example docker/.env
# Edit docker/.env: set PG_PASSWORD, MEDIA_PATH, ADMIN_EMAIL, ADMIN_PASSWORD

Compose's project directory defaults to the compose file's directory (docker/), not your cwd — .env must live there, not at repo root, or vars silently default to blank. Same applies to MEDIA_PATH/UPLOAD_PATH: relative paths resolve against docker/, not repo root, so to point at the repo-root sample_media/ use MEDIA_PATH=../sample_media (or an absolute path).

ADMIN_EMAIL/ADMIN_PASSWORD only take effect once, on first boot while no users exist yet — they seed the first admin account and are safe to leave set afterward. Leave them unset and the server logs a warning and starts anyway; every endpoint except /api/health stays unreachable until an admin exists.

Auto-organizing your existing library requires write access. The primary media root is mounted read-only (:ro) by default — fine if you don't want the scanner rearranging files it finds, but it means newly-dropped flat files won't get moved into <year>/<month>/. Drop :ro from the photos volume mount in docker/docker-compose.yml if you want that.

3. Deploy

docker compose -f docker/docker-compose.yml up --build -d
# → API + frontend at http://localhost:3000

API Reference

Every endpoint under /api requires authentication except /api/health and /api/auth/login — see Authentication below.

Method Path Access Description
GET /api/health public Health check
POST /api/auth/login public {email, password, device_name?} → session cookie, or {token} if device_name is set
POST /api/auth/logout any Revoke the calling session/token
GET /api/auth/me any Current user
GET /api/auth/devices any List your own device tokens
DELETE /api/auth/devices/:id any Revoke one of your own device tokens
GET /api/admin/users admin List all users
POST /api/admin/users admin Create a user
PATCH /api/admin/users/:id admin Update password / admin flag / disabled
DELETE /api/admin/users/:id admin Delete a user
GET /api/admin/users/:id/devices admin List another user's device tokens
DELETE /api/admin/devices/:id admin Revoke any user's device token
POST /api/scan admin Trigger a scan, returns { job_id }
GET /api/scan any List recent scan jobs
GET /api/scan/:id any Get scan job status
GET /api/assets any Paginated asset list (limit, cursor, kind)
GET /api/assets/:id any Single asset metadata
GET /api/assets/:id/file any Stream original file (Range supported)
GET /api/assets/:id/thumbnail?profile=1 any Thumbnail (Accept negotiation)
POST /api/upload/check any {items: [sha256, ...]} → {missing: [sha256, ...]}
POST /api/upload any Upload one file (see below)

Thumbnail profiles

  • profile=1 — 256px max (grid)
  • profile=2 — 1024px max (detail)

Content negotiation

The thumbnail endpoint selects format based on the Accept header: image/avif → AVIF, image/webp → WebP, else JPEG.

Uploading a file

POST /api/upload takes the raw file body plus headers: X-Content-Sha256 (required, the file's sha256 hex digest — verified server-side), X-Filename (required), X-Taken-At (optional RFC3339, used when the file has no EXIF date, e.g. video). Response is {status: "created"|"duplicate", id}.

Dedup is by content hash, not filename or location — uploading the same photo twice, even under a different name, is always a no-op. Call /api/upload/check first with a batch of hashes to skip files already backed up without uploading anything.

The web console has a drag-and-drop uploader that does exactly this (hash client-side via crypto.subtle, check, upload only what's missing). It requires a secure context (HTTPS or localhost) — the browser has no way to hash a file otherwise — and buffers each file in memory to hash it, so it caps uploads at 512 MB; anything larger needs the mobile app.

Authentication

Two credential types resolve through the same session/token table:

  • Browser (web console) — POST /api/auth/login with just {email, password} sets an HttpOnly session cookie. Admin-only: a correct password for a non-admin account still gets 403 Forbidden here — it does not leak whether the password was right, just that this account can't use the web UI. Use the device-token login instead for that account.
  • Device (mobile app) — POST /api/auth/login with {email, password, device_name} returns a long-lived bearer token instead of a cookie; send it as Authorization: Bearer <token> on every request. Works for every account, admin or not. Revoke a lost/old device via DELETE /api/auth/devices/:id (your own) or DELETE /api/admin/devices/:id (any user's, as an admin).

Every account can browse the whole library and upload via device token; only admins can log into the web UI, manage users (/api/admin/*), or trigger a scan (POST /api/scan).

Configuration

Env Var Default Description
DATABASE_URL required Postgres connection string
MEDIA_ROOTS required name:/path,name2:/path2
CACHE_DIR ./cache Thumbnail cache directory
LISTEN_ADDR 0.0.0.0:3000 Bind address
STATIC_DIR — Serve frontend from this dir (production)
RUST_LOG — Log filter (e.g. pixelvault=debug)
ADMIN_EMAIL / ADMIN_PASSWORD — Seed the first admin on first boot (only while no users exist)
UPLOAD_ROOT_NAME — Name (from MEDIA_ROOTS) that receives uploads; uploads disabled if unset or unmatched
COOKIE_SECURE false Set true only behind HTTPS — a Secure cookie is silently dropped over plain HTTP
SESSION_TTL_DAYS 30 Browser session cookie lifetime; device tokens never expire on their own
CORS_ORIGIN — Comma-separated extra origins for credentialed cross-origin requests (unneeded for the default same-origin deployment)

Note: thumbnails and originals are plain <img src> / <video src> requests, which only send cookies same-origin. The default deployments (prod serves the SPA from STATIC_DIR; dev goes through the Vite proxy) are same-origin, so this is invisible — a cross-origin VITE_API_BASE setup would show broken images despite a valid session. Not fixed here; worth knowing if you reach for CORS_ORIGIN.

Architecture

frontend/       Vite + React (TanStack Query, Tailwind)
backend/        Rust (axum, sqlx, libvips, ffmpeg)
docker/         dev.Dockerfile, prod.Dockerfile, compose files
.sqlx/          sqlx offline query cache (commit after prepare)
sample_media/   Mount point for test files in dev

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages