Deploying Damselfly

Damselfly is a server-based digital asset management system designed for photographers, creative professionals, and anyone managing large photo and media collections. Built with modern .NET technologies and Blazor, Damselfly provides a fast, responsive web interface for browsing, organizing, searching, and sharing your media files. The application excels at handling RAW image formats, extracting EXIF metadata, and generating intelligent thumbnails while maintaining a lightweight footprint.

Unlike traditional photo management software that requires desktop installations, Damselfly runs entirely in your browser and can be accessed from any device. It features AI-powered face detection, keyword tagging, advanced search capabilities, and basket collections for organizing shoots or projects. The system is particularly well-suited for professional photographers who need to manage tens of thousands of images with efficient search, filtering, and batch operations.

Why Deploy Damselfly on Klutch.sh?

Deploying Damselfly on Klutch.sh offers several advantages for hosting your digital asset management system:

Automatic Docker Detection: Klutch.sh automatically recognizes your Dockerfile and handles the containerization process without manual configuration
Persistent Storage: Built-in volume management ensures your photo library, thumbnails, and metadata are safely preserved across deployments and container restarts
Performance: Klutch.sh’s infrastructure provides the computational resources needed for thumbnail generation and image processing operations
Simple HTTP Routing: Access your media library through HTTPS with automatic SSL certificate provisioning
Scalability: Handle large photo collections with persistent storage that can scale based on your needs
Remote Access: Access your photo library from anywhere with internet connectivity while maintaining control over your data
Resource Efficiency: Containerized deployment ensures efficient resource utilization for media processing workloads

Prerequisites

Before deploying Damselfly to Klutch.sh, ensure you have:

A Klutch.sh account (sign up at klutch.sh)
A GitHub account with a repository for your Damselfly deployment
Basic understanding of Docker and containerization concepts
Familiarity with .NET applications and web servers
Git installed on your local development machine
Understanding of persistent storage requirements for media files

Understanding Damselfly Architecture

Damselfly follows a modern web application architecture built on .NET and Blazor:

Core Components

Blazor WebAssembly Frontend The user interface is built with Blazor WebAssembly, providing a responsive single-page application experience. This approach enables rich interactive features like drag-and-drop, real-time filtering, and smooth image browsing without page reloads. The frontend communicates with the backend API for all data operations.

ASP.NET Core Web API The backend is powered by ASP.NET Core, providing RESTful API endpoints for image metadata retrieval, search operations, thumbnail generation, and configuration management. The API handles authentication, authorization, and all business logic for media processing.

Image Processing Engine Damselfly includes a sophisticated image processing engine that handles:

Thumbnail generation at multiple resolutions
RAW image format support (CR2, NEF, ARW, DNG, etc.)
EXIF metadata extraction and parsing
Face detection using machine learning models
Color space conversion and image optimization

SQLite Database Metadata, tags, keywords, collections, and user preferences are stored in a SQLite database. This lightweight database solution provides fast queries for searching and filtering large image collections without requiring external database servers.

File System Watcher A background service monitors the configured image directories for changes, automatically indexing new images and updating metadata when files are added, modified, or removed. This ensures the database stays synchronized with the file system.

Thumbnail Cache Generated thumbnails are stored in a dedicated cache directory, organized by image hash and resolution. This caching mechanism significantly improves browsing performance by avoiding redundant image processing.

Data Flow

User accesses the Blazor web interface through their browser
Frontend requests image metadata from the ASP.NET Core API
API queries the SQLite database for image information
If thumbnails don’t exist, the processing engine generates them
Thumbnails and metadata are returned to the frontend
Background watcher monitors file system for new images
New images are processed, analyzed, and indexed automatically
Search queries execute against the indexed metadata in SQLite

Storage Requirements

Damselfly requires persistent storage for several critical components:

Image Library: Your original photos and RAW files (size varies by collection)
Thumbnail Cache: Generated thumbnails at multiple resolutions (approximately 1-5% of original file sizes)
Database: SQLite database containing metadata, tags, and indexes (typically under 1GB for 100,000 images)
Configuration: Application settings and user preferences
AI Models: Face detection models and machine learning data

Installation and Setup

Let’s walk through setting up Damselfly for deployment on Klutch.sh.

Step 1: Create the Project Structure

First, create a new directory for your Damselfly deployment:

mkdir damselfly-deployment
cd damselfly-deployment
git init

