Deploying HomeGallery

Introduction

HomeGallery is a self-hosted, open-source web gallery designed to view your photos and videos with features like tagging, face detection, and AI-powered image discovery. Built for performance and privacy, HomeGallery runs entirely on your own infrastructure while providing a modern, mobile-friendly interface.

The gallery processes your media files to extract metadata, generate previews, and optionally analyze content using AI models for object detection and similarity search. Once indexed, you can browse thousands of photos quickly, search by content or tags, and share albums without relying on cloud services.

Key highlights of HomeGallery:

AI-Powered Discovery: Find similar images and search by content
Face Detection: Group photos by people
Mobile Friendly: Responsive design works on all devices
Fast Browsing: Optimized for large collections
Privacy First: All processing happens locally
Multiple Sources: Index photos from different directories
Tagging System: Organize with custom tags
Video Support: Browse and preview video files

This guide walks through deploying HomeGallery on Klutch.sh using Docker, indexing your photo library, and configuring AI features.

Prerequisites

Before deploying HomeGallery on Klutch.sh, ensure you have:

A Klutch.sh account
A GitHub account with a repository for your HomeGallery configuration
Photos and videos to index
Basic familiarity with Docker and containerization concepts

Preparing Your Repository

Create a GitHub repository with the following structure:

homegallery-deploy/
├── Dockerfile
├── gallery.config.yml
├── .dockerignore
└── README.md

Creating the Dockerfile

Create a Dockerfile using the official HomeGallery image:

FROM xemle/home-gallery:latest

# Environment variables
ENV GALLERY_OPEN_BROWSER=false
ENV GALLERY_API_SERVER_CONCURRENT=5
ENV GALLERY_API_SERVER_TIMEOUT=60

# Expose the application port
EXPOSE 3000

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost:3000/ || exit 1

Configuration with API Server

For AI features, configure the extractor API:

FROM xemle/home-gallery:latest

# Gallery configuration
ENV GALLERY_OPEN_BROWSER=false
ENV GALLERY_API_SERVER=${GALLERY_API_SERVER}
ENV GALLERY_API_SERVER_CONCURRENT=${GALLERY_API_SERVER_CONCURRENT:-1}
ENV GALLERY_API_SERVER_TIMEOUT=${GALLERY_API_SERVER_TIMEOUT:-60}

# Watch folder configuration
ENV GALLERY_WATCH_POLL_INTERVAL=0

EXPOSE 3000

HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost:3000/ || exit 1

Gallery Configuration File

Create gallery.config.yml:

# HomeGallery Configuration

sources:
  - /data/photos
  - /data/videos

storage:
  dir: /data/storage

# Exclude patterns
excludePatterns:
  - '**/.git/**'
  - '**/node_modules/**'
  - '**/.thumbnails/**'
  - '**/Thumbs.db'

# API server for AI features (optional)
# extractor:
#   apiServer: http://api:3000

# Preview settings
preview:
  maxWidth: 1920
  maxHeight: 1920

Environment Variables Reference

Variable	Required	Default	Description
`GALLERY_OPEN_BROWSER`	No	true	Open browser on start
`GALLERY_API_SERVER`	No	-	URL of extractor API for AI features
`GALLERY_API_SERVER_CONCURRENT`	No	5	Concurrent API requests
`GALLERY_API_SERVER_TIMEOUT`	No	30	API timeout in seconds
`GALLERY_WATCH_POLL_INTERVAL`	No	0	Poll interval for file changes (0 disables)

Deploying HomeGallery on Klutch.sh

Push Your Repository to GitHub

git init
git add Dockerfile gallery.config.yml .dockerignore README.md
git commit -m "Initial HomeGallery deployment configuration"
git remote add origin https://github.com/yourusername/homegallery-deploy.git
git push -u origin main

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project named “homegallery” or “photos”.

Create a New App

Within your project, create a new app. Connect your GitHub account and select your HomeGallery repository.

Configure HTTP Traffic

Select HTTP as the traffic type
Set the internal port to 3000

Set Environment Variables

Configure the following environment variables:

Variable	Value
`GALLERY_OPEN_BROWSER`	`false`
`GALLERY_API_SERVER_CONCURRENT`	`3`
`GALLERY_API_SERVER_TIMEOUT`	`60`

Attach Persistent Volumes

Mount Path	Recommended Size	Purpose
`/data/photos`	100+ GB	Your photo library
`/data/videos`	100+ GB	Your video library
`/data/storage`	50 GB	Previews, thumbnails, and database
`/data/config`	1 GB	Configuration files

Deploy Your Application

Click Deploy to start the build process. Klutch.sh will build the container, attach volumes, and start HomeGallery with HTTPS enabled.

Access HomeGallery

Once deployment completes, access your gallery at https://your-app-name.klutch.sh.

Run Initial Index

On first access, HomeGallery will need to index your photos. This can take time depending on library size.

Using HomeGallery

Browsing Photos

Scroll through your entire library
Use timeline navigation on the right
Click any photo for full view
Swipe or use arrows to navigate

Search Features

Text Search:

Search by filename
Search by tags
Search by date

AI Search (with extractor):

Search by content (e.g., “beach”, “dog”)
Find similar images
Face grouping

Tagging Photos

Select one or more photos
Click the tag icon
Add or remove tags
Tags are saved in the database

Create a selection of photos
Generate shareable link
Links can be time-limited
No login required for viewers

Keyboard Shortcuts

Key	Action
`Left/Right`	Navigate photos
`Escape`	Close viewer
`F`	Toggle fullscreen
`I`	Show info panel
`Space`	Play/pause video

AI Features

Enabling AI Extractor

For object detection and similarity search, deploy the extractor API:

FROM xemle/home-gallery-api-server:latest

ENV BACKEND=cpu  # or wasm, node

EXPOSE 3000

Configure HomeGallery to use it:

extractor:
  apiServer: http://your-api-server:3000

Face Detection

Faces are automatically detected during indexing
Group photos by person
Browse by face clusters

Similar Image Search

Open any photo
Click “Find Similar”
AI finds visually similar images
Useful for finding duplicates or related shots

Performance Tips

Large Libraries

For collections over 10,000 items:

Increase API server timeout
Reduce concurrent requests on low-spec systems
Consider incremental indexing

SoC Devices

For Raspberry Pi or similar:

# In environment
GALLERY_API_SERVER_CONCURRENT: 1
GALLERY_API_SERVER_TIMEOUT: 120

Indexing Speed

Initial index is the slowest
Subsequent runs are incremental
AI extraction adds significant time

Troubleshooting

Photos Not Appearing

Check source paths in configuration
Verify volume mounts are correct
Run reindex if needed

Slow Performance

Ensure previews are generated
Check storage volume performance
Reduce concurrent operations

AI Features Not Working

Verify extractor API is running
Check API server URL configuration
Review API server logs

Additional Resources

Conclusion

Deploying HomeGallery on Klutch.sh creates a powerful, private photo and video gallery with modern features like AI discovery and face detection. The self-hosted approach ensures your memories stay under your control while providing a fast, mobile-friendly browsing experience. With persistent storage for your media and generated previews, HomeGallery on Klutch.sh offers a reliable, feature-rich alternative to cloud photo services.