Deploying Photofield

Introduction

Photofield is a high-performance photo gallery viewer designed for handling massive photo collections with ease. Unlike traditional gallery applications that struggle with large libraries, Photofield uses GPU-accelerated rendering to display millions of photos smoothly, loading images instantly as you scroll through your collection.

Built with Go for the backend and leveraging WebGL for the frontend, Photofield prioritizes speed and performance above all else. The application creates an index of your photos and generates optimized thumbnails for fast browsing, while the GPU-accelerated viewer handles smooth scrolling and zooming regardless of collection size.

Key highlights of Photofield:

• GPU-Accelerated Rendering: Smooth browsing of massive photo collections using WebGL
• Instant Loading: Progressive image loading for immediate visual feedback
• Timeline View: Browse photos chronologically with a visual timeline
• Geographic Mapping: View photos on a map based on GPS metadata
• Collection Scaling: Handle millions of photos without performance degradation
• Thumbnail Generation: Automatic creation of optimized thumbnails
• EXIF Metadata: Extract and display photo metadata
• Folder Browsing: Navigate photos by directory structure
• Full-Screen Viewer: Immersive photo viewing experience
• Keyboard Navigation: Quick navigation with keyboard shortcuts
• 100% Open Source: MIT licensed with active development

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

Why Deploy Photofield on Klutch.sh

Deploying Photofield on Klutch.sh provides several advantages for viewing your photo collection:

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds Photofield 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 indexing. Scale based on collection size.

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

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

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

Prerequisites

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

• A Klutch.sh account
• A GitHub account with a repository for your Photofield configuration
• Basic familiarity with Docker and containerization concepts
• A photo collection ready to browse
• (Optional) A custom domain for your Photofield instance

Understanding Photofield Architecture

Photofield is built for performance:

Go Backend: The server is written in Go, providing excellent performance for file handling and API requests.

WebGL Frontend: The browser-based viewer uses WebGL for GPU-accelerated rendering, enabling smooth scrolling through massive collections.

SQLite Database: Lightweight database storage for photo metadata and index information.

Thumbnail Cache: Pre-generated thumbnails at multiple sizes for instant loading.

Progressive Loading: Images load progressively from low resolution to full quality.

Preparing Your Repository

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

Repository Structure

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

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM golang:1.21-alpine AS builder

RUN apk add --no-cache git build-base

WORKDIR /app

RUN git clone https://github.com/SmilyOrg/photofield.git .

RUN go build -o photofield ./cmd/photofield

FROM alpine:latest

RUN apk add --no-cache \
    ca-certificates \
    ffmpeg \
    libraw \
    imagemagick

WORKDIR /app

COPY --from=builder /app/photofield .
COPY --from=builder /app/ui ./ui

# Create directories
RUN mkdir -p /data /photos /cache

# Environment variables
ENV PHOTOFIELD_DATA_DIR=/data
ENV PHOTOFIELD_CACHE_DIR=/cache

EXPOSE 8080

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

CMD ["./photofield", "serve"]

Creating the .dockerignore File

Create a .dockerignore file:

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

Environment Variables Reference

Variable	Required	Default	Description
PHOTOFIELD_DATA_DIR	No	/data	Database and configuration directory
PHOTOFIELD_CACHE_DIR	No	/cache	Thumbnail cache directory
PHOTOFIELD_PHOTOS_DIR	No	/photos	Photos source directory
PHOTOFIELD_PORT	No	8080	Server port

Deploying Photofield on Klutch.sh

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

Push Your Repository to GitHub

Initialize and push your repository:

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

Configure HTTP Traffic

In the deployment settings:

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

Set Environment Variables

Add the following environment variables:

Variable	Value
PHOTOFIELD_DATA_DIR	/data
PHOTOFIELD_CACHE_DIR	/cache
PHOTOFIELD_PHOTOS_DIR	/photos

Attach Persistent Volumes

Add the following volumes for data persistence:

Mount Path	Recommended Size	Purpose
/photos	100+ GB	Your photo collection
/data	5 GB	Database and configuration
/cache	20 GB	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 Photofield container
• Provision an HTTPS certificate

Access Photofield

Once deployment completes, access your Photofield instance at https://your-app-name.klutch.sh. The interface will begin indexing your photos.

Initial Setup and Configuration

Indexing Photos

After deployment, Photofield will scan and index your photo collection:

1. Navigate to your Photofield URL
2. The application will automatically detect photos in the configured directory
3. Indexing progress is shown in the interface
4. Thumbnail generation begins automatically

Browsing Your Collection

Photofield offers multiple viewing modes:

• Timeline View: Chronological photo browsing
• Folder View: Navigate by directory structure
• Map View: Geographic visualization with GPS data
• Grid View: Traditional gallery grid layout

Keyboard Navigation

Use keyboard shortcuts for efficient browsing:

• Arrow keys: Navigate between photos
• Space: Toggle full-screen viewer
• Escape: Exit current view
• +/-: Zoom in/out

Production Best Practices

Performance Optimization

• Thumbnail Pre-generation: Allow initial indexing to complete fully
• Cache Sizing: Allocate sufficient cache space for your collection
• Memory Allocation: Increase memory for larger collections

Storage Management

• Photo Organization: Maintain consistent folder structure
• Backup Strategy: Back up photos from source storage
• Cache Cleanup: Periodically clear unused thumbnails

Troubleshooting Common Issues

Slow Initial Loading

Symptoms: First load takes very long.

Solutions:

• Wait for initial indexing to complete
• Increase memory allocation
• Check disk I/O performance

Photos Not Appearing

Symptoms: Photos not showing in the interface.

Solutions:

• Verify photo directory mount
• Check file permissions
• Ensure supported image formats
• Trigger manual re-index

Thumbnail Generation Errors

Symptoms: Thumbnails not generating.

Solutions:

• Check cache directory permissions
• Verify sufficient disk space
• Review error logs

Additional Resources

• Photofield GitHub Repository
• Photofield Wiki
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying Photofield on Klutch.sh gives you a high-performance photo gallery with automatic builds, persistent storage, and secure HTTPS access. The GPU-accelerated rendering ensures smooth browsing even with massive photo collections.

With its focus on speed and performance, Photofield is ideal for photographers and enthusiasts with large libraries who want instant access to their entire collection. Photofield on Klutch.sh provides the infrastructure for a responsive, always-available photo browsing experience.