A high-performance, self-hosted Django gallery and file browser, built on a hybrid file system + database design. Point it at a directory tree of images, PDFs, archives, video, and audio, and it indexes, thumbnails, and serves them through a fast, responsive web UI.
This README covers the essentials — installation, running it, and a feature overview. For architecture, deployment options, database schema, and everything else, the docs/ directory is the complete, authoritative reference; start at docs/QuickBBS.md.
- File Areas / Image Galleries — comprehensive gallery system with database-stored thumbnails
- Multi-format support — images, PDFs, archives, text files, movies, audio, and more
- High performance — thumbnail caching in PostgreSQL for optimal I/O, plus ASGI support (HTTP/1.1 and HTTP/2)
- Real-time monitoring — watchdog-based file system monitoring for automatic cache invalidation
- Responsive design — multiple thumbnail sizes for desktop and mobile
- Search & browse — file and directory search with metadata indexing
- Modern template system — Jinja2 macros with a component architecture
- Progressive Web App — HTMX-powered dynamic updates without full page reloads
- Background task worker — thumbnail generation and maintenance run outside the request cycle via
django-dbtasks - Passkey login — optional passwordless (WebAuthn) authentication
Gallery cells are color-coded by filetype — blue for directories, pink for
images, yellow for PDFs/links, gray for movies/audio — so you can tell what
you're looking at before a thumbnail even loads. These colors are just
defaults seeded by refresh_filetypes and can be freely redefined per
extension (via the Django admin or the seed command) to match your taste.
 |
 |
 |
.png) |
More screenshots — PDF viewing, thumbnails, and video playback — are in docs/Screenshots.md, including the full filetype color legend.
Requires Python 3.12–3.14, Django 6.1+, and PostgreSQL. Django 6.1 is a hard minimum — FileIndex/DirectoryIndex use the DB_CASCADE/DB_SET_NULL on_delete options (DB-enforced ON DELETE constraints), which don't exist before 6.1.
git clone https://github.com/bschollnick/quickbbs.git
cd quickbbs
poetry installgunicorn, uvicorn, hypercorn, and granian are optional Poetry extras — poetry install alone installs none of them. Add the one you plan to deploy with, e.g. poetry install --extras granian (or --extras all-servers for all four). See docs/Web Servers.md for details.
Configure your database and gallery root, then run migrations:
cd quickbbs
python manage.py migrateQuickBBS needs two processes running side by side — the web server and the background task worker (thumbnail generation won't happen without it):
# Web server (development)
python manage.py runserver 0.0.0.0:8888
# Background task worker (separate terminal)
python manage.py taskrunner -w 4For production, QuickBBS is tested against Granian and Hypercorn (both ASGI, native HTTP/2). Other ASGI/WSGI servers such as Uvicorn, Daphne, and Gunicorn should also work but aren't part of our regular test cycle. Large-scale deployments may instead front the app with Apache, nginx, or Caddy as a reverse proxy — see docs/Web Servers.md for full deployment options, reverse proxy configs, HTTPS setup, and installing the server you choose as a Poetry extra.
The docs/ directory is where the complete documentation lives — this README is intentionally just a quick-start. Head there for anything beyond the basics, including:
- Full documentation — start here
- Screenshots — UI tour and filetype color legend
- Web Servers & Deployment
- Database ERD
- Links & Aliases
- Version History
- Design documents — architecture and design rationale
MIT — see license.txt.