Release Notes

Release notes

The top of this file contains the latest stable release and relevant notes about what has changed since the previous release.

Starting with release 4.0.0, this changelog is being updated to a loose version of Keep a Changelog

Unreleased (4.0.0)

The upcoming release, code-named "Next Release", makes several major changes that will affect backward-compatibility. Stick with 3.3.x if you need these features.

Fixed

IIIF URL parsing is now more permissive in cases where a slash is in an image's identifier, and it didn't get escaped properly for any reason
Various bad IIIF requests now report a useful error rather than just crashing the request
--log-level configuration is now always respected

Added

S3 assets can be pulled from a custom S3-compatible endpoint instead of AWS by setting S3Endpoint in your configuration file, or the environment variable RAIS_S3ENDPOINT
The S3 demo now includes "minio" so you can see how S3 could work without actually setting up an AWS account
The docker image based on Alpine now works with the demo docker-compose.yml setup
- The S3 demo still requires the bigger image because the Alpine image doesn't include plugins
JPEG quality now defaults to 75 instead of 80, and is configurable via JPGQuality in rais.toml, RAIS_JPGQUALITY environment variable, or --jpg-quality on the command line

Changed

The S3 plugin is no longer restricted to a single bucket; instead, the bucket is part of the URL to match AWS's command-line tools: s3://bucket/prefix/key
- This is also a backward-incompatible change from the previous way S3 URLs had to be set up; see migration notes for details
- IDs should still be escaped, e.g., s3:%2F%2Fbucket%2Fprefix%2Fkey.
Decoder plugins no longer have to expose ImageDecoders; they just register their decoder functions directly
DecodeFunc (which decoder plugins use when calling img.RegisterDecoder) receives a URL instead of a file path to allow for non-file images

Removed

