Wolpi: An Extensible IIIF Image Server

Wolpi is a libvips-based IIIF Image API (2.1 and 3.0) compliant image server. It is from the ground up designed to be easily extensible and customizable in order to fit into different use cases and workflows.

Use it to serve images through standard IIIF URLs, with enough configuration and extension hooks to adapt it to local storage, metadata systems, authorization, custom image processing and operational monitoring.

Quickstart

To get your feet wet with Wolpi, we recommend you start with our tutorials:

• Serve your first image.
• Use an extension to resolve images regular expressions.
• Deploy Wolpi on a server, via Docker/Podman, bare-metal using the published JAR, or in your Kubernetes cluster.
• Configuring Wolpi: use the configuration reference.
• Writing extensions: read Developing Extensions.

Configuration

The YAML-based configuration allows you to customize various aspects of Wolpi's behavior, such as:

• vips image encoding options, e.g. JPEG quality, WebP presets, etc.
• optional IIIF Image API features and limits, the IIIF Image API compliance level and info.json response are adjusted accordingly.
• Operational options like HTTP settings and logging behavior
• Extensions and their runtime options

Refer to the configuration documentation to learn more about the available configuration options.

Extending Wolpi

Wolpi can be extended using custom extensions written in JavaScript or Python. These extensions can be used to customize various aspects of Wolpi's behavior in ways that do not violate the IIIF Image API specification:

• Authorization, e.g. to integrate with your organization's IIIF Authorization Flow API implementation.
• Resolving identifiers to image sources, with the option to include image metadata from an external source to avoid hitting the filesystem for info.json requests.
• Augmenting the info.json response, e.g. to include references to additional IIIF services.
• Image operations that go beyond the IIIF Image API specification, such as watermarking, smart cropping, custom filters, custom output formats or custom encoding for existing formats.

Refer to the extension usage documentation to learn how to install and configure existing Wolpi extensions. To learn how to write your own extensions, refer to the extension development documentation.

Operating Wolpi

Wolpi provides everything required to run it both on traditional servers and in cloud environments:

• Runnable as a standalone JAR, OCI container, or Kubernetes deployment.
• Full support for HTTP caching semantics (ETags, Last-Modified, Cache-Control, etc.) to easily integrate with CDNs and proxy caches.
• Health checks, Prometheus metrics and structured logging.

Most of the above features are integrated into the extension API, so custom extensions can log, export metrics, and provide cache metadata for resolved images as well.