Hydrus Nextbooru

A Next.js-based image gallery that syncs with Hydrus Network.

A live demo filled with random Touhou images is running at https://nextbooru-demo.lattemacchiato.dev/.

You can browse, search by tags, and view images/videos without depending on Hydrus once the sync is done. Only the location Hydrus stores the files is required to be accessible from the server, all metadata is locally saved after syncing.

Warning

Still WIP. Don't use if you aren't okay with starting a fresh sync when you update.

Unorganized feature list:

• Tag-based search with autocomplete and co-occurrence filtering + wildcard support + meta tags (file types)
• Category-based (artist, character, copyright, meta, general)
• Automatic post grouping based on source URLs (Pixiv, Twitter, dA, Danbooru, Gelbooru) and titles
• Lazy loading images with blurhash placeholders and thumbnail previews
• Search query builder tree, with progressively narrowing down tags
• Thumbnail generation of many file types (including animated ones)
• Very fast server-side rendering
• Fast searches with optimized queries
• Incremental sync (to a point, Hydrus requires scanning everything but Nextbooru minimizes unneeded writes)
• OpenRouter-based translations of post titles, bodies and images

Try the demo to get a feel for it.

Requirements

• Hydrus Network with Client API enabled and available in network for first sync

Runtime:

• Docker

or

• Node.js 25+ (or Bun for faster execution, default in docker image)
• PostgreSQL 18+ (lower works, but recommend 18+ for performance)

Setup

Grab the docker-compose.yml and adjust the Hydrus bind mount. Copy .env.example to .env, then fill in the variables to fit your setup.

Note: Nextbooru should run behind a reverse proxy supporting caching for performance. Ensure you pass X-Forwarded-For to the server.

Development Setup

Use the docker compose stack for actual deployment!

1. Clone the repository

2. Install dependencies:

   npm install

3. Configure environment variables:

   cp .env.example .env

   Edit .env with your settings:

   DATABASE_URL=postgresql://user:password@localhost:5432/booru
   HYDRUS_API_URL=http://localhost:45869
   HYDRUS_API_KEY=your_api_key_here
   HYDRUS_FILES_PATH=/path/to/hydrus/db/client_files
   

4. Set up the database:

   npm run db:generate
   npm run db:deploy

5. Build the server:

   npm run build

6. Start the server:

   npm start

See documentation contained within for usage guidance.

Performance

My personal "production" server running Nextbooru holds 110k files with 140k tags, with 60k groups. Up to this database size I will optimize for speed, I cannot guarantee how it scales past it.

Open for improvements, PRs and whatever of course.