Skip to content

Configuration

Jump to bottom
Jeremy Echols edited this page Aug 10, 2020 · 5 revisions

RAIS Configuration

Generally speaking, it's best to read over the entire rais-example.toml file, as configuration is documented there, and there's no need to worry about keeping documentation in sync.

Much of the configuration won't need to be used, however, so the more common configs are documented here. Always refer to the TOML file, however, as it will always contain the most up-to-date information.

Configuration Approaches

The easiest option is simply copying the example file to /etc/rais.toml and then editing it as needed. However, all settings can also be specified in environment variables, making RAIS easy to configure in a more cloud-centric setup. All environment variables will start with RAIS_ (note the trailing underscore) and then contain the TOML file's value in all caps. e.g., Address can be configured via RAIS_ADDRESS.

Settings

Basic settings

Most RAIS settings have reasonable defaults. The most important settings which you should know and/or alter follow.

  • Address specifies the IP and port RAIS listens on, and defaults to any IP the server uses and port 12415. This is where an Apache / nginx proxy would have to point, e.g., proxy_pass http://localhost:12415;
  • TilePath specifies the base path on disk where images reside, and defaults to /var/local/images. The files here must be readable by the RAIS process owner.

Host and path

  • IIIFBaseURL has no default, as RAIS tries to infer the site's Base URL. If set, this overrides the base URL RAIS reports when an info.json request is made. If this is set, it must be set to a host (and optionally port) which reaches RAIS from the outside world. e.g., if RAIS is listening on localhost:12415, but nginx proxies oregonnews.uoregon.edu/iiif to RAIS, oregonnews.uoregon.edu is the base URL.
  • IIIFWebPath specifies the base path RAIS handles, and defaults to /iiif. This again must be set to the path that reaches RAIS from the outside world, not necessarily what RAIS internally listens on.

RAIS can often infer the host and port, but not the path. If you need a path other than /iiif, you must set IIIFWebPath in rais.toml, RAIS_IIIFWEBPATH in the environment, or --iiif-web-path on the command line.

Inferring the host and port is typically doable, but often requires a proxy (nginx, Apache, HAProxy, etc.) to set special headers which aren't set by default. See On Inferring BaseURL.

If IIIFBaseURL is set to https://oregonnews.uoregon.edu:8443 and IIIFWebPath is left at its default, then image requests from a client (like OpenSeadragon) will look something like this: https://oregonnews.uoregon.edu:8443/iiif/someimage.jp2/full/330,/0/default.jpg.

Your server must be configured such that this URL gets to RAIS. RAIS doesn't need to be listening on port 8443; it just needs to have the request make its way to RAIS eventually, via proxies or otherwise.

Object Stores

To use S3, you must have a working AWS environment, which means the following environment variables must be set:

  • AWS_ACCESS_KEY_ID, your access key
  • AWS_SECRET_ACCESS_KEY, your secret key
  • AWS_REGION, e.g., us-west-2
  • AWS_SESSION_TOKEN, optional, but some setups may need this

You may also need to set the following if you're using an S3-compatible backend that isn't AWS:

  • RAIS_S3_ENDPOINT, e.g., minio.uoregon.edu:9000
  • RAIS_S3_DISABLESSL, "true" to use a backend that doesn't have/need SSL
  • RAIS_S3_FORCEPATHSTYLE, "true" to use the "path" style, often required for custom backends like minio

Using other object stores is possible, but untested. We use gocloud.dev for our object store "engine", and it has some documentation on setting up your environment for different providers at https://gocloud.dev/howto/blob.

Note: object stores are inherently slower than local filesystems. You will want to verify that the access speeds are acceptable before committing to this course. You should also consider using the built-in tile Caching, or using a dedicated cache that sits in front of RAIS, such as varnish.

Scheme Map

This is a powerful setting that earns its own place in this document.

(Note that SchemeMap is documented in great depth in the example TOML file, too.)

The SchemeMap setting allows you to create IIIF ids that are completely opaque by turning a fake scheme into a URL prefix. For instance, say you want to showcase images that all live in S3 in a path named "8675309", but you don't want everybody knowing your phone number. Set up a map!

SchemeMap = "imgs=s3://bucket/8675309"

Then an id of imgs://jenny.jp2 will actually map to the URL s3://bucket/8675309/jenny.jp2.

You can have multiple maps if needed, separated by a space:

SchemeMap = "imgs=s3://bucket/8675309 imgs2=gs://bucket/8675309"
Clone this wiki locally