Deploying Lychee

Introduction

Lychee is a beautiful, self-hosted photo management and sharing application. Built with Laravel and Vue.js, Lychee provides an elegant way to organize, manage, and share your photo collection with a stunning gallery interface that rivals commercial solutions.

Originally created as a simple photo management tool, Lychee has evolved into a full-featured platform with album organization, smart albums, user management, and extensive sharing options. Whether you want a private photo archive or a public portfolio site, Lychee delivers a polished experience.

Key highlights of Lychee:

• Beautiful Gallery: Stunning, responsive photo galleries with multiple view modes
• Album Organization: Create albums and nested sub-albums for logical organization
• Smart Albums: Automatic albums based on tags, dates, and other criteria
• Multi-User Support: Share your instance with family and friends with separate accounts
• Public/Private Sharing: Fine-grained control over photo and album visibility
• EXIF Data: Automatic extraction and display of photo metadata
• Map View: Visualize photos on a map based on GPS data
• Search: Full-text search across photos and albums
• Import Options: Upload via web, import from server, or sync with external sources
• RAW Support: Handle RAW photo formats with automatic JPEG generation
• Video Support: Manage videos alongside photos
• API Access: Full REST API for integration and automation
• Open Source: MIT licensed with active development

This guide walks through deploying Lychee on Klutch.sh using Docker, configuring your photo library, and setting up the application for daily use.

Why Deploy Lychee on Klutch.sh

Deploying Lychee on Klutch.sh provides several advantages:

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds Lychee without complex configuration.

Persistent Storage: Attach persistent volumes for your photos and database. Your entire library survives restarts.

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

GitHub Integration: Connect your configuration repository directly from GitHub for automated deployments.

Scalable Resources: Allocate CPU and memory based on library size and traffic.

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

Custom Domains: Assign a custom domain to your Lychee instance for a professional photo portfolio.

Always-On Availability: Your photo library remains accessible 24/7.

Prerequisites

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

• A Klutch.sh account
• A GitHub account with a repository for your Lychee configuration
• Basic familiarity with Docker and containerization concepts
• Photos ready to upload to your new library
• (Optional) A custom domain for your Lychee instance

Understanding Lychee Architecture

Lychee uses a modern web application architecture:

Laravel Backend: PHP-based backend handling authentication, photo processing, and API.

Vue.js Frontend: Responsive single-page application providing the gallery interface.

Database: MySQL, MariaDB, PostgreSQL, or SQLite for metadata storage.

File Storage: Photo files stored on the filesystem with generated thumbnails.

Queue System: Background processing for photo imports and thumbnail generation.

Preparing Your Repository

To deploy Lychee on Klutch.sh, create a GitHub repository containing your configuration.

Repository Structure

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

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM lycheeorg/lychee:latest

# Set environment variables
ENV PHP_TZ=UTC
ENV STARTUP_DELAY=0
ENV ADMIN_USER=admin
ENV ADMIN_PASSWORD=${ADMIN_PASSWORD}

# Create directories
RUN mkdir -p /uploads /sym /logs

# Set permissions
RUN chown -R www-data:www-data /uploads /sym /logs

# Expose web interface
EXPOSE 80

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

Creating the .dockerignore File

Create a .dockerignore file:

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

Environment Variables Reference

Variable	Required	Default	Description
DB_CONNECTION	Yes	-	Database type (mysql, pgsql, sqlite)
DB_HOST	Yes	-	Database host
DB_DATABASE	Yes	-	Database name
DB_USERNAME	Yes	-	Database username
DB_PASSWORD	Yes	-	Database password
APP_KEY	Yes	-	Laravel application key
APP_URL	Yes	-	Public URL of your Lychee instance
ADMIN_USER	No	-	Initial admin username
ADMIN_PASSWORD	No	-	Initial admin password

Deploying Lychee on Klutch.sh

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

Generate an Application Key

Generate a Laravel application key:

echo "base64:$(openssl rand -base64 32)"

Save this securely for environment variable configuration.

Push Your Repository to GitHub

Initialize your repository and push to GitHub:

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

Configure HTTP Traffic

In the deployment settings:

• Select HTTP as the traffic type
• Set the internal port to 80

Set Environment Variables

In the environment variables section, add:

Variable	Value
DB_CONNECTION	sqlite
APP_KEY	Your generated application key
APP_URL	https://example-app.klutch.sh
ADMIN_USER	admin
ADMIN_PASSWORD	Your secure admin password

