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.
- 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
Rangesupport for video seeking - Cursor-paginated REST API (stable asset IDs, no paths exposed)
- Docker-first — no local Rust, libvips, ffmpeg, or Postgres installation needed
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:5173The 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:5173The backend auto-restarts on Rust file changes via cargo-watch.
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"cp docker/.env.example docker/.env
# Edit docker/.env: set PG_PASSWORD, MEDIA_PATH, ADMIN_EMAIL, ADMIN_PASSWORDCompose'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.
docker compose -f docker/docker-compose.yml up --build -d
# → API + frontend at http://localhost:3000Every 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) |
profile=1— 256px max (grid)profile=2— 1024px max (detail)
The thumbnail endpoint selects format based on the Accept header:
image/avif → AVIF, image/webp → WebP, else JPEG.
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.
Two credential types resolve through the same session/token table:
- Browser (web console) —
POST /api/auth/loginwith just{email, password}sets anHttpOnlysession cookie. Admin-only: a correct password for a non-admin account still gets403 Forbiddenhere — 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/loginwith{email, password, device_name}returns a long-lived bearertokeninstead of a cookie; send it asAuthorization: Bearer <token>on every request. Works for every account, admin or not. Revoke a lost/old device viaDELETE /api/auth/devices/:id(your own) orDELETE /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).
| 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.
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