DZI support is no longer worth the extra maintenance. With major image viewers like OpenSeadragon supporting IIIF, there's not a lot of need for DZI anymore.
The IIIF URL setting (--iiif-url, IIIFURL setting in rais.toml, or RAIS_IIIFURL environment variable) caused too much heartache across multiple projects using RAIS. RAIS can have its hostname set manually (which may be necessary for situations where there's no way to pass this information from the original request), but it's usually easiest to just let it infer based on the requests and proxy headers. See the migration notes.
Since there's no IIIFURL setting, the path now defaults to /iiif; e.g., a full URL would look something like http://localhost:12415/iiif/jp2tests%2Fsn00063609-19091231.jp2/full/512,512/0/default.jpg with the default value
- This can be customized via a new setting, IIIFWebPath.

Migration

Instead of setting IIIFURL, try to let RAIS infer the URL (see On-Inferring-BaseURL for details)
- If you have to set a URL manually, use IIIFBaseURL and IIIFWebPath
If you were using the S3 plugin, you'll need to adjust your URLs to use the canonical S3 format, e.g., s3://bucket/prefix/key rather than s3:prefix/key.
Any plugins which register decoders will need to be changed to expose their decode handlers rather than defining an ImageDecoders function. The easiest way to understand how this works is in the ImageMagick plugin.
- Change any DecodeFunc implementations to receive rais/src/img.Streamer instead of a file path. They can use Streamer.Location() to determine if they handle the Streamer's object, e.g. by pulling the object's extension: ext := filepath.Ext(Streamer.Location().Path)

Release 3.3.1

Small but important hotfixes:

The default docker image no longer exposes the insecure "external images" plugin without an explicit environment variable. You cannot enable insecure plugins now with any flags or settings unless the new RAIS_ALLOW_INSECURE_PLUGINS environment variable is set to "1".
The external images plugin now works again - the previous test URL became invalid, so it now uses one I expect to be more stable
Docker builds now work again

Release 3.3.0

Release 3.3.0 includes a bunch of minor improvements:

Removed ImageMagick as a dependency for default builds by moving all the imagick-specific code into a plugin.
- RAIS (and basically every image server, really) can't process huge non-JP2 images efficiently, so this was never a widely-used option, but its inclusion added a massive dependency.
- ...but the standard docker image will continue to include the ImageMagick plugin since that image is so absurdly huge anyway
- If you want to handle non-JP2 sources and you're building RAIS manually, you need to build the plugin yourself now (make bin/plugins/imagick-decoder.so).
Various "under the hood" improvements for building code (the Makefile rules)
The main docker image has had a lot of small changes:
- Base image is Fedora 30 instead of 29
- The Go compiler is now 1.12 instead of 1.11
- The nginx configuration has been improved
The example config (rais-example.toml) has clearer instructions and better default values
Manual RedHat configuration documentation is now in the wiki instead of a local file, and is slightly more accurate
Added request logging, rather than only logging the "processing" side of things
Improved error handling and reporting for image decoders

In addition, we now have a new alpine-based docker image, making the fastest open-source JP2 tile server also the smallest! If you wanted to take the Docker version of RAIS for a spin, this image will get you up and running in no time.

Release 3.2.1

Note: Due to a misconfiguration, 3.2.0 and 3.2.1 are the same codebase, but 3.2.1 bumped the Docker image to use Fedora 29 as its base.

Rais 3.2.1 overhauls RAIS to improve cloud usage significantly by adding an administrative endpoint. By default it's exposed to port 12416 to avoid accidentally publishing it to the Internet directly.

The key benefit of all this work is to make it possible to purge caches from a separate application, such as the application which manages the images in the first place.

An example form that posts a purge to RAIS can be seen in the S3 demo: https://github.com/uoregon-libraries/rais-image-server/blob/develop/docker/s3demo/admin.go.html#L13-L34

Release 3.1.1

Note: Due to a mistaken version bump, 3.1.0 doesn't exist.

RAIS 3.1.1 improves plugins, the build process, and docker setups in significant ways.

Plugin improvements:

The S3 plugin now has a complete demo to showcase exactly how a gallery could be stood up in a production environment. It's not pretty, but it works well for an on-demand S3 pull-and-serve demonstration.
- See https://github.com/uoregon-libraries/rais-image-server/blob/v3.1.1/docker/s3demo/README.md for details
Plugins are now specified in config rather that all auto-loaded
- You can specify absolute paths, meaning plugins don't have to live in a "magic" subdirectory anymore
- You can modify config to change what plugins are loaded and then simply restart RAIS rather than having to copy or move files around - this should ease docker use significantly.
- You can compile any plugin you like, and not worry about accidentally having an insecure plugin in production. If a plugin isn't loaded, none of its code will run, period.
- It's still obviously safer just to not deploy insecure plugins, but this adds a significant layer of safety
To aid in S3 plugin debugging, we've added a script, scripts/s3list.go, which can be run to see what assets exist in a given bucket.
A new plugin was added for doing generalized tracing of performance, json-tracer. This allows you to send information to other APM solutions than just DataDog (e.g., Honeycomb.io), or even simply crunch the data locally.
The S3 plugin now "buckets" downloaded assets to avoid a million files living in a single directory
Plugins now explicitly state to RAIS whether they're enabled (e.g., if configuration was incorrect)
Plugin shutdown is now much more reliable

Build improvements:

The binaries are built with debugging info stripped, resulting in slightly smaller files for production use
The lint make target now runs go vet in addition to golint to improve error detection
The Makefile no longer has target for each individual plugin
The example deploy script (scripts/deploy.sh) now builds plugins and deploys the "safe" ones (i.e., it doesn't deploy the external-images plugin). We use this script, slightly modified, in production.

Docker improvements:

The docker image build (make docker) works better and more consistently now
The demo docker-compose.yml file no longer includes a "build box", resulting in simpler demo runs
- scripts/buildrun.sh now uses its own docker-compose file so you can still run builds in docker if desired
The docker-based local demo is now slightly easier to work with
The example docker override (docker-compose.overrride-example.yml) is more useful
The docker image now builds with Go 1.11.1
The docker image now builds all plugins
The docker build runs go mod download prior to putting all the source files in the container in order to speed up rebuilds of the image

Other miscellaneous changes:

Removed a script that was no longer relevant from scripts/
RAIS now reports image decoding errors without trying to send the HTTP headers twice
OpenJPEG debugging has been removed - it was far too chatty even for debug info

Release 3.0.0

RAIS 3.0.0 marks one of the biggest changes RAIS has seen to date!

Massive changes:

RAIS now supports Go plugins, and there are three example plugins to look at, two of which are suitable for use in production:
- The S3-images plugin lets you save a ton of money if you can take a performance hit. S3 storage is extremely cheap, but the first request for an uncached file will be a bit slow. The plugin could probably use some refinement, but it works beautifully in some test cases we've tried out.
- The DataDog plugin is very simple and can give you a high-level overview of how long RAIS is taking to process requests
- Read more in the Plugins document
Dockerfile.build / Dockerfile.prod have been merged into a single multi-stage file
The docker-compose setup now passes all RAIS_* environment variables into the rais container, allowing for easier configuration via an .env file (or manually exporting environment variables)
The docker-compose setup is now far more generalizable
For those wanting to test out plugins, there are various docker-compose examples you can string together. For instance: docker-compose -f docker-compose.yml -f docker-compose.s3.yml
Major rewrite in IIIF URL parsing to improve how errors are reported when a request cannot be handled. Instead of just knowing the URL was invalid, you can now see things like "invalid quality" if "default" were misspelled to "defualt" or something.
Massive improvement to non-JP2 file performance when tiles are cached: RAIS used to read the file into memory (via ImageMagick libs) and then check the cache. Oops.
Legacy "chronam" handlers have been removed. RAIS is now exclusively for use with IIIF and DeepZoom clients.
If caching is enabled, a very basic cache info response is printed to logs every 10 minutes
RAIS now attempts to shut down gracefully instead of just immediately closing all connections

Other fixes:

Various comments have been fixed or improved to simplify the codebase
Most of the README has been moved to this wiki
Small improvements to various bits of code to reduce errors and improve developers' experiences

Release 2.11.2

Another very minor release: fixed issues with the local docker demo

Release 2.11.1

Very minor release: fixed version number and some documentation issues

Release 2.11.0

Major changes:

Supports new features defined in IIIF 2.1:
- maxArea, maxWidth, and maxHeight may be set via configuration values in rais.toml or put into an overridden info.json file
  - If an image is requested that exceeds these values, the server will return an error, allowing for better image protection as well as reduced DOS attack vectors
- "square" region keyword
- "max" size keyword
- Reports features "sizeByConfinedWh" and "sizeByDistortedWh" in info.json
GIF output has been disabled by default. It can be re-enabled with a custom capabilities toml file, but it is recommended you don't do this as GIF is notoriously slow in RAIS.

Docker image changes:

Uses Fedora 28 instead of 27
RAIS now runs as an unprivileged user
The demo uses docker-compose instead of being a bash script
Binaries use Go 1.11 for compilation
Added capacity to change demo container's capabilities

Minor / backend changes:

Source code format is now using the "go modules" approach rather than gb (gb is no longer being maintained as the author feels modules make more sense)
Minor test / coverage improvements
Slightly better logging
Minor code refactor

Release 2.10.1

Fixed memory leak due to mistake in openjpeg API usage

Release 2.10.0

Changed OpenJPEG interfacing to fix incompatibility with OpenJPEG 2.3.0
Upgraded Docker image to use Fedora 27, which has OpenJPEG 2.3.0, improving performance significantly
Minor "housekeeping" to clean up code and improve testing and benchmarking
Sample deploy script is now based on RHEL 7

Release 2.9.1

Adds ability to filter logging by severity

Release 2.9.0

Adds a timeout for HTTP connections to (hopefully) avoid "accept4: too many open files" errors when things get too slow or networks drop temporarily
Updates the build environment to use Go 1.9.2
Improves the apache Open Seadragon / DeepZoom test container setup

Release 2.8.1

Fixes errors when a viewer uses URL query parameters

Release 2.8.0

Adds experimental support for handling the DeepZoom protocol

Release 2.7.2

Un-fixes tile caching to avoid huge delays when Open Seadragon pulls the initial thumbnails

This un-fix unfortunately adds a fair amount of potentially cached images which may not be desired. It's a necessary evil, however, as huge JP2s can take 30 seconds or more when Open Seadragon insists on pulling 5-10 lower-resolution thumbnails before it will start working.

Release 2.7.1

Fixes tile caching to be significantly more selective about what is considered a tile

Release 2.7

Adds a new option to /etc/rais.toml for caching tiles in memory
Uses Go 1.6.3 for Docker build

Release 2.6