It is simple. Everything is ready in three steps:
  1. Copy your photos to directories and their subdirectories. (more details)
  2. Modify optional settings and run the Rhotoalbum generator. (more details)
  3. Enjoy :)
Photo folders   A photo folder with photos   A photo view
Real photo albums:

Please, visit the Rhotoalbum's GitHub page.

The latest version 0.9 was released on January 17, 2011. The first one on May 25, 2007.

Rhotoalbum is a photo album generator programmed in Ruby.

It works with a directory structure, it produces static web content and it does not require any database.

Rhotoalbum generates thumbnails and the index.html (rss.xml) file in each subdirectory. There is a possibility to add titles and descriptions of the images.

I. What do I need?

Minimal configuration

Additional configuration

i) for generating cute thumbnails by applying various effects:

ii) for displaying EXIF data of the photos:

For installing the libraries you may need an admin or root access, e.g. on Linux you may use sudo gem install exifr.


There are two ways how to publish the photos and files generated by rhotoalbum:

a) a web hosting with a shell account

b) a minimal web hosting or without Ruby or libraries

II. Directory Structure

Rhotoalbum expects that your photos are stored in directories (and their subdirectories). The Rhotoalbum files should be installed (do not worry, it means unpacked) it the top directory of this structure.

Example 1:


In this example, the Rhotoalbum files should be stored in the photos directory.

Example 2:

      200702 Beach
      200705 Party
      200703 Nice sunset
      200705 Party

Again, the Rhotoalbum files should be stored in the photos directory.

III. How does it work?

ruby rhotoalbum.rb

That's all :)

and in details...

Rhotoalbum starts in the actual directory where it gathers all subdirectories and image files.

If there are image files, it creates the thumbnails directory, creates a thumbnail for each image and stores is in the thumbnails directory.

Then it creates the index.html file that contains:

And it repeats these steps for each subdirectory (and its subdirectories).

Directories and files are ordered by their names.

IV. Customization

There are plenty of possibilities how to customize the generated result.

The first step is to prepare your options file options.yml by copying the options template options.yml.template, so the next rhotoalbum update does not overwrite your settings:
(Windows) copy options.yml.template options.yml
(Linux or OS X) cp options.yml.template options.yml

IV.1 Title and Author

Change the title option to set the photoalbum title:
title: My Photos

Change the author option to set the author name:
author: John Smith

IV.2 Thumbnail effects

There are various thumbnail effects that can be set in the effect setting:
Effect Effect Effect Effect Effect
reflection shadow polaroid glow rotate

And there are various album thumbnail effects that can be set in the effectAlbum setting:
Effect Effect
stack polaroid_stack

All effects that include rotating (rotate, polaroid and all album effects) are randomly rotated - each thumnail looks slightly different; and each generator run will produce different thumbnails.

Once a thumbnail is generated, it is not generated again - it is necessary to remove existing thumbnails to reflect a changed effect option. This can be done by calling the rhotoalbum generator with the clean command:
ruby rhotoalbum.rb clean

To clean only album thumnails (highlight.jpg) you may use the cleanhighlight command:
ruby rhotoalbum.rb cleanhighlight

IV.3 Album cover

The album cover is by default the first image in the album. The album cover image is used to generate an album thumbnail - that is used in the parent album page as an image for the album link.

To change the default behaviour (the first image of album) just create the cover.jpg file the album:

IV.4 Album thumbnail

A link to an album = subdirectory uses a thumbnail highlight.jpg located in that subdirectory.

It is automatically created from the first image or the cover image in the album = directory, however there is a possibility to set own or already genereated thumbnail:

Note: This is an older way how to set an album thumbnail, but it is still supported and it allows to use own images as thumnails.

IV.4 Best Practice

The best practice / sequence of steps for generating albums:

  1. Deployment
    • Upload directory structure with your images and install Rhotoalbum to the root directory.
  2. Descriptions (optional)
    1. Run
      ./rhotoalbum.rb text
      to generate description.txt files.
    2. Write descriptions of the albums and images to the description.txt file in each directory.
  3. Customisation (optional)
    1. Copy options.yml.template to options.yml, e.g.
      cp options.yml.template options.yml
    2. Customize the options in the options.yml file, e.g. enable cool effects for the photo slideshow:
      panning: true
      fading: true
  4. Generation
    • Run
      All thumbnails, index pages will be generated.
  5. Highlights
    • Create cover.jpg or highlight.jpg (by copy or symbolic link) in each directory for the album front page.
    • Run
      rhotoalbum.rb cleanhighlight
      to refresh album thumbnails changes.

