Quick Start Guide

This documentation covers the latest version of Tenrankai. Check the GitHub releases page for the current version.

Want to get Tenrankai running quickly? This guide will have you up and running in just a few minutes.

Prerequisites

  • Rust installed (the project will handle the version)
  • Git
  • Node.js (for building the React frontend)

5-Minute Setup

1. Clone and Build

git clone https://github.com/theatrus/tenrankai.git
cd tenrankai
npm ci
cd admin && npm ci && cd ..
cargo build --release

2. Create Basic Configuration

Create a config.toml bootstrap file:

[server]
host = "127.0.0.1"
port = 3000

[app]
name = "My Photo Gallery"
cookie_secret = "CHANGE_ME_generate_with_openssl_rand_base64_32"
config_storage = "config.d"

3. Initialize ConfigStorage and Set Up Directories

# Initialize the ConfigStorage directory with a default site
./target/release/tenrankai config init config.d

# Add a gallery to the default site
./target/release/tenrankai config add-gallery main --site default \
  --source photos --url-prefix /gallery

# Create directories
mkdir -p photos cache static

# Add the required font for watermarks
wget https://github.com/dejavu-fonts/dejavu-fonts/releases/download/version_2_37/dejavu-fonts-ttf-2.37.tar.bz2
tar -xjf dejavu-fonts-ttf-2.37.tar.bz2
cp dejavu-fonts-ttf-2.37/ttf/DejaVuSans.ttf static/
rm -rf dejavu-fonts-ttf-2.37*

# Add some test photos
cp ~/Pictures/*.jpg photos/  # Or copy from your photo collection

4. Run Tenrankai

./target/release/tenrankai serve

5. View Your Gallery

Open your browser to: http://localhost:3000

That’s it! You now have a working photo gallery.

What’s Next?

Add More Photos

Simply copy photos to the photos directory. Tenrankai will automatically:

  • Generate thumbnails
  • Extract metadata from EXIF, XMP sidecar files, and markdown frontmatter
  • Create a responsive gallery with masonry layout
  • Build the React frontend for modern image viewing

Pro tip: Use SyncThing to sync your photos folder between your devices and server. Edit on your phone or laptop, and your gallery updates automatically!

Organize Your Photos

Create subdirectories for organization:

photos/
├── vacation-2026/
│   ├── beach-photos/
│   └── city-tour/
└── family-events/
    ├── birthday/
    └── holidays/

Add Descriptions

Create _folder.md in any directory:

+++
title = "Summer Vacation 2026"
hide_technical_details = false  # Show camera info
+++

# Summer Vacation 2026

Photos from our amazing trip to the coast. Perfect weather and great memories!

Or add metadata to individual images with IMAGE.jpg.md:

+++
title = "Sunset at the Beach"
description = "Golden hour magic captured at Big Sur"
tags = ["sunset", "landscape", "california"]
+++

This was taken during our last evening at the coast.

Control Privacy

Want to hide dates and locations from public viewers? Easy:

# config.d/sites/default/permissions.toml
public_role = "viewer"

[roles.viewer]
name = "Viewer"

[roles.viewer.permissions]
can_view = true       # Includes thumbnail & gallery size downloads
can_use_zoom = true   # Keep zoom for better viewing
# Add these to show dates/location:
# can_see_exact_dates = true  # Shows only month/year when omitted
# can_see_location = true     # Hides GPS data when omitted

For maximum privacy, use non-guessable URLs:

# In gallery TOML file (config.d/sites/default/galleries/main.toml)
image_indexing = "unique_id"  # URLs like /gallery/image/a3k2x

Enable Blog

Create a blog post in posts/blog/:

+++
title = "Welcome to My Gallery"
summary = "Introduction to my photo collection"
date = "2026-01-01"
+++

# Welcome!

This gallery showcases my photography journey...

Common Tasks

Change Port

Edit config.toml:

[server]
port = 8080

Enable Authentication

Add a user database to your site config, and email to the bootstrap config:

# config.d/sites/default/site.toml
user_database = "users.toml"

# config.toml (bootstrap)
[email]
provider = "null"  # Logs emails for development
from_address = "noreply@yourdomain.com"

# WebAuthn/Passkeys are automatically enabled when user_database is set

Then add users:

./target/release/tenrankai user add admin admin@example.com

Enable user metadata (comments, picks, tags) by adding a member role to permissions.toml:

# config.d/sites/default/permissions.toml
default_authenticated_role = "member"

[roles.member]
name = "Member"

[roles.member.permissions]
can_view = true
can_add_comments = true
can_set_picks = true
can_add_tags = true

Users can now:

  • Leave comments on specific areas of images
  • Mark favorites with picks (✓)
  • Add tags for organization
  • See visual indicators in the gallery view

Enable Debug Logging

./target/release/tenrankai --log-level debug serve

Refresh Gallery

The gallery automatically refreshes every 60 minutes, or trigger manually:

curl -X POST http://localhost:3000/api/gallery/main/refresh

Troubleshooting

“Font file not found”

  • Ensure DejaVuSans.ttf is in the static directory

“No images in gallery”

  • Check that your photos directory contains supported formats (JPEG, PNG, WebP, AVIF)
  • Verify the source_directory path in config.toml

“Port already in use”

  • Change the port in config.toml or kill the process using the port

“React build failed”

  • Ensure Node.js is installed
  • Check npm error messages in the log output

Learn More