Skip to content

Release Notes

Jump to bottom
Jeremy Echols edited this page Feb 19, 2024 · 30 revisions

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

4.1.3

Fixed

  • RAIS is no longer using "git flow", as the overhead for a mostly solo project was just too cumbersome, and hotfixing the "stable" branch (main) really wasn't occurring often enough to justify that overhead.
  • Many dependencies have been updated, though the cloud components are still pretty far behind what's current. These are used by very few people, so we want to stick with what's known to be stable as opposed to bleeding-edge.
    • Note that there are vulnerabilities in some of these packages - these do not affect RAIS! Go's govulncheck verifies that there are multiple reported vulnerabilities, but none of the vulnerable code paths are in use.

Changed

  • golint has been deprecated, so we've replaced it with revive. You will have to install this if you want to do development work.

4.1.1

Fixed

  • RAIS no longer crashes on termination, so plugins can now run their Teardown method successfully again

4.1.0

ImageMagick fixes

Fixed

  • Concurrent requests to non-JP2 images (using the ImageMagick plugin) no longer crash
  • Quieter logging in the image magick decoder plugin (debug level instead of info and warning)

Migration

  • To fix the ImageMagick oddities, there are minor incompatibilities. If for some bizarre reason you were using src/plugins/imagick-decoder/Image's Image() or CleanupResources() functions, you can no longer do so. Those functions should never have been exported. This violates semver, I'm aware, but (a) it's a plugin, (b) it's a type that's only exposed because it's a plugin, not because it's meant to be used directly, and (c) it has basically no value outside of the RAIS codebase. I think the risk of this breaking others' code is zero. Still, I'm not super happy to do this.

4.0.2

v4.0.2 fixes a Catalina build bug and some minor issues

Fixed

  • MacOS Catalina build problem fixed
  • Images that aren't tiled no longer report a single tile. Though technically somewhat true, it confuses IIIF clients (such as Open Seadragon) in some cases.
  • Deploy script works again

Changed

  • Docker builds no longer namespace the build images, since those aren't generally useful to publish

4.0.1

v4.0.1 fixes some minor issues

Fixed

  • The TilePath configuration setting is now properly enforced (it was allowed to be empty, but RAIS can't find file-based images without a valid tile path)
  • The main Docker image is now based on the golang image, meaning new builds will be compiled with the latest Go release rather than whatever's specified in the Dockerfile
  • Local docker builds are now named more consistently with dockerhub images

4.0.0

v4.0.0 makes several major changes that significantly affect backward-compatibility for some users. 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
  • A new setting, SchemeMap, which can be used to create a fake scheme for IIIF ids. See rais-example.toml or Configuration for details.

Changed

  • There is no longer a separate S3 plugin. RAIS now supports S3 by default, simply by using a properly-constructed canonical S3 URL
  • Speaking of which, S3 URLs now match AWS's command-line tools: s3://bucket/prefix/key
    • This is 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
  • RAIS now treats all IIIF ids as a URL to an image. This is transparent for people strictly using the filesystem (RAIS converts path-only data to a "file://" URL under the hood), but can be useful to understand when switching to something like S3 storage. See IIIF IDs for more information.

Removed

  • The IDToPath plugin hook has been removed and has not been replaced with anything equivalent yet; it was too tied to the idea of serving local filesystem images only. Some sort of ID-to-URL plugin hook is anticipated soon, however.
  • The S3 plugin has been removed - its "download and serve" approach was too slow for most situations compared to streaming pieces of a JP2 as needed. As noted above, RAIS now supports S3 without a plugin, but it doesn't download files locally anymore.
  • The "external images" plugin has been removed - it's insecure, it's poor code, and now that there are real plugins included, it's not worth maintaining even as an example.
  • 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

  • Settings:
    • IIIFURL has been split into IIIFBaseURL and IIIFWebPath. Using the Historic Oregon Newspapers as an example, our IIIFURL used to be https://oregonnews.uoregon.edu/iiif/images, so we now have the following two declarations:
      • IIIFBaseURL = "https://oregonnews.uoregon.edu"
      • IIIFWebPath = "/images/iiif"
    • Instead of setting IIIFURL, you may be able to let RAIS infer the URL (see On-Inferring-BaseURL for details)
    • As usual, check out rais-example.toml for all possible settings
    • IIIFWebPath defaults to /iiif if you don't want to set it
  • If you were using S3 assets:
    • You'll need to adjust your URLs to use the canonical S3 format, e.g., s3://bucket/prefix/key rather than s3:prefix/key.
    • You no longer need (or can use) the S3 plugin: s3 ids are supported out of the box now, and are streamed from the object store, not copied locally
    • New settings are needed to make RAIS talk to cloud services in a more consistent manner. See the "Object Stores" section of our Configuration documentation.
  • Any plugins which register decoders will need to be rewritten. See Plugins for details about how to define and register a Decoder.
  • If you relied on the external images plugin for anything critical, you will have to build your own version of it using the Streamer interfaces (see Plugins). This plugin was insecure, and changes to RAIS meant it would need to be rewritten as a Streamer, which wasn't worth the effort for a plugin that nobody should have used to begin with.
  • If you were relying on the IDToPath plugin hook, there is no migration path currently, and an older version of RAIS must be used
    • The new SchemeMap config setting may be useful if you only needed simple transformations of the id

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/main/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.
  • 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

Major changes:

  • Properly detects resolution levels in JP2 files, and reports scale factors accordingly
  • Properly detects tile width and height, eliminating the need for manually specifying tiles on the command line
  • Optionally caches data for info.json responses
  • Adds the ability to override the IIIF info.json response per image
  • Allows specifying configuration via /etc/rais.toml (see the rais-example.toml file in the repository)
  • Allows limiting RAIS features via a IIIF capabilities file (see the cap-max.toml and cap-level0.toml files for examples)

Back-end improvements:

  • Fixes init scripts for RHEL 6 users
  • Uses Go 1.6 for the Docker build
  • The build system now uses gb
  • Visiting the server URL + "/version" will report the current version of RAIS

Release 2.5

  • Adds docker support for production and development
  • Removes the test which pulled huge JP2s from an external site

Release 2.4

  • Improves JP2 library detection when building with -tags jp2

Release 2.3

  • Fixes HUGE memory leak when handling pyramidal TIFFs

Release 2.2

  • Fixes bug with IIIF requests on non-JP2 sources

Release 2.1

  • Adds ImageMagick bindings for significantly faster TIFF decoding
  • Makes JP2 support optional, off by default
  • Allows chronam handler to use non-JP2 files
  • Fixes a minor memory leak
  • Removes annoying JP2 logging
  • Makes it easier to register different backends for various image types

Release 2.0

  • Adds TIFF, JPG, PNG, and GIF support for source images (instead of just JP2)
  • Adds PNG, GIF, and TIFF to output encoding options (instead of just JPG)
  • Adds grayscale and bitonal ouput
  • Adds force-resize and best-fit-resize options
  • Adds mirroring support
  • Dynamically determines compliance level for writing out info.json
  • Removes legacy "info" handler
  • Removes JP2 Dimensions() functionality (use GetWidth and GetHeight now)
  • Now IIIF level 2 compliant
  • Lots of formatting and lint fixes, and better testing

Release 1.0

  • Initial stable release under the RAIS name
  • Initial stable release of IIIF features
Clone this wiki locally