Step 2: Create the Dockerfile

Create a Dockerfile in the root directory. We’ll use the official Damselfly image as a base:

FROM webreaper/damselfly:latest

# Set working directory
WORKDIR /app

# Expose the web interface port
EXPOSE 6363

# Set environment variables
ENV ASPNETCORE_URLS=http://+:6363
ENV SYNO_THUMBS=true
ENV DAMSELFLY_THUMBS=/thumbs

# Create necessary directories
RUN mkdir -p /pictures /thumbs /config

# Set volumes
VOLUME ["/pictures", "/thumbs", "/config"]

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
  CMD curl -f http://localhost:6363/health || exit 1

# Start Damselfly
CMD ["dotnet", "Damselfly.Web.dll"]

Step 3: Create Configuration Files

Create a config directory for application settings:

mkdir config

Create config/appsettings.json:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Information"
    }
  },
  "AllowedHosts": "*",
  "Damselfly": {
    "SourceDirectory": "/pictures",
    "ThumbsDirectory": "/thumbs",
    "EnableFaceDetection": true,
    "EnableAIAnalysis": true,
    "MaxConcurrentJobs": 4,
    "ThumbnailSizes": [
      { "Name": "Small", "Width": 320, "Height": 240 },
      { "Name": "Medium", "Width": 640, "Height": 480 },
      { "Name": "Large", "Width": 1280, "Height": 960 },
      { "Name": "ExtraLarge", "Width": 1920, "Height": 1440 }
    ],
    "SupportedFormats": [
      ".jpg", ".jpeg", ".png", ".gif", ".bmp", ".tiff", ".tif",
      ".cr2", ".nef", ".arw", ".dng", ".raf", ".orf", ".rw2"
    ],
    "EnableWatcher": true,
    "WatcherDelaySeconds": 5,
    "CpuLevel": "Medium",
    "EnablePerformanceMonitoring": true
  },
  "Authentication": {
    "Enabled": false,
    "Provider": "Local"
  }
}

Step 4: Create Environment Configuration

Create a .env.example file for reference:

# Server Configuration
ASPNETCORE_URLS=http://+:6363
ASPNETCORE_ENVIRONMENT=Production

# Damselfly Paths
DAMSELFLY_PICTURES=/pictures
DAMSELFLY_THUMBS=/thumbs
DAMSELFLY_CONFIG=/config

# Processing Configuration
SYNO_THUMBS=true
CPU_LEVEL=Medium
MAX_CONCURRENT_JOBS=4

# Feature Flags
ENABLE_FACE_DETECTION=true
ENABLE_AI_ANALYSIS=true
ENABLE_WATCHER=true

# Database
DATABASE_PATH=/config/damselfly.db

# Performance
THUMBNAIL_CACHE_SIZE=5000
INDEX_BATCH_SIZE=100

Step 5: Create Docker Compose for Local Development

Create docker-compose.yml for local testing:

version: '3.8'

services:
  damselfly:
    build: .
    ports:
      - "6363:6363"
    volumes:
      - ./pictures:/pictures
      - ./thumbs:/thumbs
      - ./config:/config
    environment:
      - ASPNETCORE_URLS=http://+:6363
      - ASPNETCORE_ENVIRONMENT=Development
      - SYNO_THUMBS=true
      - CPU_LEVEL=Medium
      - MAX_CONCURRENT_JOBS=4
      - ENABLE_FACE_DETECTION=true
      - ENABLE_AI_ANALYSIS=true
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:6363/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 60s

Step 6: Create .dockerignore

Create a .dockerignore file to optimize the build:

node_modules
npm-debug.log
.git
.gitignore
README.md
.env
*.md
docker-compose.yml
pictures/
thumbs/
.DS_Store
Thumbs.db

Step 7: Create a README

Create README.md with deployment information:

# Damselfly Deployment

This repository contains the configuration for deploying Damselfly on Klutch.sh.

## Features

- Digital asset management for photos and media
- Support for RAW image formats
- AI-powered face detection
- EXIF metadata extraction
- Advanced search and filtering
- Basket collections for organizing shoots
- Responsive web interface

## Storage Requirements

- `/pictures` - Your photo library (size varies)
- `/thumbs` - Generated thumbnails (1-5% of originals)
- `/config` - Database and configuration files (< 1GB typically)

## Environment Variables

