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: Full S3 storage support for cloud-native deployments, CSS theming with custom variables, AI-powered image analysis, and much more! Tenrankai now supports hybrid local/cloud configurations for maximum flexibility.

📂 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

🤖 AI-Powered Image Analysis NEW

OpenAI Vision Integration

Automatic keyword and alt-text generation using AI:

  • Smart keywords: Automatically extract relevant keywords from image content
  • Accessibility alt-text: Generate descriptive alt-text for screen readers
  • Batch processing: Analyze entire galleries with a single command
  • Background processing: Optional automatic analysis of new images
  • Rate limiting: Configurable delays between API calls
  • Incremental: Only analyzes images without existing keywords

Analysis CLI Commands

Powerful command-line tools for batch analysis:

  • Gallery analysis: tenrankai analyze-images -g photos
  • Folder targeting: Analyze specific folders only
  • Limit controls: Set maximum images per run
  • Force mode: Re-analyze already processed images
  • Dry run: Preview what would be analyzed
  • Clear command: Remove AI-generated data when needed

AI Analysis Use Cases

Enhance your galleries with AI-generated metadata:

  • SEO optimization: Better search visibility with relevant keywords
  • Accessibility compliance: WCAG-compliant alt-text for all images
  • Content discovery: Help users find images by content
  • Archive organization: Auto-categorize large image collections
  • Social sharing: Better previews with AI-generated descriptions

⚡ 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
  • Memory protection: Limits concurrent operations to CPU cores

Pre-generation Options

Configurable cache pre-generation for instant loading:

  • Parallel processing: Uses all CPU cores for fast generation
  • Selective formats: Choose which formats (JPEG, WebP, AVIF)
  • Selective sizes: Choose which sizes (thumbnail, gallery, medium, large)
  • Tile pre-generation: Pre-build tiles for enhanced zoom
  • Incremental: Only generates missing cache entries
  • Graceful cancellation: Clean shutdown on Ctrl+C

📝 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:

  • Image Preloading: Adjacent images preload for instant navigation
  • Filmstrip Navigation: Thumbnail strip for quick browsing on desktop
  • Desktop Loupe: Click-and-hold zoom with optional high-res tiles
  • Mobile Pinch-to-Zoom: Native gestures with fullscreen modal and tiles
  • 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

☁️ S3 Storage Support NEW

Full Amazon S3 integration for cloud-native deployments:

  • Unified Storage API: Same configuration for local or S3 storage
  • URL-based config: s3://bucket/prefix?region=us-west-2
  • Hybrid configurations: Local source with S3 cache for optimal performance
  • Signed URL redirects: Direct S3 downloads reduce server bandwidth
  • All components supported: Galleries, caches, templates, posts, static files
  • AWS credential chain: Environment, credentials file, or IAM roles
  • Streaming support: Efficient handling of large files from S3

🛠️ 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

🎨 CSS Theming System NEW

Complete visual customization through CSS variables:

  • CSS Custom Properties: Override colors, fonts, spacing with simple variables
  • Dark/Light Mode: Built-in theme toggle with automatic OS preference detection
  • Custom Fonts: Use Google Fonts or self-hosted fonts easily
  • Stable Classes: Safe component classes for reliable customization
  • theme-override.css: Drop-in customization file for quick theming
  • No Core Modifications: Customize everything without touching source files

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
  • Cache management: report, cleanup, invalidate, list-composites
  • AI analysis: analyze-images, clear-analysis for batch processing
  • AVIF debugging: Analyze AVIF metadata and color properties
  • Server control: Auto-shutdown for testing
  • Configuration: Override settings via CLI flags

Ready to Experience These Features?

Get started with Tenrankai today and build your perfect gallery.

Read the Documentation View Source Code