Gallery

Media gallery app for browsing, filtering, and organizing AI-generated images and videos. Backend (FastAPI + SQLite) indexes media from configurable paths, extracts metadata (prompts, models, LoRAs), and serves a React frontend with infinite scroll, filters, collections, ratings, and slideshow.

Prerequisites

• Python 3.12+ (backend)
• Node.js 18+ and npm (frontend)
• uv or pip for Python dependencies

Repository layout

gallery/
├── backend/           # FastAPI app, indexer, DB
│   ├── app/
│   │   ├── main.py    # API routes, startup
│   │   ├── config.py  # Config loading
│   │   ├── db.py      # SQLite engine, sessions
│   │   ├── indexer.py # Scan paths, extract metadata, thumbnails
│   │   └── models.py  # SQLModel schemas
│   └── config.yaml    # Scan paths, DB path, thumb dir, port (create from example)
├── frontend/          # Vite + React + TypeScript
│   ├── src/
│   │   ├── App.tsx
│   │   ├── components/  # UI and gallery components
│   │   └── lib/         # API client, types
│   └── package.json
├── start-backend.sh   # Run backend (optionally build frontend)
├── pyproject.toml     # Python project / root deps
└── README.md

Backend

• Framework: FastAPI
• DB: SQLite via SQLModel/SQLAlchemy
• Config: backend/config.yaml — define scan_paths, db_path, thumb_dir, thumb_size, port, scan_interval_seconds

Setup and run

From the project root:

# Create venv and install backend deps (if using uv)
uv sync

# Or with pip (install fastapi uvicorn sqlmodel Pillow etc. per backend needs)
pip install -r backend/requirements.txt  # if present, or install from pyproject

# Edit backend/config.yaml: scan_paths, db_path, thumb_dir, port

# Run backend (serves API and, if built, frontend static files)
./start-backend.sh

# Optional: build frontend before starting
./start-backend.sh --build

Backend runs at http://0.0.0.0:8000 by default. API docs at http://localhost:8000/docs.

• Initial scan runs in the background at startup (server does not block on it).
• Periodic scans run on the interval set in config.

Frontend

• Stack: Vite, React 19, TypeScript, Tailwind CSS, shadcn-style UI
• API base: Set VITE_API_BASE_URL when the frontend is served from a different origin (e.g. http://localhost:8000). Leave unset when using the same host (backend serves frontend/dist).

Setup and run

cd frontend
npm install
npm run dev      # Dev server (e.g. http://localhost:5173)
npm run build    # Production build → frontend/dist
npm run preview  # Preview production build

Use npm run dev and point the app at the backend (e.g. proxy or VITE_API_BASE_URL) for local development.

Running the full app

1. Backend only (serves built frontend):
   ./start-backend.sh --build then open http://localhost:8000.

2. Dev frontend + backend:
   Terminal 1: ./start-backend.sh --skip-build
   Terminal 2: cd frontend && npm run dev
   Open http://localhost:5173 and set VITE_API_BASE_URL=http://localhost:8000 if needed.

Configuration summary

Item	Where	Purpose
Scan paths, DB, thumbs, port	backend/config.yaml	What to index, where DB and thumbnails live, server port
API base URL	frontend/.env or env	VITE_API_BASE_URL for API requests from the dev server
Auth password and session secret	Environment variables	Configures the single-user login gate

Authentication

Auth is enabled by default. Set a password and session secret before starting the backend:

export GALLERY_AUTH_PASSWORD="change-me"
export GALLERY_SESSION_SECRET="$(openssl rand -hex 32)"

# Optional; defaults to admin
export GALLERY_AUTH_USERNAME="admin"

# Optional
export GALLERY_SESSION_DAYS="7"
export GALLERY_COOKIE_SECURE="false"
export GALLERY_CORS_ORIGINS="http://localhost:5173,http://127.0.0.1:5173"

For local-only development, auth can be disabled explicitly:

export GALLERY_AUTH_ENABLED="false"

Set GALLERY_COOKIE_SECURE=true when serving the app over HTTPS. Do not commit real credentials or session secrets.

Key features (for devs)

• Media list: Paginated, filterable by type, model, LoRA, list/collection, rating, date range, full-text search (FTS5 + LIKE fallback).
• Collections: CRUD lists; filter gallery by list; add/remove items from detail panel.
• Slideshow: Filtered set with backend-configured item limit (slideshow_limit in backend/config.yaml), configurable image duration, video plays to end then next, arrow keys, fullscreen, download current.
• Zip export: Download shown items as a zip with backend-configured cap (zip_download_limit in backend/config.yaml).