See `.env.example` for configuration options.

## Deployment

This application is configured to deploy on Klutch.sh with automatic Docker detection.

Step 8: Initialize Git Repository

git add .
git commit -m "Initial Damselfly setup for Klutch.sh deployment"
git branch -M master
git remote add origin https://github.com/yourusername/damselfly-deployment.git
git push -u origin master

Deploying to Klutch.sh

Now that your Damselfly application is configured, let’s deploy it to Klutch.sh.

Log in to Klutch.sh
Navigate to klutch.sh/app and sign in with your GitHub account.
Create a New Project
Click “New Project” and select “Import from GitHub”. Choose the repository containing your Damselfly deployment.
Configure Build Settings
Klutch.sh will automatically detect the Dockerfile in your repository. The platform will use this for building your container.
Configure Traffic Settings
Select “HTTP” as the traffic type. Damselfly serves its web interface on port 6363, and Klutch.sh will route HTTPS traffic to this port.
Set Environment Variables
In the project settings, add the following environment variables:
- ASPNETCORE_URLS: http://+:6363
- ASPNETCORE_ENVIRONMENT: Production
- SYNO_THUMBS: true
- CPU_LEVEL: Medium
- MAX_CONCURRENT_JOBS: 4
- ENABLE_FACE_DETECTION: true
- ENABLE_AI_ANALYSIS: true
- ENABLE_WATCHER: true
Configure Persistent Storage
Damselfly requires persistent storage for your photo library, thumbnails, and configuration:
- Pictures Volume:
  - Mount path: /pictures
  - Size: Allocate based on your photo collection size (e.g., 50GB-500GB)
- Thumbnails Volume:
  - Mount path: /thumbs
  - Size: Allocate 5-10% of your pictures volume size (e.g., 5GB-50GB)
- Configuration Volume:
  - Mount path: /config
  - Size: 2GB (sufficient for database and settings)
These volumes ensure your photos, generated thumbnails, and database persist across deployments and container restarts.
Deploy the Application
Click “Deploy” to start the build process. Klutch.sh will:
- Clone your repository
- Build the Docker image using your Dockerfile
- Deploy the container with the specified configuration
- Provision an HTTPS endpoint
The initial deployment may take several minutes as the container downloads dependencies and initializes the database.
Access Your Media Library
Once deployment completes, Klutch.sh will provide a URL like example-app.klutch.sh. Visit this URL to access your Damselfly instance.
Upload Initial Photos
You’ll need to upload photos to the /pictures directory. Options include:
- Using SFTP to access the volume directly
- Mounting the volume and copying files
- Configuring automatic sync from cloud storage
After uploading, Damselfly will automatically index and process your images.
Monitor Initial Indexing
The first time Damselfly starts with a photo collection, it will:
- Scan all images in the /pictures directory
- Extract EXIF metadata from each image
- Generate thumbnails at multiple resolutions
- Run face detection (if enabled)
- Build the search index
This process runs in the background and may take several hours for large collections. You can start using the interface immediately, with more images appearing as indexing progresses.

Getting Started with Damselfly

Once your Damselfly instance is deployed and has indexed your photos, here’s how to use it effectively:

Initial Setup

Navigate to your deployed URL
The first launch will create the database and initialize settings
Damselfly will start scanning the /pictures directory automatically
Check the “Indexing Status” to monitor progress

Browsing Your Photo Library

Grid View The default view displays your photos in a responsive grid with thumbnails. You can:

Scroll infinitely through your collection
Click any image to open the detail view
Use arrow keys to navigate between images
Adjust thumbnail size with the slider

Timeline View Switch to timeline mode to see photos organized chronologically:

Group by year, month, week, or day
Quickly jump to specific dates
View shooting patterns and activity

Folder View Browse your collection by the original folder structure:

Navigate through directories
Maintain your existing organization
Useful for shoot-based workflows

Searching and Filtering

Damselfly provides powerful search capabilities:

Keyword Search

sunset beach 2024

Searches through filenames, EXIF data, tags, and keywords.

Metadata Filters

Camera: Filter by camera model (e.g., “Canon EOS R5”)
Lens: Show images from specific lenses
Date Range: Select start and end dates
ISO Range: Find images within ISO bounds
Aperture: Filter by f-stop range
Focal Length: Show images at specific focal lengths

Advanced Filters

