PhotoStack

A self-hosted photo library. Drop in your photos and PhotoStack reads when and where they were taken, builds a timeline, groups them into albums, puts them on a map, and finds duplicates. Think a small, understandable Google Photos you run yourself.

Website · Live demo (read-only, sample photos)

Features

• Timeline: every photo, grouped by day, keeping its real shape (portrait stays portrait)
• Reads your photos: date, camera, lens, exposure and GPS from EXIF; iPhone HEIC included
• Videos: MP4, MOV and WebM with thumbnails, duration, date and place (needs ffmpeg; included in the Docker image)
• Albums: your own albums, plus automatic month albums
• Map: photos on a map as thumbnails, with street addresses (OpenStreetMap)
• Search: by place, camera, tag or file name
• Duplicates: finds copies even when resized or re-saved, keeps the original
• Integrity checks: real file type, SHA-256, signs of editing, data hidden after the image
• Library health: what needs fixing (unreadable files, no date, no location, duplicates), with a retry button
• Light and dark mode, works on phones
• Optional AI tags: off by default; with a Gemini key, photos get descriptive tags

Run it

Docker (simplest):

docker compose up --build

Open http://localhost:8000. Photos and the database live in the photostack_data volume.

For development (needs uv, Node 20+, and optionally ffmpeg for video thumbnails):

uv sync
npm --prefix frontend install
npm --prefix frontend run build
uv run uvicorn photostack.main:app --reload

You can also copy photos straight into uploads/; they're indexed at startup.

Settings

All optional, via environment variables or a .env file (see .env.example):

Variable	Default	What it does
DATABASE_URL	sqlite:///./photostack.db	Any SQLAlchemy URL; Postgres needs uv sync --extra postgres
UPLOADS_DIR	uploads	Where photos, thumbnails and previews are stored
GEOCODING_ENABLED	true	Look up street addresses for GPS positions
GEMINI_API_KEY	unset	Turns on AI tagging (needs uv sync --extra ai). Sends 400px thumbnails to Google
DEMO_MODE	false	Public demo: fully read-only, with example albums from demo-photos/albums.json

How it works

FastAPI backend, React frontend, SQLite by default. Uploads return immediately; a background task reads EXIF, makes WebP thumbnails, fingerprints the image for duplicate detection, and then (optionally) geocodes and tags it.

See docs/ARCHITECTURE.md for the data model, the upload flow, and why each design decision was made.

photostack/   backend: routers → crud → models; indexer, integrity, storage
frontend/     React + TypeScript + Tailwind
tests/        pytest, runs offline against SQLite

Development

uv run pytest                          # backend tests
uv run ruff check && uv run ruff format --check
npm --prefix frontend run typecheck

Deploying the demo

The public demo runs on Render's free tier from render.yaml (Dashboard → New → Blueprint → this repo). It runs the Docker image with DEMO_MODE=true: read-only, seeded with demo-photos/ on every start, no AI. Free instances sleep when idle, so the first visit can take up to a minute.

The project website is docs/index.html, published with GitHub Pages from /docs.

License

MIT