Features
Tenrankai is a photo gallery server designed for photographers and teams who want full control over their images. No database, no complex setup -- just files, folders, and a single binary.
- File-Based Architecture -- No database, SyncThing-ready
- Gallery Management -- Multiple galleries, flexible grid modes, web uploads
- Image Processing -- Resizing, format conversion, HDR/AVIF, metadata
- AI Analysis -- OpenAI Vision for keywords and alt-text
- Performance -- Caching, pre-generation, parallel processing
- Content Management -- Blog, markdown, inline editing
- Collaboration -- Comments, picks, area-specific feedback
- Security -- RBAC, watermarks, WebAuthn, privacy controls
- Deployment -- Docker, systemd, S3 storage
- Developer Tools -- Templates, theme editor, CLI, REST API
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
Flexible Grid Modes
Choose the layout that fits your content:
- Masonry layout: Variable-height grid preserving image aspect ratios
- Square grid: Uniform cells with images fitted inside (not cropped)
- Variable columns: Responsive 1-5 columns based on viewport width
- Max columns cap: Control maximum columns per gallery or folder
- Folder overrides: Different grid settings per folder via
_folder.md - Smooth animations and transitions
- Touch-friendly navigation on mobile devices
- 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
Web-Based Image Management NEW
Full image management directly from your browser:
- Upload images: Drag-and-drop with resumable TUS uploads (500MB per file)
- Create folders: Organize content without file system access
- Batch operations: Select multiple images for bulk actions
- Move and copy: Reorganize images between folders
- Hide and unhide: Control visibility without deleting
- Delete: Remove images when needed
- Smart sidecars: Automatically associates .xmp, .md, and RAW files
- Permission-based: Controlled by
can_manage_imagespermission
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
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 fast, consistent page loads:
- 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
Parallel image processing for large galleries:
- 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
Advanced Watermarking NEW
Protect your images with text or PNG image watermarks:
- Text watermarks: Auto-adjusting color based on background
- PNG image watermarks: Use custom logos and graphics
- Position options: Corners, center, or tiled pattern
- Adaptive mode: Auto-invert grayscale watermarks on light backgrounds
- Per-size control: Choose which image sizes get watermarked
- Admin UI: Configure watermarks visually without editing config
- 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
Visual Theme Editor NEW
Customize your site's appearance without writing CSS:
- Visual Color Picker: Point-and-click color customization for dark and light modes
- 42 Curated Fonts: Google Fonts organized by style with live preview
- Force Color Scheme: Lock users to dark or light mode if desired
- Instant Preview: Site reloads automatically after saving changes
- Reset to Defaults: One-click restore of original theme
- CSS Variables: Advanced users can still use theme-override.css
- 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
- TCP health checks for monitoring
- 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
Get Running in 5 Minutes
Clone the repo, build, and serve your first gallery with the Quick Start guide.