File Type: RAW, JPEG, PNG, etc.
Orientation: Portrait, landscape, square
Rating: Star ratings you’ve assigned
Flag Status: Picked, rejected, or unflagged
Color Label: Organize by color tags

Organizing with Tags and Keywords

Adding Keywords

Select one or more images
Click “Edit Keywords” in the toolbar
Type keywords separated by commas
Keywords are written to image EXIF data

Creating Collections (Baskets)

Click “Create Basket” to start a new collection
Drag images into the basket
Use baskets for projects, exports, or sharing
Baskets persist until you delete them

Ratings and Flags

Press 1-5 to assign star ratings
Press P to mark as picked
Press X to mark as rejected
Use keyboard shortcuts for rapid culling

Face Detection and Recognition

If face detection is enabled:

Navigate to “People” section
Damselfly will show detected faces
Click a face to assign a name
Once trained, the system will automatically tag faces
Search for photos by person name

Single Image Export

Open an image in detail view
Click “Download” to get the original file
Choose thumbnail size for smaller versions

Batch Export

Select multiple images or a basket
Click “Export Selection”
Choose destination format and quality
Download as ZIP archive

Creating Shareable Links Damselfly supports generating public links for specific images or collections (when enabled in settings).

Metadata Editing

Bulk EXIF Editing

Select multiple images
Click “Edit Metadata”
Modify fields like:
- Title and description
- Copyright information
- Keywords and tags
- Date taken
Changes are written back to image files

Viewing EXIF Data

Open any image to see full EXIF details
View camera settings, GPS coordinates, lens data
Check file information and color profile

Production Best Practices

To run Damselfly effectively in production on Klutch.sh, follow these recommendations:

Storage Planning

Volume Sizing Strategy Calculate your storage needs:

Pictures Volume = Total photo collection size + 20% growth
Thumbnails Volume = Pictures Volume × 0.05 to 0.10
Config Volume = 2GB minimum (database grows with collection size)

Example for 100GB photo collection:

Pictures: 120GB (100GB + 20% growth)
Thumbnails: 10GB (10% of pictures)
Config: 2GB
Total: 132GB

Storage Organization Organize your photo library efficiently:

/pictures/
  ├── 2024/
  │   ├── 01-January/
  │   ├── 02-February/
  │   └── ...
  ├── 2023/
  └── Archives/

This structure helps with:

Logical organization
Easier backup management
Selective indexing if needed

Performance Optimization

Indexing Configuration Optimize indexing for large collections:

{
  "Damselfly": {
    "MaxConcurrentJobs": 4,
    "IndexBatchSize": 100,
    "CpuLevel": "Medium",
    "EnablePerformanceMonitoring": true
  }
}

CPU Level Settings

Low: 2 concurrent jobs, slower indexing
Medium: 4 concurrent jobs, balanced performance
High: 8+ concurrent jobs, faster indexing but higher CPU usage

Thumbnail Generation Configure thumbnail sizes based on usage:

{
  "ThumbnailSizes": [
    { "Name": "Small", "Width": 320, "Height": 240 },
    { "Name": "Medium", "Width": 640, "Height": 480 },
    { "Name": "Large", "Width": 1280, "Height": 960 }
  ]
}

Fewer sizes = less storage and faster generation.

Database Maintenance

Regular Backups Backup the SQLite database regularly:

Access the /config volume
Copy damselfly.db to secure storage
Schedule weekly backups
Test restoration procedures

Database Optimization Damselfly automatically optimizes the database, but you can manually trigger optimization:

sqlite3 /config/damselfly.db "VACUUM;"
sqlite3 /config/damselfly.db "ANALYZE;"

Index Rebuilding If search performance degrades:

Navigate to Settings → Database
Click “Rebuild Search Index”
Wait for completion (can take hours for large collections)

Security Configuration

Authentication Setup Enable authentication for multi-user or public deployments:

{
  "Authentication": {
    "Enabled": true,
    "Provider": "Local",
    "RequireAuthentication": true
  }
}

User Management

Create user accounts through the admin interface
Assign different permission levels
Enable audit logging for user actions

File Access Control Restrict file system access:

Use read-only mounts if users shouldn’t upload
Implement network-level restrictions
Monitor access logs regularly

Monitoring and Logging

Health Checks The /health endpoint provides status information:

curl https://example-app.klutch.sh/health

Monitor for:

