Deploying PiGallery 2

Introduction

PiGallery 2 is a fast, self-hosted directory-first photo gallery designed for browsing large photo collections. Unlike traditional gallery applications that require importing or organizing photos, PiGallery 2 reads directly from your existing folder structure, making it ideal for photographers and anyone with an established file organization system.

Built with TypeScript and Angular for performance, PiGallery 2 emphasizes speed and efficiency. The application generates thumbnails on-the-fly, supports full-text search with face detection, and provides a responsive interface that works seamlessly on both desktop and mobile devices.

Key highlights of PiGallery 2:

• Directory-First: Browse photos using your existing folder structure
• Fast Performance: Optimized for large collections with caching
• Face Detection: Automatic face detection and grouping
• Full-Text Search: Search by metadata, faces, and folder names
• GPS Mapping: View photos on an interactive map
• Video Support: Browse and stream video files
• On-the-Fly Thumbnails: Generate thumbnails without pre-processing
• Responsive Design: Works on desktop and mobile devices
• Sharing: Password-protected sharing of folders
• EXIF Metadata: Display detailed photo information
• Slideshow: Automatic photo slideshow viewing
• 100% Open Source: MIT licensed with active development

This guide walks through deploying PiGallery 2 on Klutch.sh using Docker, configuring storage, and setting up the application for production use.

Why Deploy PiGallery 2 on Klutch.sh

Deploying PiGallery 2 on Klutch.sh provides several advantages for browsing your photo collection:

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds PiGallery 2 without complex orchestration. Push to GitHub and your gallery deploys automatically.

Persistent Storage: Attach persistent volumes for your photos, thumbnails, and database. Your library survives container restarts and redeployments.

HTTPS by Default: Klutch.sh provides automatic SSL certificates, ensuring secure access to your photos from anywhere.

GitHub Integration: Connect your configuration repository directly from GitHub. Updates trigger automatic redeployments.

Scalable Resources: Allocate CPU and memory for thumbnail generation and search indexing. Scale based on library size.

Environment Variable Management: Securely store configuration through Klutch.sh’s environment variable system.

Custom Domains: Assign a custom domain to your PiGallery 2 instance for personalized access.

Always-On Availability: Your photo gallery remains accessible 24/7 without managing infrastructure.

Prerequisites

Before deploying PiGallery 2 on Klutch.sh, ensure you have:

• A Klutch.sh account
• A GitHub account with a repository for your PiGallery 2 configuration
• Basic familiarity with Docker and containerization concepts
• A photo collection with an organized folder structure
• (Optional) A custom domain for your PiGallery 2 instance

Understanding PiGallery 2 Architecture

PiGallery 2 is built on a modern, efficient architecture:

TypeScript Backend: The server handles file browsing, search indexing, and thumbnail generation.

Angular Frontend: The web interface provides a responsive single-page application experience.

SQLite Database: Lightweight database for metadata caching and search indexing.

Thumbnail Cache: Generated thumbnails are cached for fast subsequent access.

Face Detection: Optional face detection using machine learning models.

Preparing Your Repository

To deploy PiGallery 2 on Klutch.sh, create a GitHub repository containing your Dockerfile.

Repository Structure

pigallery2-deploy/
├── Dockerfile
├── .dockerignore
└── README.md

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM bpatrik/pigallery2:latest

# Environment variables
ENV NODE_ENV=production
ENV PORT=80

# Create directories
RUN mkdir -p /app/data/images /app/data/db /app/data/tmp

EXPOSE 80

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

Creating the .dockerignore File

Create a .dockerignore file:

.git
.github
*.md
LICENSE
.gitignore
*.log
.DS_Store

Environment Variables Reference

Variable	Required	Default	Description
PORT	No	80	Server port
NODE_ENV	No	production	Node environment

Configuration is primarily done through the web interface after deployment.

Deploying PiGallery 2 on Klutch.sh

Once your repository is prepared, follow these steps to deploy PiGallery 2:

Push Your Repository to GitHub

Initialize and push your repository:

git init
git add Dockerfile .dockerignore
git commit -m "Initial PiGallery 2 deployment configuration"
git remote add origin https://github.com/yourusername/pigallery2-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. Give it a descriptive name like “pigallery2” or “photo-gallery”.

Create a New App

Within your project, create a new app. Connect your GitHub account if you haven’t already, then select the repository containing your PiGallery 2 Dockerfile.

