skrop

README

Skrop  

Skrop is a media service based on Skipper and the vips library.

Usage

In order to be able to use Skrop, you have to be familiar with how Skipper works.

Getting started

Skrop is 'go get' compatible. If needed, create a Go workspace first:

mkdir ~/go-workspace
cd ~/go-workspace
export GOPATH=$(pwd)

This can be set up in the BASH profile (~/.bash_profile or ~/.bashrc)

export GOPATH=~/go-workspace

Get the Skrop sources:

go get github.com/zalando-stups/skrop

Install dependencies:

System dependencies

The vips library needs to be installed for Skrop to build.

On macOS, that can be easily done using brew.

brew install vips

On a Linux machine, use the provided script.

run packaging/install-vips.sh

GO dependencies

Only on macOS, you have to manually install Glide using Brew.

brew install glide

Then, for all.

./packaging/build.sh
go get github.com/Masterminds/glide
go get ./cmd/skrop/

Run Skrop

go run cmd/skrop/main.go -routes-file eskip/sample.eskip -verbose

Test

make all

To test if everything is configured correctly you should open in your browser

http://localhost:9090/images/big-ben.jpg

and the resized version

http://localhost:9090/images/S/big-ben.jpg

Here is how a route from the sample.eskip file would look like:

small: Path("/images/S/:image")
  -> modPath("^/images/S", "/images")
  -> longerEdgeResize(800)
  -> "http://localhost:9090";

What it means, is that when somebody does a GET to http://skrop.url/images/S/myimage.jpg, Skrop will call http://localhost:9090/images/myimage.jpg to retrieve the image from there, resize it, so that its longer edge is 800px and return the resized image back in the response.

Filters

Skrop provides a set of filters, which you can use within the routes:

• longerEdgeResize(size) — resizes the image to have the longer edge as specified, while at the same time preserving the aspect ratio
• crop(width, height, type) — crops the image to have the specified width and height the type can be "north", "south", "east" and "west"
• cropByHeight(height, type) — crops the image to have the specified height
• cropByWidth(width, type) — crops the image to have the specified width
• resize(width, height, opt-keep-aspect-ratio) — resizes an image. Third parameter is optional: "ignoreAspectRatio" to ignore the aspect ratio, anything else to keep it
• addBackground(R, G, B) — adds the background to a PNG image with transparency
• convertImageType(type) — converts between different formats (for the list of supported types see here
• sharpen(radius, X1, Y2, Y3, M1, M2) — sharpens the image (for info about the meaning of the parameters and the suggested values see here)
• width(size, opt-enlarge) — resizes the image to the specified width keeping the ratio. If the second arg is specified and it is equals to "DO_NOT_ENLARGE", the image will not be enlarged
• height(size, opt-enlarge) — resizes the image to the specified height keeping the ratio. If the second arg is specified and it is equals to "DO_NOT_ENLARGE", the image will not be enlarged
• blur(sigma, min_ampl) — blurs the image (for info see here)
• imageOverlay(filename, opacity, gravity, opt-top-margin, opt-right-margin, opt-bottom-margin, opt-left-margin) — puts an image onverlay over the required image
• transformFromQueryParams() - transforms the image based on the request query parameters (supports only crop for now) e.g: localhost:9090/images/S/big-ben.jpg?crop=120,300,500,300.

About filters

The eskip file defines a list of configuration. Every configuration is composed by a route and a list of filters to apply for that specific route. Skrop adds by default two filters (setupResponse() and finalizeResponse()). The filter setupResponse() initialize the response by adding in the context the image received from the backend. The finalizeResponse() needs to be added at the end, because it triggers the last transformation of the image.

Because of performance, each filter does not trigger a transformation of the image, but if possible it is merged with the result of the previous filters. The image is actually transformed every time the filter cannot be merged with the previous one e.g. both edit the same attribute and also at the end of the filter chain by the finalizeResponse filter.

Metadata

By default metadata are kept in the processed images. If you are not interested in metadata and you want them stripped from all the images that are processed, you can add the following environment variable to the running system:

STRIP_METADATA=TRUE

Packaging

In order to package skrop for production, you're going to need Docker. To build a Docker image, just run the build script (the arguments are optional):

make docker version=1.0.0 routes_file=eskip/sample.eskip docker_tag=zalando-stups/skrop

Now you can start Skrop in a Docker container:

make docker-run

Continuous Integration

We are using Travis CI for this project.

GitHub Token

In order for Travis CI to perform its duty, a valid GitHub token must be encrypted in the Travis configuration file.

If this token needs to change, here is how to set it up:

• Log on to GitHub on the account you want Travis CI to impersonate when performing operation on the repository
• Go to GitHub, in your Personal access tokens configuration
• Click on Generate new token
• Keep the default (nothing checked)
• Click Generate token

We will now encrypt that token with the travis CLI. Make sure it is installed.

travis encrypt GITHUB_AUTH=the_token_copied_from_github

This will encrypt it in a way that only Travis CI can decrypt. Your personal token is then quite safe.

The output should look like this.

  secure: "someBASE64value"

Take the output (the complete YAML key as it appears) and replace, in the .travis.yaml file, this line with the output of the previous command.

env:
- secure: "someBASE64value"

Versioning

This project uses semantic versioning.

The patch-version (3rd digit) is bumped up automatically at every merge to master (by Travis CI).

Increment the patch version

This is done automatically by Travis CI. Nothing special to do here. Example: merging when latest tag is v3.23.291 will automaticall tag a version v3.23.292.

Increment the minor version

Since Travis CI only automatically increases the patch-version, we need to manually pre-tag with the new version we want.

Scenario:

• actual version is v3.23.291
• tag one of the commit on your branch with the new version you want.
  • it is important that the patch version be -1, since it will be incremented automatically by Travis CI.
  • git tag v3.24.-1 && git push --tags
• open the pull request.
• after merge, Travis CI will tag automatically the right final version v3.24.0.
• delete the temporary manual tag
  • git tag -d v3.24.-1 && git push --tags

Increment the major version

Since Travis CI only automatically increases the patch-version, we need to manually pre-tag with the new version we want.

Scenario:

• actual version is v3.23.291
• tag one of the commit on your branch with the new version you want.
  • it is important that the patch version be -1, since it will be incremented automatically by Travis CI.
  • git tag v4.0.-1 && git push --tags
• open the pull request.
• after merge, Travis CI will tag automatically the right final version v4.0.0.
• delete the temporary manual tag
  • git tag -d v4.0.-1 && git push --tags

License

MIT