Attach Persistent Volumes

Add the following volumes:

Mount Path	Recommended Size	Purpose
/uploads	100+ GB	Photo storage (adjust based on library size)
/sym	20 GB	Symbolic links and thumbnails
/var/www/html/database	1 GB	SQLite database (if using SQLite)

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 Lychee container
• Provision an HTTPS certificate

Access Lychee

Once deployment completes, access your Lychee instance at https://example-app.klutch.sh. Log in with your admin credentials.

Initial Setup and Configuration

Creating Albums

Organize your photos into albums:

1. Click the + button on the main page
2. Select New Album
3. Enter album title and description
4. Set visibility (public, private, or password protected)
5. Click Create

Uploading Photos

Add photos to your library:

1. Open an album or stay on the main page
2. Click the Upload button
3. Select files from your computer
4. Wait for upload and processing to complete
5. Photos appear with generated thumbnails

Smart Albums

Set up automatic organization:

1. Navigate to Settings > Smart Albums
2. Configure criteria for each smart album:
   • Recent: Photos from the last 7 days
   • Starred: Your favorite photos
   • Public: All publicly visible photos
   • On This Day: Photos from today in previous years

User Management

Add additional users:

1. Go to Settings > Users
2. Click Add User
3. Enter username, email, and password
4. Set permissions (upload, edit, admin)
5. Save the new user

Sharing Options

Public Albums

Share albums with anyone:

1. Open album settings
2. Set visibility to Public
3. Copy the direct album URL
4. Share the link with anyone

Password Protected

Add password protection:

1. Open album settings
2. Set visibility to Private
3. Enable password protection
4. Set a password
5. Share the password with intended viewers

Download Options

Allow photo downloads:

1. Open album settings
2. Enable Allow Downloads
3. Visitors can download individual photos or the entire album

Advanced Features

EXIF Data Display

Show photo metadata:

1. Navigate to Settings > Photo Display
2. Enable EXIF data display
3. Choose which fields to show (camera, lens, settings, etc.)
4. EXIF data appears in photo details view

Map View

Visualize photo locations:

1. Ensure photos have GPS data
2. Enable map view in settings
3. Configure map provider (OpenStreetMap, etc.)
4. Access the map view from the navigation

Import from Server

Import existing photos:

1. Place photos in the designated import directory
2. Navigate to Settings > Import
3. Click Import from Server
4. Select folders to import
5. Lychee processes and adds photos to your library

Production Best Practices

Security Recommendations

• Strong Passwords: Use strong passwords for all accounts
• HTTPS Only: Always access Lychee over HTTPS
• Regular Backups: Back up your photos and database regularly
• Access Control: Review album visibility settings
• Update Regularly: Keep Lychee updated for security patches

Performance Optimization

• Thumbnail Generation: Pre-generate thumbnails for large uploads
• Image Optimization: Enable image compression settings
• CDN Integration: Consider CDN for public galleries
• Resource Allocation: Scale resources based on library size

Backup Strategy

Protect your photo library:

1. Photo Backups: Regularly back up /uploads directory
2. Database Backups: Back up the database regularly
3. Configuration Backup: Export settings and preferences
4. Offsite Storage: Store backups in a separate location

Troubleshooting Common Issues

Photo Upload Failures

Symptoms: Uploads fail or timeout.

Solutions:

• Check PHP upload size limits
• Verify disk space availability
• Review file permissions
• Check supported file formats

Thumbnails Not Generating

Symptoms: Photos display without thumbnails.

Solutions:

• Verify ImageMagick is installed
• Check queue worker is running
• Review thumbnail directory permissions
• Manually trigger thumbnail regeneration

Slow Gallery Loading

Symptoms: Gallery pages load slowly.

Solutions:

• Enable browser caching
• Optimize database queries
• Generate thumbnails in advance
• Consider pagination for large albums

Additional Resources

• Lychee Official Documentation
• Lychee GitHub Repository
• Lychee Community Discussions
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying Lychee on Klutch.sh gives you a beautiful, self-hosted photo management solution with professional gallery features. The combination of Lychee’s elegant interface and Klutch.sh’s deployment simplicity means you can focus on your photography rather than infrastructure.

With album organization, sharing options, and smart album features, Lychee provides everything needed for personal photo management or professional portfolio presentation. Whether you’re archiving family memories or showcasing your creative work, Lychee on Klutch.sh offers a reliable, always-available platform that you control.