On Inferring BaseURL

On Inferring the Base URL

Can RAIS infer your site's base URL? The answer, unfortunately, depends on your particular setup.

First and foremost, if you use a non-standard port, then no. You'll have to set IIIFBaseURL manually, e.g., IIIFBaseURL = http://staging.mysite.edu:12415. Standard ports are 80 for http and 443 for https.

RAIS is typically proxied from a IIIF-enabled application, not exposed directly to the Internet. This allows a site, like an Open ONI instance, to dispatch requests to ONI or RAIS depending on the request. For instance, Historic Oregon News, running Open ONI, sits behind an Apache proxy. Most requests to https://oregonnews.uoregon.edu just pass through to the Open ONI software. But any starting with /images/iiif are seen by Apache as a RAIS request, and are therefore sent to the RAIS server. RAIS itself cannot be reached directly

• only certain "special" URLs are forwarded by Apache.

By default, many proxies do not give the proxied applications a full set of information to know where the request actually came from. For example, if you request https://oregonnews.uoregon.edu/images/iiif/foo.jp2/info.json, Apache knows what hostname, port, and path you're requesting, as well as things like your IP address, the port the request is made on, etc. But once the request is forwarded, RAIS only knows the path, /images/iiif/foo.jp2/info.json. And it only knows that Apache made the request; your IP and other data is not sent along. RAIS returns its response to Apache, since it doesn't know about you, and Apache then sends it to your browser.

When an info.json file is requested, which happens by all IIIF viewers, RAIS has to construct the full URL to the image - despite the fact that the URL was already given to the IIIF viewer. This is just part of the IIIF spec, and unfortunately there's no easy way around it while conforming to the IIIF spec. But without the hostname (and possibly port), RAIS can't actually return a full URL - again, it knows only that somebody wants /images/iiif/foo.jp2/info.json.

Setting IIIFBaseURL solves this very nicely, but requires an extra configuration setting, and can become a little annoying if you have multiple environments running RAIS (development, staging, and production all have to be set up differently).

However, starting from RAIS 4.0, proxies can set headers so RAIS will get the information the proxies were given, and can then construct full URLs properly. You can look at our sample nginx config in the docker demo docker/nginx.conf to see how this works in nginx, but all headers RAIS respects are listed below:

• X-Forwarded-Host tells RAIS to use this value in place of the hostname. For us, this would be oregonnews.uoregon.edu
• X-Forwarded-Proto replaces the protocol of the request, e.g., https

---

If RAIS can't be given the information it needs (e.g., the port isn't standard, or a proxy is used which won't send the headers automatically), or you just find it easier to be explicit, set IIIFBaseURL directly. Just make sure you remember that this setting is mandatory for your environment.