top
(readme.md)
A Golang powered image caching and resizing reverse proxy.
It supports automatic, on-the-fly image resizing, and caches the results 
for best performance.

## Usage

Any of the following ways are valid to access scaled images. In the examples
below, they would all result in an image that's 100px wide, with the height
being relative to the width.

`yourserver.com/100/some/file/photo.png`

`yourserver.com/some/file/photo.png?w=100`

To fetch the original, unmodified image, just access it directly:

`yourserver.com/some/file/photo.png `

## Build and Install (Ubuntu Only)

```sh
git clone https://github.com/BitolaCo/proximity.git
cd proximity
sudo mkdir -p /etc/proximity/ssl
sudo cp config/config.json /etc/proximity/config.json
sudo go build -o /usr/bin/local/proximity main.go
sudo cp config/proximity.conf /etc/init
```

## Configuration

If you followed the instructions above, the config file
will now be at `/etc/proximity/config.json`, it's default location.

You can run it from the command line, too, with the `--config` flag:

`proximity --config=/custom/config/dir/config.json`

A sample configuration file looks like this:

```json
{
  "hosts": {
    "127.0.0.1": "upload.wikimedia.org",
  },
  "storage": "",
  "ttl": 1,
  "listen": ":4000",
  "quality": 70, 
  "colors": 256
}
```

Here's a rundown of each variable:

- `hosts`: A key/value pair that matches the incoming address (i.e. `yourserver.com`) with the remote address (i.e. `upload.wikimedia.org`)
- `storage` Path to store the cached files in. Defaults to system temp directory (maybe `/tmp`, who knows?)
- `ttl` Time to live of cached files, in minutes.
- `listen` Address to bind/listen on. Leave off the ip address to listen on 0.0.0.0
- `quality` Quality of resized JPEG's. Applies to jpegs only.
- `colors` Colors in resampled gif's. Applies to gif's only.


Most important part here is probably the `hosts` and `listen` options.
Hosts matches a reqest host name (the key) to an upstream server (where to fetch the images from).
In the example above, `"127.0.0.1": "upload.wikimedia.org"` means requests to 127.0.0.1 would be
mapped to the corresponding file on `upload.wikimedia.org`

## Production configuration

Changes are, you'll want to use it with a proxy setup, though it's strictly not necessary as
it does support full, valid SSL connections if desired.

#### Nginx

```
# For Nginx
location / {
    proxy_pass        http://localhost:4000/;
}
```

#### Apache
```
ProxyPass / http://localhost:4000
ProxyPassReverse / http://localhost:4000
```

## Using In HTML

For the automatic scaling, a JavaScript package is being tested. The source is in the
`assets` directory of the repository.


### Including the JavaScript file

The javascript file can be included by adding a script tag to the fixed location on
the Proximity server. The server will set the correct parameters automatically for you:

```html
<script src="//yourserver.com/script"></script>
```

The resizing assumes the images will fit the parent container. As such, 
you'll need to make sure the images have a the following css set up:

```css
.optimized {
  display: block;
  width: 100%;
  max-width: 100%;
}
```

The default class for the images is `.optimized`, although you can change that by passing the `c=className` to
the server when including the script tag mentioned above:

```html
<script src="//yourserver.com/script?c=my-cool-class"></script>
```

In the example above, the JavaScript would then to it's work with any element with the class name `.my-cool-class`
instead of the default class.

### Using Images

Images need to have the class set (see above), and also have either a `data-src` or `data-bg` attribute 
set (or both). You'll want to set up the image to have some kind of `src` until it can be loaded, so just
use `data:` for now. (We're looking into valid options.)

*The `data-src` and `data-bg` are relative to the root of the Proximity server, not the HTML page.*

Here's an exmaple of a standard image:

```html
<img class="optimized" src="data:" data-src="/my/cool/image.png">
```

Here's an example of a background image:

```html
<span class="optimized" data-bg="/my/cool/background.jpg"></span>
```

Of course, if you don't want to use the auto-sizing feature via JavaScript, you don't have to.
Just use the `src` attribute directly:

```html
<img src="//my-proximity-server/my/cool/image.png"><!-- standard size -->
<img src="//my-proximity-server/32/my/cool/image.png"><!-- 32px width -->
<img src="//my-proximity-server/my/cool/image.png?w=128"><!-- 128px width -->
<!-- etc. -->
```

## Roadmap

- Allow timed/remote reload of configuration
- Remove out-dated cache automatically
- Write tests
- Lock down sizing to a predefined set of widths (Small differences handled via CSS and 100% width, would also support srcset?)
- Generate all sizes automatically on first visit.
- Logging to system log
- Log performance with each request
- Standardize the log format for easier parsing later on
- Add blank image for spacing in client side
- Add client side javascript fetch url.
- Add support for background images `url(//some/image/file.png)`

## License

Licensed under the [MPL](https://www.mozilla.org/MPL/) license.

(c) 2015 Brad Berger and Bitola Software Company

Imports 2 package(s) ΒΆ

  1. github.com/gorilla/mux
  2. github.com/nfnt/resize