V. JavaScript Image Viewer

Rhotoalbum uses the TripTracker slideshow. See the link for more details.

VI. License

Rhotoalbum is distributed under the GPL license.


A few of (not so) frequently asked questions:

VIII. Advanced

VIII.1 Command Line

./rhotoalbum.db [command]
  generate (default)        generates index.html, thumbnails for all subdirectories
                            recursively (doesn't overwrite already generated files)

  text                      generates descriptions.txt file in each subdirectory where
                            album/photo descriptions can be written

  rebuild                   combines cleanindex, text, and generate (helpful when using text description for your photos)

  cleanindex                remove all index.html files recursively

  clean                     remove all generated thumbnails, indices, highlights

  help                      displays a short Usage

VIII.2 Description Files

If a photo title is not enough, you can assign a description text to any album or photo.

Thereare two ways how to do it:

  1. One file per description. This is useful for ad-hoc description of few images. The text file name is the original file name of image or directory + '.txt', e.g. for IMG123.JPG the description file is IMG123.JPG.txt
  2. Central file for all description per album. description.txt containing one-line mappings of the format: image name, text separated by colon, semicolon, comma or tab, e.g.
    IMG123.JPG  : Sunset
    My Album    : Vacation 2007

VIII.3 Customization

You can customize the album generation. You can do it in the options.yml file. If this file is present the options will be used. You can copy the file from options.yml.template

The following properties can be customized:

title:: name of the album
author:: author or authors
author_label:: a label that should be used in the copyright section for author(s), e.g. Author, Authors or Artist
css:: default style to be used
explicitIndexHtml: true or false -- if true, appends '/index.html' to links; useful when you're browsing the album locally
styleSwitcher:: true or false -- to show the style switcher
showTitleAlbum:: true or false -- to show the album title
showStatsAlbum:: true or false -- to show the album statistics
showTitlePhoto:: true or false -- to show the photo title
showDescription:: true or false -- to show the photo description
descriptionAsName:: true or false -- displays photo/album descriptions instead of the name everywhere
showDate:: true or false -- to show the photo date
showExif:: true or false -- to show the basic EXIF data (exposure time, focal length and f-number)
showExtendedExif:: true or false -- to show extended EXIF data (camera model)
thumbnailDim:: 256x256 -- the thumbnail size
panning:: true or false -- to enable the panning effect for the JavaScript photo viewer
fading:: true or false -- to enable the fading effect for the JavaScript photo viewer
labelNoPhoto:: no photos -- a label for no photo in an album
labelOnePhoto:: one photo -- a label for one photo in an album
labelMorePhotos:: # photos -- a label for more photos in an album
labelOneAlbum:: one album -- a label for one subalbum in an album
labelMoreAlbums:: # albums -- a label for more subalbums in an album
copyright:: your copyright section, it may include links to e.g. creative commons licenses.
generateRss:: true or false -- generate RSS (MediaRSS 2.0) feed for each album
google_analytics:: tracker-code or nil -- if the trackers code is given, it generates google analytics for each album
nonrecursive:: true or false -- do not process all album directories, just the root
maxPerPage:: number-of-items-per-page or -1 -- enables/defines pagination for albums.
debug:: true or false -- verbose debuging messages
effect:: options (nil, 'reflection', 'shadow', 'polaroid', 'glow', 'rotate') -- applies an effect to the thumbnail
effectAlbum: options( nil, 'stack', 'polaroid_stack') -- applies an effect to an album thumbnail
effectBackground:: color definitions, e.g. '#000000', red -- background for the effectss

Thanks to:

Michael Adams for his CSS file optimisation and double thumbnails fix.

Mooffie for the relative links, adding index.html to URLs for browsing without a web server and a fix for the too many open files bug.

Ondrej Jaura

Viktor Zigo

May 2007 - January 2011