2.0.0 • Public • Published


Build Status Maintainability Test Coverage


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



  • 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'


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 for details and workarounds.


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





npm i serverless-iiif

DownloadsWeekly Downloads






Unpacked Size

14.1 MB

Total Files


Last publish


  • mbklein