Database connectivity
File system access
Indexing queue status
Memory usage

Application Logs Configure logging levels:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Damselfly": "Debug",
      "Microsoft": "Warning"
    }
  }
}

Performance Metrics Track key metrics:

Indexing throughput (images per hour)
Thumbnail generation time
Database query performance
Memory consumption
Storage utilization

Backup Strategy

Three-Tier Backup Approach

Pictures Volume:
- Daily incremental backups
- Weekly full backups
- Store offsite or in cloud storage
Thumbnails Volume:
- Can be regenerated if lost
- Optional backups (saves time on restoration)
Config Volume:
- Daily database backups
- Version control for settings
- Critical for preserving tags and metadata

Automated Backup Script Create a backup routine:

#!/bin/bash
DATE=$(date +%Y%m%d)
BACKUP_DIR="/backups"

# Backup database
cp /config/damselfly.db "$BACKUP_DIR/damselfly-$DATE.db"

# Backup configuration
cp /config/appsettings.json "$BACKUP_DIR/appsettings-$DATE.json"

# Compress and upload (example: to S3)
tar -czf "$BACKUP_DIR/damselfly-backup-$DATE.tar.gz" \
  "$BACKUP_DIR/damselfly-$DATE.db" \
  "$BACKUP_DIR/appsettings-$DATE.json"

# Cleanup old backups (keep 30 days)
find "$BACKUP_DIR" -name "damselfly-*.tar.gz" -mtime +30 -delete

Resource Optimization

Container Resource Limits Monitor and adjust resource allocation:

Memory: 2GB minimum, 4GB recommended for large collections
CPU: 2 cores minimum, 4 cores for faster indexing
Storage I/O: SSD-backed volumes recommended for thumbnails

Caching Strategy Optimize caching for better performance:

{
  "Damselfly": {
    "ThumbnailCacheSize": 5000,
    "MetadataCacheSize": 10000,
    "EnableCaching": true
  }
}

Troubleshooting

Here are solutions to common issues you might encounter with Damselfly:

Indexing Problems

Problem: Images not appearing in the library

Solutions:

Check that photos are in the /pictures directory
Verify file permissions (container must have read access)
Check supported formats in configuration
Review indexing logs for errors
Restart the indexing process from Settings

Problem: Indexing is extremely slow

Solutions:

Increase MaxConcurrentJobs in configuration
Set CpuLevel to “High” for faster processing
Check container resource allocation
Reduce thumbnail sizes to speed generation
Disable face detection temporarily during initial indexing

Problem: Some RAW formats not recognized

Solutions:

Ensure RAW format is in SupportedFormats list
Update to latest Damselfly version
Check that LibRaw libraries are present
Try converting problematic files to DNG
Verify file extensions are lowercase

Thumbnail Generation Issues

Problem: Thumbnails not generating

Solutions:

Check /thumbs volume has sufficient space
Verify write permissions on thumbnails directory
Review logs for thumbnail generation errors
Clear thumbnail cache and regenerate
Increase memory allocation for container

Problem: Thumbnail quality is poor

Solutions:

Increase thumbnail resolution in settings
Adjust JPEG quality settings
Enable high-quality mode for RAW thumbnails
Check source image quality
Regenerate thumbnails after adjusting settings

Database Issues

Problem: Database locked or corrupted

Solutions:

Stop the container
Backup current database file
Run SQLite integrity check: sqlite3 damselfly.db "PRAGMA integrity_check;"
If corrupted, restore from backup
Rebuild index if necessary

Problem: Search not returning expected results

Solutions:

Rebuild search index from Settings
Check that metadata extraction completed
Verify keywords are properly saved
Clear search cache
Check for special characters in search query

Performance Problems

Problem: Web interface is slow

Solutions:

Check container resource usage
Reduce concurrent indexing jobs
Clear browser cache
Optimize database with VACUUM
Increase thumbnail cache size
Check network latency

Problem: High memory usage

Solutions:

Reduce MaxConcurrentJobs
Lower ThumbnailCacheSize and MetadataCacheSize
Disable face detection if not needed
Restart container to clear memory
Check for memory leaks in logs

File System Issues

Problem: Cannot write to volumes

Solutions:

Verify volume mount paths match configuration
Check container user permissions
Ensure volumes have sufficient space
Review Klutch.sh volume configuration
Test write access with simple file creation

Problem: Disk space exhausted

