Deploying Photoview

Introduction

Photoview is a simple, user-friendly photo gallery application designed for self-hosting. It provides a clean, modern interface for browsing and sharing your photo and video library while supporting advanced features like facial recognition, GPS mapping, and multi-user access control.

Built with Go for the backend and React for the frontend, Photoview strikes a balance between simplicity and functionality. The application scans your existing photo directories, generates optimized thumbnails, and presents your media through a beautiful web interface without requiring you to import or reorganize your files.

Key highlights of Photoview:

• Simple Setup: Point to existing photo directories without reorganization
• Facial Recognition: Automatic face detection and grouping
• Video Support: Browse and stream video files alongside photos
• GPS Mapping: View photos on an interactive map
• Multi-User Support: Create accounts with individual album access
• RAW File Support: Process RAW files from professional cameras
• EXIF Display: View detailed photo metadata
• Sharing: Create share links for albums
• Favorites: Mark and organize favorite photos
• Timeline View: Browse chronologically with an intuitive timeline
• Mobile Friendly: Responsive design for all devices
• 100% Open Source: AGPL-3.0 licensed with active development

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

Why Deploy Photoview on Klutch.sh

Deploying Photoview on Klutch.sh provides several advantages for sharing your photo library:

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

Persistent Storage: Attach persistent volumes for your photos, database, and thumbnails. 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 facial recognition. Scale based on library size.

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

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

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

Prerequisites

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

• A Klutch.sh account
• A GitHub account with a repository for your Photoview configuration
• A MySQL, MariaDB, or PostgreSQL database
• Basic familiarity with Docker and containerization concepts
• Photos ready to share
• (Optional) A custom domain for your Photoview instance

Understanding Photoview Architecture

Photoview is built on a clean, efficient architecture:

Go Backend: The API server handles authentication, media scanning, and database operations.

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

Database Layer: Supports MySQL, MariaDB, PostgreSQL, and SQLite for metadata storage.

Thumbnail Generation: Automatic creation of optimized thumbnails at multiple resolutions.

Face Detection: Machine learning-based facial recognition using local processing.

Video Transcoding: Automatic video transcoding for web-compatible playback.

Preparing Your Repository

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

Repository Structure

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

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM viktorstrate/photoview:latest

# Environment variables
ENV PHOTOVIEW_DATABASE_DRIVER=${PHOTOVIEW_DATABASE_DRIVER:-mysql}
ENV PHOTOVIEW_MYSQL_URL=${PHOTOVIEW_MYSQL_URL}
ENV PHOTOVIEW_LISTEN_IP=0.0.0.0
ENV PHOTOVIEW_LISTEN_PORT=80
ENV PHOTOVIEW_MEDIA_CACHE=/cache

# Create directories
RUN mkdir -p /photos /cache

EXPOSE 80

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --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
PHOTOVIEW_DATABASE_DRIVER	Yes	mysql	Database driver (mysql/postgres/sqlite)
PHOTOVIEW_MYSQL_URL	Conditional	-	MySQL connection string
PHOTOVIEW_POSTGRES_URL	Conditional	-	PostgreSQL connection string
PHOTOVIEW_SQLITE_PATH	Conditional	-	SQLite database file path
PHOTOVIEW_LISTEN_PORT	No	80	Server port
PHOTOVIEW_MEDIA_CACHE	No	/cache	Thumbnail cache directory
PHOTOVIEW_FACE_RECOGNITION_ENABLED	No	true	Enable facial recognition

Deploying Photoview on Klutch.sh

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

Provision a Database

Set up a MySQL, MariaDB, or PostgreSQL database. Create a database and user for Photoview with full access permissions.

Push Your Repository to GitHub

Initialize and push your repository:

git init
git add Dockerfile .dockerignore
git commit -m "Initial Photoview deployment configuration"
git remote add origin https://github.com/yourusername/photoview-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 “photoview” or “family-photos”.

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 Photoview Dockerfile.

Configure HTTP Traffic

In the deployment settings:

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

Set Environment Variables

Add the following environment variables:

