serverless-iiif

Description

A IIIF 2.1 Image API compliant server written as an AWS Serverless Application.

Components

• A simple Lambda Function wrapper for the iiif-processor module.
• A Lambda Layer containing all the dependencies for the Lambda Function.
• An API Gateway interface for the Lambda Function.
• A CloudFormation template describing the resources needed to deploy the application.

Prerequisites

• Some basic knowledge of AWS.
• An Amazon Web Services account with permissions to create resources via the console and/or command line.
• An Amazon S3 bucket to hold the source images to be served via IIIF. Note: The Lambda Function will be granted read access to this bucket.

Quick Start

serverless-iiif is distributed and deployed via the AWS Serverless Application Repository. To deploy it using the AWS Console:

1. Click to 👉 Deploy the Serverless Application 👈 from the AWS Console.
2. Make sure your currently selected region (in the console's top navigation bar) is the one you want to deploy to.
3. Scroll down to the Application settings section.
4. Give your stack a unique name, enter the name of the image bucket, and check the box acknowledging that the app will create an IAM execution role for itself.
5. Click Deploy.
6. When all the resources are properly created and configured, the new stack should be in the CREATE_COMPLETE stage. If there's an error, it will delete all the resources it created, roll back any changes it made, and eventually reach the ROLLBACK_COMPLETE stage.
7. Click the CloudFormation stack link.
8. Click the Outputs tab to see (and copy) the IIIF Endpoint URL.

Source Images

The S3 key of any given file, minus the extension, is its IIIF ID. For example, if you want to access the image manifest for the file at abcdef.tif, you would get https://.../iiif/2/abcdef/info.json. If your key contains slashes, they must be URL-encoded: e.g., ab/cd/ef/gh.tif would be at https://.../iiif/2/ab%2Fcd%2Fef%2Fgh/info.json. (This limitation could easily be fixed by encoding only the necessary slashes in the incoming URL before handing it off to the IIIF processor, but that's beyond the scope of the demo.)

iiif-processor can use any image format natively supported by libvips, but best results will come from using tiled, multi-resolution TIFFs. The Lambda Function wrapper included in this application assumes a .tif extension.

Creating tiled TIFFs

Using VIPS

vips tiffsave source_image.tif output_image.tif --tile --pyramid --compression jpeg --tile-width 256 --tile-height 256

Using ImageMagick

convert source_image.tif -define tiff:tile-geometry=256x256 -compress jpeg 'ptif:output_image.tif'

Testing

If tests are run locally they will start in "watch" mode. If a CI environment is detected they will only run once. From the project root run:

npm test

To generate a code coverage report run:

npm test --coverage

Known Limitations

AWS API Gateway Lamnbda integration has a payload (request/response body) size limit of approximately 6MB in both directions. Please see LAMBDA_LIMIT.md for details and workarounds.

License

This software is licensed under the Apache License, Version 2.0. Dependencies are subject to their own licenses.

Contributors

• Michael B. Klein
• Justin Gondron
• Edward Silverton
• Trey Pendragon
• Dan Wolfe