Skip to content
Klutch.sh Docs

Deploying Mejiro

Introduction

Mejiro is a lightweight, database-free photo gallery written in PHP. Named after the Japanese white-eye bird, Mejiro creates beautiful galleries directly from your image folders without requiring complex setup, database management, or extensive configuration.

The simplicity of Mejiro makes it ideal for quickly sharing photo collections. Just drop your images into folders, and Mejiro automatically generates a clean, responsive gallery with thumbnails and navigation. It’s perfect for photographers, artists, or anyone who wants to share images without the overhead of a full-featured photo management system.

Key highlights of Mejiro:

  • No Database Required: Works directly with your file system
  • Folder-Based Organization: Create albums by organizing images into folders
  • Automatic Thumbnails: Generates thumbnails on-the-fly
  • Responsive Design: Clean, mobile-friendly interface
  • EXIF Data Display: Shows camera settings and metadata
  • Lightbox Viewing: Full-screen image viewing with navigation
  • Minimal Configuration: Works out of the box with sensible defaults
  • Lightweight: Small footprint with fast performance
  • Password Protection: Optional album-level authentication
  • 100% Open Source: Simple, auditable PHP code

This guide walks through deploying Mejiro on Klutch.sh using Docker, configuring persistent storage for your photo library, and customizing your gallery.

Why Deploy Mejiro on Klutch.sh

Deploying Mejiro on Klutch.sh provides several advantages for self-hosted photo galleries:

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

Persistent Storage: Attach persistent volumes for your photo library. Your images survive container restarts and redeployments.

HTTPS by Default: Klutch.sh provides automatic SSL certificates for secure image viewing and sharing.

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

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

Custom Domains: Assign a custom domain for a professional portfolio or gallery.

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

Prerequisites

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

  • A Klutch.sh account
  • A GitHub account with a repository for your configuration
  • Basic familiarity with Docker and containerization concepts
  • Your photo collection ready for upload
  • (Optional) A custom domain for your gallery

Preparing Your Repository

To deploy Mejiro on Klutch.sh, create a GitHub repository containing your Dockerfile and configuration.

Repository Structure

mejiro-deploy/
├── Dockerfile
├── config.php
├── README.md
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM php:8.1-apache


# Install GD extension for image processing
RUN apt-get update && apt-get install -y \
    libpng-dev \
    libjpeg-dev \
    libfreetype6-dev \
    && docker-php-ext-configure gd --with-freetype --with-jpeg \
    && docker-php-ext-install gd \
    && rm -rf /var/lib/apt/lists/*


# Enable Apache mod_rewrite
RUN a2enmod rewrite


# Set working directory
WORKDIR /var/www/html


# Clone Mejiro
RUN apt-get update && apt-get install -y git \
    && git clone https://github.com/dmpop/mejiro.git . \
    && rm -rf .git \
    && apt-get remove -y git \
    && rm -rf /var/lib/apt/lists/*


# Copy custom configuration
COPY config.php /var/www/html/config.php


# Create photos directory
RUN mkdir -p /var/www/html/photos


# Set permissions
RUN chown -R www-data:www-data /var/www/html \
    && chmod -R 755 /var/www/html


# Expose port
EXPOSE 80


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

Creating the Configuration File

Create config.php to customize your gallery:

<?php
// Gallery title
$title = "My Photo Gallery";


// Gallery description
$description = "A collection of photographs";


// Photos directory (relative to Mejiro root)
$photos_dir = "photos";


// Thumbnail size (in pixels)
$thumb_size = 300;


// Number of photos per page
$per_page = 24;


// Show EXIF data
$show_exif = true;


// Timezone
$timezone = "UTC";


// Footer text
$footer = "Powered by Mejiro";
?>

Environment Variables Reference

VariableRequiredDefaultDescription
GALLERY_TITLENoMy Photo GalleryGallery title
PHOTOS_DIRNophotosPhotos directory path
THUMB_SIZENo300Thumbnail size in pixels

Deploying on Klutch.sh

    Push Your Repository to GitHub

    Initialize your repository and push to GitHub:

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

    Configure HTTP Traffic

    Mejiro serves its web interface over HTTP. In the deployment settings:

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

    Attach Persistent Volumes

    Add the following volumes:

    Mount PathRecommended SizePurpose
    /var/www/html/photosSize of your libraryPhoto files and albums

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

    Access Mejiro

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

Organizing Your Photos

Folder Structure

Create albums by organizing images into folders:

/photos/
├── 2024/
│   ├── Summer Vacation/
│   │   ├── image1.jpg
│   │   ├── image2.jpg
│   │   └── image3.jpg
│   └── Birthday Party/
│       └── photos...
├── Nature/
│   ├── Landscapes/
│   └── Wildlife/
└── Portfolio/
    └── selected works...

Supported Image Formats

Mejiro supports common image formats:

  • JPEG (.jpg, .jpeg)
  • PNG (.png)
  • GIF (.gif)

Naming Conventions

For best results:

  • Use descriptive folder names for albums
  • Avoid special characters in folder and file names
  • Keep file names consistent

Customization

Changing the Theme

Edit config.php to customize appearance:

// Custom CSS colors
$background_color = "#1a1a2e";
$text_color = "#eaeaea";
$accent_color = "#0f3460";

Place your logo in the Mejiro directory and reference it in config:

$logo = "logo.png";
$logo_height = 50;

Password Protection

Protect albums with a password:

  1. Create a .htpasswd file
  2. Configure Apache authentication
  3. Place in specific album directories

Features

Album Navigation

Browse your gallery:

  • Click folder names to enter albums
  • Use breadcrumbs to navigate back
  • Sort by name or date

Image Viewing

View images in full resolution:

  • Click thumbnails to open lightbox
  • Navigate with arrow keys or swipe
  • View EXIF data if enabled

Thumbnail Generation

Mejiro automatically generates thumbnails:

  • Created on first view
  • Cached for faster subsequent loads
  • Regenerated if source changes

Uploading Photos

Transfer Methods

Get photos onto your persistent volume:

  • Deploy a file manager alongside Mejiro
  • Use SFTP/SCP for direct upload
  • Sync with cloud storage using rclone

Batch Processing

For large uploads:

  1. Prepare photos locally
  2. Upload in batches
  3. Organize into folders
  4. Verify in gallery

Troubleshooting

Thumbnails Not Generating

  • Verify GD extension is installed
  • Check PHP error logs
  • Ensure write permissions on cache directory

Images Not Appearing

  • Confirm supported image format
  • Check file permissions
  • Verify photos are in correct directory

Slow Loading

  • Optimize original image sizes
  • Enable browser caching
  • Consider a CDN for large galleries

Additional Resources

Conclusion

Deploying Mejiro on Klutch.sh gives you a simple, elegant photo gallery without the complexity of database-driven systems. Just upload your images, organize them into folders, and Mejiro creates a beautiful gallery automatically.

The combination of Mejiro’s simplicity and Klutch.sh’s reliable infrastructure makes it easy to share photos with friends, family, or clients. Whether you’re showcasing a portfolio, sharing vacation photos, or archiving memories, Mejiro on Klutch.sh provides an elegant solution that you fully control.