Variable	Value
PHOTOVIEW_DATABASE_DRIVER	mysql (or postgres)
PHOTOVIEW_MYSQL_URL	user:password@tcp(host:3306)/photoview

For PostgreSQL:

Variable	Value
PHOTOVIEW_POSTGRES_URL	postgres://user:password@host:5432/photoview

Attach Persistent Volumes

Add the following volumes for data persistence:

Mount Path	Recommended Size	Purpose
/photos	100+ GB	Your photo and video collection
/cache	30 GB	Thumbnail and transcoded video 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 Photoview container
• Provision an HTTPS certificate

Complete Initial Setup

Access your Photoview instance and complete the setup wizard to create your admin account.

Access Photoview

Once setup completes, access your Photoview instance at https://your-app-name.klutch.sh.

Initial Setup and Configuration

Creating Admin Account

On first access, create your administrator account:

1. Navigate to your Photoview URL
2. Enter username and password for the admin account
3. Configure initial settings
4. Complete the setup wizard

Adding Photo Sources

Configure photo directories for users:

1. Go to Settings > Users
2. Select or create a user
3. Add photo source paths (e.g., /photos/family)
4. Trigger initial scan

Scanning Photos

After adding sources, scan your library:

1. Navigate to Settings
2. Click “Scan All” or scan individual paths
3. Monitor progress in the interface
4. Thumbnails and faces are processed automatically

Configuring Users

Create accounts for family members or friends:

1. Go to Settings > Users
2. Click “Add User”
3. Set username and password
4. Assign photo source paths
5. Configure permissions

Features Deep Dive

Facial Recognition

Photoview automatically detects and groups faces:

1. Navigate to People section
2. Review detected face groups
3. Name recognized individuals
4. Merge duplicate groups
5. Browse photos by person

Geographic Mapping

View photos on an interactive map:

1. Navigate to Places
2. Browse photos by location
3. Explore clusters on the map
4. Filter by specific regions

Timeline View

Browse chronologically:

• Scroll through timeline for visual navigation
• Jump to specific dates
• View photos grouped by time periods

Sharing Albums

Share albums with external users:

1. Navigate to an album
2. Click share button
3. Generate a share link
4. Optionally set password protection
5. Share the link with recipients

Production Best Practices

Security Recommendations

• Strong Passwords: Use complex passwords for all accounts
• Share Links: Use passwords on shared albums
• Regular Updates: Keep Photoview updated for security patches
• Database Security: Secure database connections

Performance Optimization

• Initial Scan: Allow complete scanning before heavy use
• Thumbnail Quality: Balance quality vs. storage
• Face Recognition: Disable if not needed for performance
• Resource Allocation: Scale resources for larger libraries

Backup Strategy

Protect your photo library:

1. Database Backups: Regular database exports
2. Photo Backups: Maintain copies of original files
3. Cache Regeneration: Cache can be regenerated if lost
4. Configuration: Save user and settings configurations

Troubleshooting Common Issues

Database Connection Errors

Symptoms: Application fails to start.

Solutions:

• Verify database connection string format
• Check database server accessibility
• Confirm user permissions
• Review firewall rules

Scanning Not Finding Photos

Symptoms: Photos not appearing after scan.

Solutions:

• Verify mount path matches configuration
• Check file permissions
• Ensure supported file formats
• Review scan logs for errors

Thumbnails Not Generating

Symptoms: Photos show placeholder images.

Solutions:

• Check cache directory permissions
• Verify sufficient disk space
• Review processing logs
• Trigger manual rescan

Additional Resources

• Photoview Official Website
• Photoview Documentation
• Photoview GitHub Repository
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying Photoview on Klutch.sh gives you a simple yet powerful photo gallery with automatic builds, persistent storage, and secure HTTPS access. The combination of user-friendly interface and advanced features like facial recognition makes Photoview an excellent choice for sharing photos with family and friends.

With multi-user support and flexible access control, Photoview adapts to various sharing scenarios while keeping your original files untouched. Whether you’re organizing family memories or managing a photography portfolio, Photoview on Klutch.sh provides the foundation for a private, self-hosted photo sharing experience.