Skip to content

Creating an image server

When importing IIIF manifests from files or from S3 buckets, or calling the CreateIIIFURL or CreateIIIFInformation API endpoints, Arkindex starts with a complete IIIF image URL and must detect where to split the URL into its image server and image components for storage.

Automatic detection

An image server detection algorithm is used for any attempt to create an IIIF image through the API:

  1. List the existing image servers whose URL starts with the image’s URL.

  2. When exactly one server is found, use this server.

  3. When more than one server is found, cause an error:

The URL "…" matched multiple existing image servers.

In this scenario, a system administrator will likely need to merge or delete the conflicting servers.

  1. When no servers are found, attempt to create a new server by looking for a common prefix found in most IIIF servers: /iiif/2/, /iiif/, /i3f/ or /iiif-img/.

For example, an image at https://example.org/iiif/2/image.jpg would be split into a server at https://example.org/iiif/2 and an image at image.jpg.

  1. When none of those prefixes are found, cause an error:
The URL "…" does not match any existing image server.
Please ask an instance administrator to register the IIIF server for this image.

Manual creation

When Arkindex is unable to create an image server on its own, or when a specific prefix should be used instead of the ones it can automatically detect, system administrators can create an image server manually through the administration interface.

Display name

Required. A readable name for this server. This is available in the API but not typically used, as it is only meant to help administrators in organizing image servers.

URL

Required. The URL that will be added before the path of any image. Images whose URLs do not have this prefix cannot belong to this server. This URL may start with either http:// or https://.

Allow external validation

Optional. When this is set, API users may send in their own image width and height when creating images on this specific server, and Arkindex will trust them. The image will be created immediately and the image checks will be run asynchronously, which can help improve performance when importing large amounts of images that have already been validated as compatible with Arkindex by an external tool.

API users will also need the Can validate images permission to use this feature.

This setting is only meant for advanced use cases and is not used by any feature within Arkindex directly.

Max width

Optional. The maximum width of any image that the server can return. When this is set, the Arkindex backend will never generate image URLs that request an image larger than this width.

This should match the maxWidth property of the profile returned in the image information (/info.json) for any image belonging to this server.

Max height

Optional. The maximum height of any image that the server can return. When this is set, the Arkindex backend will never generate image URLs that request an image larger than this height.

This should match the maxHeight property of the profile returned in the image information (/info.json) for any image belonging to this server.

S3 bucket

Optional. The S3 bucket that this server retrieves images from. This is only used for the local image server for file imports, and ignored elsewhere.

S3 region

Optional. The Amazon Web Services region that this server retrieves images from. This is only used for the local image server for file imports, and ignored elsewhere. This has no effect when the S3 API is used outside of Amazon Web Services.

S3 read-only bucket

Optional. This can only be enabled if an S3 bucket is defined. When this is set, Arkindex will not perform the additional MD5 hash checks that it may make when the S3 bucket is set.