# Damselfly Photo Management for Large Server Libraries

> Damselfly indexes folder-based photo collections and searches them through IPTC metadata, file and folder names, visual similarity, and computer vision results. It is aimed at users who want a shared browser interface for large libraries, although the documentation does not provide a complete installation or startup command.

**Webreaper/Damselfly** — Damselfly is a server-based Photograph Management app. The goal of Damselfly is to index an extremely large collection of images, and allow easy search and retrieval of those images, using metadata such as the IPTC keyword tags, as well as the folder and file names. Damselfly includes support for object/face detection.

- Repository: https://github.com/Webreaper/Damselfly
- Stars: 1,795 · Forks: 95
- Language: C#
- License: GPL-3.0
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/webreaper-damselfly

## Damselfly's target library and tagging workflow

Damselfly is designed for a large photo collection kept on a server and organised through folders. Its central problem is making that collection searchable without requiring every device to hold a separate catalogue or database. The README says users can search through IPTC keyword tags, folder names, and file names. That is useful when an existing library already contains useful metadata, but it also means Damselfly benefits from files being named and tagged before indexing.

The intended workflow begins on a laptop, where photographs are sorted, quality checked, and tagged with Picasa or DigiKam. The README then describes an Rclone script syncing new files across the LAN to a network share. Once those files reach the server library, Damselfly detects them, indexes them, and generates thumbnails. According to the documented workflow, this normally happens within 30 minutes. Search results can be added to a basket, after which a selected group can be downloaded or copied locally for editing in Lightroom, ON1, DigiKam, Photoshop, or another application.

This approach separates the authoritative library from the editing environment. Damselfly provides a central catalogue and a repeatable selection mechanism, while external tools handle detailed work. It is also a sensible division for teams that want several people to search one library without duplicating the full collection on every workstation. The cost is that edited files must currently be copied back manually. Synchronisation of local changes to the server remains a planned feature, so users must include that step in their own procedure.

## Indexing, metadata search, and image recognition

Based on the repository layout and README, Damselfly is implemented as a.NET solution with separate projects for core services, database models, image processing, machine learning, the server, the Blazor web client, and an Electron.NET desktop client. The web front end is Blazor WebAssembly, backed by EF Core 7. The repository also includes SQLite migrations, while the compose file builds a container named `damselfly.web`.

The catalogue combines metadata and computer vision information. Full-text search supports multiple phrases and partial words. Advanced filters cover date ranges, camera and lens details, file size, orientation, missing keyword tags, visually similar images, detected objects, detected faces, and identified faces. This gives users several routes into a large collection. A keyword search can locate an image through its IPTC data, while visual filters can find images that have no dependable caption or useful filename.

Face detection, face recognition, object detection, and colour classification are documented capabilities. The current version supports face recognition locally and offline. The README explains that Damselfly formerly depended on the Microsoft Azure Face API, but access to that API was restricted. The local and offline direction removes that particular external dependency, although the repository does not document hardware requirements, accelerator support, memory consumption, or the exact operational cost of processing a very large library.

Keyword tagging is described as non-destructive because ExifTool updates metadata without re-encoding JPEG files. That distinction matters for photographers. Re-encoding can introduce generation loss or alter image data, while metadata-only updates preserve the image payload. The exact ExifTool configuration and error-handling process are not included in the repository documentation, so deployments should confirm write permissions and backup original files before allowing tags to be changed.

## Server roles, baskets, exports, and desktop integration

Damselfly supports user accounts and role-based entitlements. The repository links to separate multi-user documentation, and the README gives `ReadOnly` as an example of a role that prevents keyword tagging. This makes the application relevant to shared environments where some users may browse or export images but should not modify their metadata.

A basket collects selected images from search results. It can be private to one user or shared with others. Images in that basket can be downloaded, exported for applications such as DigiKam or Photoshop, or uploaded to WordPress. Export processing can also apply watermarks, and the README mentions watermarked output for social media and sending images by email. The basket is therefore more than a transient selection list. It acts as the handoff point between searching, selecting, exporting, and local editing.

The Electron.NET desktop client provides tighter operating system integration than the browser interface. The README lists desktop builds for macOS, Windows, and Linux, along with synchronisation from a server basket to a local folder. This does not create a two-way editing workflow. The documented procedure still requires the user to copy changed files back to the server so indexing can pick them up.

The server model also introduces operational responsibilities that the README does not fully describe. It does not document backup commands, database restoration, upload size limits, storage quotas, authentication configuration, or reverse-proxy setup. Those omissions do not establish that the functions are absent, but they prevent the README from serving as a complete production deployment guide.

## Docker deployment and the first library search

The repository provides Docker assets, but the README does not give an install command or explain how to supply the image library, database location, credentials, or application settings. Because the documentation gives no launch command, this tutorial does not invent one. The repository's `docker-compose.yml` is the confirmed deployment definition:

```yaml
version: '3.4'

services:
  damselfly.web:
    image: ${DOCKER_REGISTRY-}damselfly
    build:
      context: .
      dockerfile: Dockerfile
```

This defines one service, `damselfly.web`, builds from the repository `Dockerfile`, and permits `DOCKER_REGISTRY` to override the image namespace. The `Dockerfile` identifies `webreaper/damselfly-base:2.0.1` as its base image, copies the published application and desktop assets, exposes port `6363`, and starts `/damselfly-entrypoint.sh`. These are useful facts for deployment, but the README does not document the required volume mappings or environment variables, so the configuration should be completed from the repository's deployment documentation rather than guessed.