Configure HTTP Traffic

In the deployment settings:

• Select HTTP as the traffic type
• Set the internal port to 80 (PiGallery 2’s default port)

Set Environment Variables

Add the following environment variables:

Variable	Value
NODE_ENV	production
PORT	80

Attach Persistent Volumes

Add the following volumes for data persistence:

Mount Path	Recommended Size	Purpose
/app/data/images	100+ GB	Your photo collection
/app/data/db	5 GB	Database and configuration
/app/data/tmp	10 GB	Temporary files and thumbnail cache

Deploy Your Application

Click Deploy to start the build process. Klutch.sh will:

• Detect your Dockerfile automatically
• Build the container image
• Attach the persistent volumes
• Start the PiGallery 2 container
• Provision an HTTPS certificate

Access PiGallery 2

Once deployment completes, access your PiGallery 2 instance at https://your-app-name.klutch.sh. Complete the initial setup.

Initial Setup and Configuration

First-Time Setup

On first access, configure the application:

1. Navigate to your PiGallery 2 URL
2. Access the admin interface
3. Set the images folder path to /app/data/images
4. Configure authentication settings
5. Save the configuration

Uploading Photos

Upload photos to the images directory:

1. Use the mounted volume path
2. Maintain your folder structure
3. Photos will be automatically discovered
4. Indexing begins on access

Configuring Users

Set up access control:

1. Navigate to Settings > Users
2. Create admin account with password
3. Optionally enable guest access
4. Configure sharing permissions

Enabling Face Detection

Enable face detection for people searching:

1. Go to Settings > Face Detection
2. Enable the feature
3. Allow initial processing time
4. Review and name detected faces

Features Deep Dive

Directory Navigation

Browse photos using folder structure:

• Navigate through directories
• View photo counts per folder
• Quick navigation breadcrumbs
• Folder thumbnails

Search Functionality

Find photos quickly:

• Search by filename
• Search by folder name
• Search by date
• Search by face (if enabled)
• Full-text metadata search

Map View

View photos geographically:

1. Navigate to Map view
2. Browse clusters on the map
3. Click to view photos from location
4. Explore by geographic area

Sharing

Share folders with others:

1. Navigate to a folder
2. Enable sharing
3. Set optional password
4. Copy share link
5. Recipients can view without login

Slideshow

View photos automatically:

1. Enter a folder
2. Start slideshow
3. Configure timing
4. Enjoy automatic navigation

Production Best Practices

Performance Optimization

• Thumbnail Caching: Allow cache to build up over time
• Indexing: Complete initial indexing during low-traffic
• Memory: Allocate sufficient memory for large collections
• Storage: Use fast storage for thumbnails

Security Recommendations

• Authentication: Enable user authentication
• HTTPS: Always use HTTPS (provided by Klutch.sh)
• Sharing: Use passwords on shared folders
• Updates: Keep PiGallery 2 updated

Backup Strategy

Protect your configuration:

1. Database Backup: Back up SQLite database
2. Photo Backup: Maintain original photo backups
3. Configuration: Export settings
4. Thumbnail Regeneration: Can be regenerated if lost

Troubleshooting Common Issues

Photos Not Appearing

Symptoms: Folders empty or photos missing.

Solutions:

• Verify volume mount paths
• Check file permissions
• Confirm supported formats
• Trigger re-index from settings

Slow Loading

Symptoms: Gallery loads slowly.

Solutions:

• Wait for initial indexing
• Check thumbnail cache
• Increase memory allocation
• Optimize image paths

Face Detection Not Working

Symptoms: No faces detected.

Solutions:

• Verify feature is enabled
• Check sufficient memory
• Allow processing time
• Review configuration

Additional Resources

• PiGallery 2 GitHub Repository
• PiGallery 2 Wiki
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying PiGallery 2 on Klutch.sh gives you a fast, directory-first photo gallery with automatic builds, persistent storage, and secure HTTPS access. The focus on browsing existing folder structures makes PiGallery 2 ideal for anyone who already has an organized photo collection.

With features like face detection, geographic mapping, and full-text search, PiGallery 2 provides powerful discovery tools while respecting your existing organization. Whether you’re a photographer with a carefully curated archive or a family with years of memories, PiGallery 2 on Klutch.sh provides the foundation for a fast, private photo browsing experience.