Features

Tenrankai is packed with features designed to make hosting and managing photo galleries a breeze. Whether you're a photographer showcasing your portfolio or an organization managing multiple image collections, Tenrankai has you covered.

🎉 New in Latest Release: Enhanced metadata system with XMP support, gallery filters, click-to-zoom loupe, React frontend, flexible image indexing, and much more! Tenrankai now supports professional photography workflows with user comments, picks, and tags.

📂 File-Based Architecture

No Database Required

Tenrankai operates entirely on files and folders - no database setup or maintenance:

  • Drop images in folders to create galleries
  • Add markdown files for descriptions and captions
  • Write blog posts as simple markdown files
  • Configuration is just a TOML file
  • Everything is human-readable and version-control friendly
  • Permissions in config: Define access rules right in your TOML

SyncThing Integration

Perfect for distributed workflows with SyncThing:

  • Edit your gallery on any device
  • Changes sync automatically to your server
  • No deployment process - just save and sync
  • Keep multiple servers in sync effortlessly
  • Works with any file synchronization tool

Simple Deployment

Since everything is files, deployment is straightforward:

  • Copy files to server - you're done!
  • Use rsync, SyncThing, Dropbox, or git
  • No database migrations or schema updates
  • Easy backup - just copy the folders
  • Portable between servers
  • Docker support with official images

🖼️ Gallery Management

Multiple Independent Galleries

Run unlimited galleries from a single Tenrankai instance, each with:

  • Custom URL prefixes (e.g., /portfolio, /family, /projects)
  • Independent source directories and cache locations
  • Per-gallery configuration for image quality and sizes
  • Custom templates for unique gallery experiences
  • Gallery-specific permissions: Different access rules per gallery
  • Individual copyright holders: Different watermarks per gallery

Responsive Masonry Layout

Beautiful, mobile-friendly gallery layouts that adapt to any screen size:

  • Automatic column adjustment based on viewport
  • Smooth animations and transitions
  • Touch-friendly navigation on mobile devices
  • Optimized for both portrait and landscape orientations
  • Metadata badges: ✓ (picks), ★ (highlights), 💬 (comments)
  • Filter bar: Persistent URL-based filtering

Folder Organization

Organize photos hierarchically with full support for nested folders:

  • Automatic breadcrumb navigation
  • Folder descriptions via markdown files
  • Hidden folders for private collections
  • Custom folder titles and metadata

📸 Image Processing

Automatic Resizing

Generate multiple image sizes automatically:

  • Thumbnail: Small previews for gallery grids
  • Gallery: Standard viewing size
  • Medium: Larger size with optional watermarking
  • Large: Full quality (authentication required)
  • @2x variants for all sizes (retina display support)

Format Optimization

Intelligent format selection for optimal performance:

  • Full AVIF support: HDR preservation and gain maps
  • Automatic WebP conversion for supported browsers
  • JPEG fallback for maximum compatibility
  • PNG support with transparency preservation
  • Configurable quality settings per format
  • Content negotiation based on Accept headers
  • Smart format selection based on browser capabilities

Color Profile Preservation

Full support for professional color management:

  • ICC profile extraction and preservation
  • Display P3 and Adobe RGB support
  • Color profiles maintained through watermarking
  • Both JPEG and WebP profile embedding

Enhanced Metadata System

Multi-source metadata with priority cascade:

  • Markdown frontmatter: Override any metadata with TOML
  • XMP sidecar files: Adobe Lightroom compatible
  • EXIF extraction: Camera, lens, GPS, settings
  • Astronomy support: Telescope, mount, exposure hours
  • Custom fields: Tags, descriptions, additional details
  • Priority order: Markdown > XMP > EXIF

⚡ Performance & Caching

Intelligent Caching System

Multi-level caching for lightning-fast performance:

  • In-memory metadata cache with persistence
  • Processed image cache on disk
  • Automatic cache refresh in background
  • Version-based cache invalidation
  • Configurable cache directories per gallery

Concurrent Processing

Blazing-fast image processing:

  • Parallel image processing with rate limiting
  • Non-blocking background tasks
  • Async I/O throughout the application
  • Efficient memory usage with streaming

Pre-generation Options

Optional cache pre-generation for instant loading:

  • Generate all image sizes on startup
  • Background processing without blocking
  • Progress tracking and logging
  • Skip already cached images

📝 Content Management

Markdown Support

Rich content with simple markdown files:

  • Folder descriptions with _folder.md
  • Image captions with [imagename].md
  • TOML frontmatter for metadata
  • Full CommonMark support

Built-in Blog System

Multiple markdown-based blog systems:

  • TOML frontmatter for post metadata
  • Automatic HTML generation
  • Chronological sorting and pagination
  • Subdirectory organization
  • Gallery image embedding support
  • Automatic reload on file changes
  • Permission-aware: Posts visibility based on user roles

Dynamic Content Updates

Keep content fresh without restarts:

  • API endpoints for content refresh
  • Automatic periodic refresh options
  • Hot-reload for development
  • Individual file update detection
  • Permission-protected refresh: Only admins can trigger updates

🎉 Interactive Features NEW

