thumbsup/README.md

```
┌───┐ ┌───┐ ┌───┐ ┌───┐ ┌───┐ ┌───┐ ┌───┐ ┌───┐
│ t │ │ h │ │ u │ │ m │ │ b │ │ s │ │ u │ │ p │
└───┘ └───┘ └───┘ └───┘ └───┘ └───┘ └───┘ └───┘
```

[![NPM](http://img.shields.io/npm/v/thumbsup.svg?style=flat)](https://npmjs.org/package/thumbsup)
[![License](http://img.shields.io/npm/l/thumbsup.svg?style=flat)](https://github.com/rprieto/thumbsup)
[![Dependencies](http://img.shields.io/david/rprieto/thumbsup.svg?style=flat)](https://david-dm.org/rprieto/thumbsup)

Build static HTML galleries from local photos & videos.

- thumbnails & multiple resolutions for fast previews
- mobile friendly website with customisable themes
- only rebuilds changed files: it's fast!
- uses relative paths so you can deploy the pages anywhere
- works great with Amazon S3 for static hosting

## Table of contents

<!-- START toc -->
- [Table of contents](#table-of-contents)
- [Example gallery](#example-gallery)
- [Required folder structure](#required-folder-structure)
- [Setup](#setup)
  * [As an npm package](#as-an-npm-package)
- [Expected output](#expected-output)
- [Configuration](#configuration)
- [Generated gallery structure](#generated-gallery-structure)
- [Themes](#themes)
- [Deployment](#deployment)
- [Password protection](#password-protection)
- [Dev notes](#dev-notes)

<!-- END toc -->

## Example gallery

You can [view a sample gallery here](http://rprieto.github.io/thumbsup).

[![screenshot](https://raw.github.com/rprieto/thumbsup/master/screenshot.jpg)](http://rprieto.github.io/thumbsup)

## Required folder structure

Any folder with photos and videos!
`thumbsup` currently supports 1 level of subfolders, where they each become a gallery.

```
input
  |
  |__ paris
  |    |__ img001.jpg
  |    |__ img002.jpg
  |
  |__ sydney
       |__ vid001.mp4
       |__ img003.png
```

## Setup

### As an npm package

**Requirements**

- [Node.js](http://nodejs.org/): `brew install Node`
- [GraphicsMagick](http://www.graphicsmagick.org/): `brew install graphicsmagick`
- [FFmpeg](http://www.ffmpeg.org/): `brew install ffmpeg`

*Note: there currently is [an issue with Ubuntu 14.04](#27) if you build `ffmpeg` from source. Please upgrade to 14.10 and install it with `apt-get`.*

**Installation**

```bash
npm install -g thumbsup
```

**Creating a basic gallery**

```bash
thumbsup --input ~/photos --output ~/gallery
```

## Expected output

If everything worked well, you should expect:

```bash
$ thumbsup [args]

  List all files      [===================] 6/6 files
  Update metadata     [===================] 6/6 files
  Original photos     [===================] 6/6 files
  Original videos     [===================] 6/6 files
  Photos (large)      [===================] 5/5 files
  Photos (thumbs)     [===================] 5/5 files
  Videos (resized)    [===================] 1/1 files
  Videos (poster)     [===================] 1/1 files
  Videos (thumbs)     [===================] 1/1 files
  Static website      [===================] done

  Gallery generated successfully
```

`thumbsup` keeps track of which files need updating.

Re-running the command above when nothing has changed will show the same output but only take a second,
even on a 50GB folder with thousands of photos and videos.

## Configuration

The following args are required:

- `--input <path>` path to the folder with photos / videos
- `--output <path>` target output folder

And you can optionally specify:

- `--title [text]` website title (default: `Photo gallery`)
- `--thumb-size [pixels]` thumbnail image size (default: `120`)
- `--large-size [pixels]` fullscreen image size (default: `1000`)
- `--original-photos [true|false]` to allow download of full-size photos (default: `false`)
- `--original-videos [true|false]` to allow download of full-size videos (default: `false`)
- `--sort-folders [name|date]` how to sort the folders/galleries (default: `date`)
- `--theme [name]` name of the gallery theme to apply (default: `default`)
- `--css [file]` CSS or LESS styles to be applied on top of the theme (no default)
- `--google-analytics [code]` code for Google Analytics tracking (no default)

*Note:* all paths are relative to the current working directory.
For example:

```bash
thumbsup --input "/media/photos" --output "./website" --title "My holidays" --thumb-size 200 --large-size 1500 --full-size-photos true --sort-folders date --css "./custom.css" --google-analytics "UA-999999-9"
```

You can also save all your arguments to a `JSON` file:

```bash
thumbsup --config config.json
```

**config.json**

```js
{
  "input": "/media/output",
  "output": "./website",
  "title": "My holiday",
  "thumb-size": 200,
  "large-size": 1500,
  "original-photos": true,
  "original-videos": false,
  "sort-folders": "date",
  "css": "./custom.css",
  "google-analytics": "UA-999999-9"
}
```

## Generated gallery structure

The generated static website has the following structure:

```
website
  |__ index.html
  |__ sydney.html
  |__ paris.html
  |__ public
  |__ media
  |    |__ original
  |    |__ large
  |    |__ thumbs
```

##  Themes

The `--theme` flag allows you to select a style for the generated gallery.
The only theme so far is called `default`, but please submit more ideas to share!

Some themes have [LESS](http://lesscss.org/) variables that you can customise.
Check [THEMES.md](THEMES.md) for more details.
Simply use the `--css` option and pass a LESS file with your values, e.g.

```less
// thumbsup --css custom.less

@myvariable: #cef9b6;
```

## Deployment

The simplest is to deploy the media and generated pages to S3 buckets on AWS using the [AWS CLI tools](http://aws.amazon.com/cli/).

- `aws s3 sync ./generated/website s3://my.website.bucket --delete`

You can also use [s3cmd](http://s3tools.org/) which offer a few more options.

- `s3cmd sync --config=<credentials> --delete-removed --exclude-from <exclude-file> ./generated/website/ s3://my.website.bucket/`


## Password protection

Amazon S3 buckets do not offer any type of authentication. If you want to protect your galleries, you can

- deploy the galleries to UUID-based locations, like Dropbox shared galleries
- use [CloudFront with signed cookies](http://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/PrivateContent.html) in front of S3
- deploy to another web server that offers password protection, such as Varnish/Apache/Nginx with `HTTP Basic Auth`

## Dev notes

To create the sample gallery locally:

```bash
npm run clean      # clean the output
npm run example    # build the gallery
npm run open       # open it in the browser
```