For a first real use, copy a small set of images into the intended server library before indexing the entire collection. Tag representative JPEGs with IPTC keywords, retain meaningful folder and file names, and add a `.nomedia` file to any directory that must be skipped. The README says background indexing updates the collection when files are added or changed and normally completes within 30 minutes. After indexing, verify that the files appear in the web interface, open one image, and search for its IPTC keyword, part of its filename, and part of its folder name. This first pass checks the complete path from filesystem access through metadata extraction to browser search before processing hundreds of thousands of files.

## Format coverage, file organisation, and current boundaries

Damselfly documents support for JPG, PNG, HEIC, TIFF, WebP, BMP, and several RAW extensions, including DNG, CR2, ORF, and NEF. That range covers common photographic and image formats, but the README does not describe sidecar metadata, colour-profile handling, malformed files, or recovery after a failed import. It also lists additional formats and possible video support as planned enhancements.

The application can move or copy images between folders and delete them through a trashcan folder. Background indexing then updates the catalogue as the library changes. A `.nomedia` marker provides a direct way to exclude a directory. These features make Damselfly more than a read-only index, but they also make filesystem permissions and backup strategy important. The README does not say whether database records and image files can be restored independently, so copying the image library alone may not be a complete backup.

Several boundaries are explicit. Image de-duplication is in progress. Simple non-destructive editing, including cropping and colour adjustment, is in progress. Two-way synchronisation from a local desktop back to the server is planned. DamselFly can export selected images, but it does not currently describe a complete local editing loop. Users who need those missing workflows should either accept manual steps or choose a different system rather than treating planned features as available functionality.

## Damselfly versus conventional folder and desktop workflows

A conventional desktop catalogue keeps the index close to the editing software and often fits a photographer who works from one computer. Damselfly takes a different approach: the server owns the library, the browser provides shared access, and the desktop client transfers selected basket items for local editing. This is more relevant when several devices or users need to search one collection, or when a camera workflow already stores files on a network share.

A file manager plus operating-system search offers simpler storage without a database or computer vision index, but it does not provide the documented combination of IPTC full-text search, visual similarity, face identification, object filters, shared baskets, and role-based metadata permissions. Damselfly adds a server application, database maintenance, metadata scanning, and image analysis in exchange for those capabilities.

For a small collection that already fits comfortably within a desktop tool, that server overhead may not be worthwhile. For a shared collection approaching the scale described in the README, Damselfly's indexing model and search filters address a real organisational problem. Its limits are equally concrete: startup is underdocumented, restoration procedures are not given in the README, return synchronisation is unfinished, and planned editing and de-duplication features should not be assumed.

## Release history, GPL-3.0, and upgrade planning

The repository is not archived, and its last push was on 2026-09-29. The latest listed release is version 4.5.3, published on 2026-01-14. Earlier listed releases are 4.2.3 from 2025-01-07 and 4.2.2 from 2024-12-31. These dates indicate recent repository activity and a release history with substantial gaps, so an adopter should not assume that every deployment receives frequent releases.

Damselfly is licensed under GPL-3.0. For organisations modifying and distributing the application, that licence creates source-code and notice obligations associated with covered derivative works. This is not legal advice. The practical upgrade question is broader than copying new files into a container: releases may change database migrations, metadata handling, machine learning components, client assets, and server behaviour. The repository contains `Damselfly.Migrations.Sqlite`, so database migration is part of the codebase rather than an incidental concern.

Before upgrading, preserve the server-side image library and database, record the currently deployed image tag, and review the release notes for migration instructions. The README does not provide rollback or backup commands. It also does not explain how to restore a database after a failed migration. Those are concrete deployment checks, not generic maintenance advice. An installation that can restore both indexed data and original photographs is safer than one that treats a container restart as a sufficient recovery plan.

## Conclusion

Damselfly fits photographers and teams with a large, shared, folder-based library who need metadata search, computer vision, and controlled image selection from several devices. It is less suitable for users who require documented one-command setup, cloud synchronization in both directions, or immediate access to features listed as planned rather than complete. Before adoption, verify startup with the repository's Docker files and deployment documentation, then test indexing, EXIF writing, permissions, backup procedures, and the return of edited files against the intended library.

## FAQ

### What file formats does Damselfly support?

The README lists JPG, PNG, HEIC, TIFF, WebP, BMP, and RAW formats including DNG, CR2, ORF, and NEF. It also says that support for additional image formats and possibly video is planned.

### Does Damselfly support face recognition without an online service?

Yes. The README says the latest version supports face detection and recognition locally and offline, replacing the earlier dependence on the Microsoft Azure Face API.

### How are new photographs added to a Damselfly library?

The suggested workflow copies or syncs new images to a server network share, where background indexing detects them, indexes their metadata, and generates thumbnails. The README says this normally happens within 30 minutes.

## Sources

- [Issues](https://github.com/Webreaper/Damselfly/issues)
- [License: GPL-3.0](https://github.com/Webreaper/Damselfly/blob/master/LICENSE)
- [README](https://github.com/Webreaper/Damselfly/blob/master/README.md)
- [Releases](https://github.com/Webreaper/Damselfly/releases)
- [Webreaper/Damselfly on GitHub](https://github.com/Webreaper/Damselfly)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/webreaper-damselfly