Enhanced user interaction capabilities:

  • Click-to-Zoom Loupe: 2x magnification with click-and-hold
  • User Metadata Storage: Comments, picks, highlights, tags in .toml sidecars
  • Area-Specific Comments: Select and comment on specific parts of images
  • Gallery Filters: Filter by picks, rejects, highlights, comments
  • Permission-based interaction: Fine-grained control over features
  • Collaborative workflows: Multiple users can comment and organize
  • React Frontend: Modern SPA with swipe navigation on mobile
  • Image Protection: Harder to save images via right-click

👥 Collaboration & Feedback

Area-Specific Comments NEW

Provide precise feedback by commenting on specific parts of images:

  • Visual Selection: Click and drag to select rectangular areas
  • Mobile Friendly: Touch gestures supported on tablets and phones
  • Context Preservation: Areas remain highlighted when viewing comments
  • Edit Support: Add, change, or remove areas when editing comments
  • Responsive Display: Percentage-based coordinates adapt to any screen size
  • Visual Previews: See highlighted areas in comment threads

Use Cases for Area Comments

Perfect for professional workflows and collaboration:

  • Client Feedback: "Please adjust the lighting in this corner"
  • Photo Critique: Point out composition elements or technical issues
  • Quality Control: Mark blemishes, dust spots, or areas needing retouching
  • Education: Highlight examples of good technique or areas for improvement
  • Collaborative Editing: Discuss specific elements without ambiguity
  • Event Photography: Identify people or important details in group shots

🔒 Security & Permissions

Role-Based Access Control (RBAC)

Fine-grained permissions system with over 20 different permissions:

  • Viewing permissions: Control basic image viewing and folder browsing
  • Privacy permissions: Show/hide dates, location, and technical details
  • Download permissions: Control access to different image sizes
  • Interactive permissions: NEW Enable zoom and metadata reading
  • Content management: Comments, picks, and tags with user-level control
  • Custom roles: Create roles tailored to your needs
  • Per-gallery settings: Different permissions for each gallery
  • Folder-level overrides: Fine-tune access within galleries

Copyright Watermarking

Protect your images with intelligent watermarking:

  • Automatic text color selection based on background
  • Configurable watermark text and positioning
  • Applied only to medium-sized images
  • Preserves image quality and color profiles
  • Per-gallery copyright holders: Different watermarks for different galleries

Modern Authentication

Secure, user-friendly authentication system:

  • WebAuthn/Passkey support: Biometric login on phones and computers
  • Hardware security keys: YubiKey and FIDO2 device support
  • Passwordless email login: Simple magic link authentication
  • Session management: Secure cookies with configurable expiry
  • Rate limiting: Protection against brute force attacks
  • User management CLI: Easy user and role administration
  • Permission-aware UI: Features automatically show/hide based on permissions

Privacy Protection

Multiple layers of privacy control:

  • Date Privacy: Show only month/year to viewers without permissions
  • Location Privacy: Hide GPS coordinates based on user roles
  • Technical Details: Hide camera/lens info per folder
  • URL Privacy: Three indexing modes (filename, sequence, unique_id)
  • Non-guessable URLs: 6-character base36 IDs prevent enumeration
  • Per-gallery privacy: Different settings for each gallery
  • Folder-level control: Override gallery settings per folder

🐳 Deployment Options

Docker Support

Official Docker images for easy containerized deployment:

  • Optimized multi-stage builds (~168 MB)
  • Security hardening with non-root user
  • Environment variable configuration
  • Docker Compose examples included
  • Kubernetes-ready with health checks
  • Support for Docker Swarm deployments

Traditional Deployment

Deploy directly on any Linux server:

  • Single static binary - no runtime dependencies
  • Systemd service examples provided
  • Nginx and Apache reverse proxy configurations
  • Built-in Let's Encrypt support via proxy
  • Resource-efficient - runs on minimal VPS

🛠️ Developer Features

Template System

Flexible Liquid templating engine:

  • Customizable gallery and image templates
  • Reusable partial components
  • Per-gallery template configuration
  • Full Liquid syntax support
  • Automatic cache-busting with asset_url filter

Cascading Static Directories

Advanced asset management with precedence:

  • Multiple static directories with override support
  • Theme customization without modifying defaults
  • Perfect for A/B testing and seasonal themes
  • Automatic file version tracking
  • Cache-busting for all static assets

RESTful API

Comprehensive API endpoints:

  • Gallery preview and metadata
  • Image serving with size parameters
  • Content refresh triggers
  • Health check endpoints
  • Permission-aware API: Responses filtered by user roles
  • User metadata API: Comment and pick management
  • Filter API: Query parameters for metadata filtering

Monitoring & Logging

Production-ready observability:

  • Structured logging with configurable levels
  • HTTP access logs with latency tracking
  • Error tracking and reporting
  • Performance metrics

CLI Tools

Powerful command-line utilities:

  • User management: add, list, update, remove users
  • AVIF debugging: Analyze AVIF metadata and color properties
  • Server control: Auto-shutdown for testing
  • Configuration: Override settings via CLI flags
  • Consistent help: Improved command documentation

Ready to Experience These Features?

Get started with Tenrankai today and build your perfect gallery.

Read the Documentation View Source Code