Solutions:

Increase volume size in Klutch.sh dashboard
Clear old thumbnail cache
Remove duplicate images
Archive old photos to separate storage
Implement automatic cleanup policies

Face Detection Problems

Problem: Faces not being detected

Solutions:

Ensure ENABLE_FACE_DETECTION is true
Verify AI models are downloaded
Check that images have sufficient resolution
Increase face detection sensitivity
Review logs for ML model errors

Problem: Incorrect face matches

Solutions:

Retrain specific face tags
Increase face recognition threshold
Manually correct misidentified faces
Rebuild face detection index
Update to latest AI models

Authentication Issues

Problem: Cannot log in

Solutions:

Verify authentication is enabled in settings
Check credentials are correct
Clear browser cookies and cache
Review authentication logs
Reset user password through admin interface

Problem: Session expires too quickly

Solutions:

Increase session timeout in configuration
Check for clock synchronization issues
Verify cookie settings
Use “Remember Me” option if available

Advanced Configuration

Take your Damselfly deployment further with these advanced customization options:

Custom Image Processing Pipelines

Configure advanced image processing workflows:

{
  "Damselfly": {
    "ImageProcessing": {
      "EnableColorAnalysis": true,
      "EnableObjectDetection": true,
      "AutoRotateByExif": true,
      "PreserveExifData": true,
      "ThumbnailFormat": "JPEG",
      "ThumbnailQuality": 85,
      "ColorSpace": "sRGB"
    }
  }
}

Machine Learning Integration

Enhance AI capabilities:

{
  "MachineLearning": {
    "FaceDetection": {
      "Enabled": true,
      "MinFaceSize": 50,
      "ConfidenceThreshold": 0.8,
      "Model": "MTCNN"
    },
    "ObjectDetection": {
      "Enabled": true,
      "Model": "YOLO",
      "Classes": ["person", "car", "animal", "building"]
    },
    "SceneClassification": {
      "Enabled": true,
      "Model": "ResNet50",
      "MinConfidence": 0.7
    }
  }
}

Automated Tagging Rules

Create rules for automatic keyword assignment:

{
  "AutoTagging": {
    "Rules": [
      {
        "Name": "Sunset Detection",
        "Condition": "time >= 18:00 AND time <= 20:00",
        "Tags": ["sunset", "golden hour"]
      },
      {
        "Name": "Portrait Detection",
        "Condition": "orientation = portrait AND faces > 0",
        "Tags": ["portrait", "people"]
      },
      {
        "Name": "High ISO",
        "Condition": "iso >= 3200",
        "Tags": ["low light", "high iso"]
      }
    ]
  }
}

External Storage Integration

Connect to cloud storage providers:

{
  "ExternalStorage": {
    "Providers": [
      {
        "Type": "S3",
        "Bucket": "my-photo-archive",
        "AccessKey": "${S3_ACCESS_KEY}",
        "SecretKey": "${S3_SECRET_KEY}",
        "Region": "us-east-1",
        "AutoSync": true
      },
      {
        "Type": "GoogleDrive",
        "FolderId": "your-folder-id",
        "AutoSync": false
      }
    ]
  }
}

Custom Metadata Schemas

Define custom metadata fields:

{
  "MetadataSchema": {
    "CustomFields": [
      {
        "Name": "Project",
        "Type": "String",
        "Required": false,
        "DefaultValue": "General"
      },
      {
        "Name": "Client",
        "Type": "String",
        "Required": false
      },
      {
        "Name": "Usage Rights",
        "Type": "Enum",
        "Values": ["Personal", "Commercial", "Editorial"],
        "DefaultValue": "Personal"
      },
      {
        "Name": "Print Ready",
        "Type": "Boolean",
        "DefaultValue": false
      }
    ]
  }
}

Webhook Integration

Set up webhooks for external integrations:

{
  "Webhooks": {
    "Enabled": true,
    "Events": [
      {
        "Event": "image.indexed",
        "Url": "https://your-service.com/webhook/indexed",
        "Method": "POST",
        "Headers": {
          "Authorization": "Bearer ${WEBHOOK_TOKEN}"
        }
      },
      {
        "Event": "face.detected",
        "Url": "https://your-service.com/webhook/faces",
        "Method": "POST"
      }
    ]
  }
}

API Rate Limiting

Protect your instance from API abuse:

{
  "RateLimiting": {
    "Enabled": true,
    "Rules": [
      {
        "Endpoint": "/api/*",
        "Limit": 100,
        "Period": "1m"
      },
      {
        "Endpoint": "/api/search",
        "Limit": 20,
        "Period": "1m"
      },
      {
        "Endpoint": "/api/export",
        "Limit": 5,
        "Period": "1h"
      }
    ]
  }
}

Batch Processing Scripts

Create automated workflows:

#!/bin/bash
# Automated photo processing script

# Import new photos from staging
rsync -av /staging/photos/ /pictures/incoming/

# Trigger re-index
curl -X POST https://example-app.klutch.sh/api/index/scan

# Apply auto-tagging
curl -X POST https://example-app.klutch.sh/api/tags/auto

# Generate thumbnails for new images
curl -X POST https://example-app.klutch.sh/api/thumbnails/generate

# Run face detection
curl -X POST https://example-app.klutch.sh/api/faces/detect

# Backup database
sqlite3 /config/damselfly.db ".backup /backups/damselfly-$(date +%Y%m%d).db"

echo "Batch processing complete"

Performance Tuning

Advanced performance configuration:

{
  "Performance": {
    "ThreadPoolSize": 16,
    "MaxImageCacheSize": "2GB",
    "EnableParallelProcessing": true,
    "DatabaseOptimization": {
      "CacheSize": "100MB",
      "PageSize": 4096,
      "JournalMode": "WAL",
      "Synchronous": "NORMAL"
    },
    "ImageDecoding": {
      "UseHardwareAcceleration": true,
      "MaxDecoderThreads": 4,
      "PreloadBuffer": "500MB"
    }
  }
}

Additional Resources

Enhance your Damselfly knowledge with these helpful resources:

Damselfly Official Website - Project homepage and documentation
Damselfly GitHub Repository - Source code and issue tracking
Damselfly Docker Hub - Official container images
ASP.NET Core Documentation - Framework documentation
Blazor Documentation - Frontend framework guide
ExifTool - Metadata manipulation tool
SQLite Documentation - Database documentation
Klutch.sh Documentation - Platform-specific deployment guides

Conclusion

Damselfly provides a powerful, self-hosted solution for managing digital photo collections with advanced features like RAW format support, AI-powered face detection, and comprehensive metadata management. By deploying on Klutch.sh, you gain the benefits of containerized hosting with automatic HTTPS, persistent storage, and straightforward deployment workflows.

The combination of Blazor’s responsive interface and ASP.NET Core’s robust backend creates a professional-grade digital asset management system that can handle collections ranging from thousands to hundreds of thousands of images. With proper storage configuration and performance tuning, Damselfly on Klutch.sh offers a scalable, maintainable platform for organizing and accessing your photo library from anywhere.

Whether you’re a professional photographer managing client work, a photo enthusiast organizing personal collections, or a creative team collaborating on visual projects, Damselfly provides the tools needed for efficient photo management. Start building your digital asset management system today and take control of your photo library with the power of modern web technologies.

Deploying Damselfly

Why Deploy Damselfly on Klutch.sh?

Prerequisites

Understanding Damselfly Architecture

Core Components

Data Flow

Storage Requirements

Installation and Setup

Step 1: Create the Project Structure

Step 2: Create the Dockerfile

Step 3: Create Configuration Files

Step 4: Create Environment Configuration

Step 5: Create Docker Compose for Local Development

Step 6: Create .dockerignore

Step 7: Create a README

Step 8: Initialize Git Repository

Deploying to Klutch.sh

Getting Started with Damselfly

Initial Setup

Browsing Your Photo Library

Searching and Filtering

Organizing with Tags and Keywords

Face Detection and Recognition

Exporting and Sharing

Metadata Editing

Production Best Practices

Storage Planning

Performance Optimization

Database Maintenance

Security Configuration

Monitoring and Logging

Backup Strategy

Resource Optimization

Troubleshooting

Indexing Problems

Thumbnail Generation Issues

Database Issues

Performance Problems

File System Issues

Face Detection Problems

Authentication Issues

Advanced Configuration

Custom Image Processing Pipelines

Machine Learning Integration

Automated Tagging Rules

External Storage Integration

Custom Metadata Schemas

Webhook Integration

API Rate Limiting

Batch Processing Scripts

Performance Tuning

Additional Resources

Conclusion