Issues with installing IIIF: what worked for me.

Issues with installing IIIF: what worked for me.

Posted on: Wed, 10/14/2020 - 22:58 By: Matt

I recently had my IIIF server (a Loris installation) collapse on me and quit working properly. It was no longer serving the pages from the manifest as expected, but was serving the first two properly and then just displaying the first image in the manifest for the rest of the links. I suspect that in reality it was really doing that for all of the pages, but I had cached images that I was seeing in my browser so they sometimes looked correct. In any event, the server needed to be repaired or replaced.  After messing around with settings for a couple of days I decided discretion was the better part of valor and that I would reinstall the server from scratch since all it does is serve pages for my Lydgate archive.  In getting ready to do so it became really apparent that despite some more recent additions the instructions on the page hadn’t really been updated since Ubuntu 16.04.  Ubuntu 16.04 was released in 2016, and it becomes obsolete in April of 2021—which is only a few months away from when I’m writing this. So it is really likely that people will not be able to install or reinstall Loris using the set of instructions provided without some extra work on their parts.  Furthermore, in attempting to follow those instructions I found out that there were some changes in how the software was intended to be deployed that had not been documented. Luckily, the way I found this out was by asking a question on the github page and engaging in a conversation with the developers.  This netted me a version that ended up working for me, but I thought it might be useful to document the process I had to go through to install for others. My plan is to do so by using the framework they lay out in the instructions on the github page, and then mention where my experience required me to make some changes or additions in order to get things to work right. As such, these aren't intended to be stand-alone instructions, but to be something you reference in tandem with the existing instructions at the page above.

One final note before I jump in—I run my sites as simply as possible, trusting that to do so will help make the networking bulletproof and unlikely to cause time-consuming problems. This means that if I had my druthers I’d run everything on bare metal servers and try to avoid virtualization. I can’t do that with the Loris IIIF server, however, so I’m running a DigitalOcean droplet. I didn’t see the point of running another virtualization in the droplet, so I am running a basic Apache server rather than a Docker container.  Because of that some of what I needed to do and talk about below may differ from what you will need if you plan to run it in Docker. I think the NGINX installation may have some of the same issues up until the configuration stage, so there it may prove more useful. In any event, I will not be including the NGINX and Docker sections when I note changes as I didn’t use them.

Ubuntu version and clone Loris

Before you do anything, there is a big problem with versions of Ubuntu later than 18.04 and Python at the time of this post. Python 3 (more on this below) needs a Debian package for the foreign function interface (the bit that allows code written in one language to call code written in another), and it expects libffi6. Ubuntu 20.04, however, replaces libffi6 with libffi7, and the Loris installation will throw an error at you if you attempt to run it with the more recent version of the package. There are fixes for this online, but the fixes seem really dodgy to me. So your easiest option at this point—at least until the version of Python Ubuntu uses fixes the issue—is to install Ubuntu 18.04 and use that as the basis for your Loris server. That will get you a supported server through April of 2023 rather than April of 2021. I expect this issue with Python to be fixed relatively quickly, though, so just doublecheck the version of libffi Python is looking for before you install the version of the OS you plan to work with and if they’ve corrected the problem install the latest version of the OS.

The other thing you need to do that the instructions don’t mention is copy the Loris folders to your machine. At least right now, you need to use the version of Loris in the “development” branch on github, so it is probably easier to just use git to clone the folders onto your system rather than downloading a zip file. You can do that with this command:

git clone -b development

Installing Dependencies

This was by far the most time-consuming part of the entire installation process in terms of actually setting up the server for me, and the impetus for writing this post. The instructions assume that you will be running things in Python 2.7, but Python 2 is actually a deprecated platform and everything should be running in Python 3. The Python 3 versions of some of the packages have changed, and you have to hunt those down. So where the instructions say sudo apt-get install python-pip python-setuptools you need to type sudo apt install python3-pip python3-setuptools (Ubuntu 16.04+ has reduced the apt-get command to just apt).

Install Pillow

Next, you’ll need to install Pillow following the directions provided by the developers, but if you try to use the three uninstall commands you’ll find you’re getting a “command not found” error.  With Python 3, pip requires the command pip3, so you’ll need to type

sudo pip3 uninstall PIL
sudo pip3 uninstall Pillow
sudo apt purge python3-imaging

You may find that you're getting an error when you do so. That's because it's really not best practice to use sudo with pip, but the instructions do it so I'm assuming there may be something in the code that necessitates sudo. Get around this by typing sudo -H rather than just sudo if you do get an error message.

Install Dependencies

The dependencies in the list provided that relate to Python have changed, and while the instructions acknowledge that the versions may be different it is probably easier to just provide you with the versions I used:

sudo apt install libjpeg-turbo8-dev libfreetype6-dev zlib1g-dev liblcms2-dev liblcms2-utils libtiff5-dev python3-dev libwebp-dev apache2 libapache2-mod-wsgi-py3

Then just install Pillow, again using pip3:

sudo pip3 install Pillow

Also, if you do intend to work on the source code you’ll want to install the four packages the instructions mention as well:

sudo pip3 install configobj
sudo pip3 install requests
sudo pip3 install mock
sudo pip3 install responses

Configuration Options

The new version places the loris2.conf file in /loris/data rather than /etc, so make sure you go there to make your changes.

Cache Maintenance

There’s no real difference between what I needed to do and what the instructions lay out, so go ahead and follow what you see in the instructions if you need to run any of the cache scripts.

Resolver Implementation

Again, the Resolver implementation isn’t going to be that much different than that provided by the instructions.  The biggest thing is to remember that loris2.conf is located in /loris/data.

I wanted to be able to point to uri’s constructed by my archive, so my resolver section is as follows:

impl = 'loris.resolver.SimpleHTTPResolver'

If you don’t want to point to uri’s, you may want to change that to something that works for what you intend your implementation to be. The section in the instructions gives several possible options.


There are a few things you need to do before you run The first is to create the loris user the system requires (either loris or another username, as the instructions note):

sudo adduser loris

You’ll also need to run the script, which is located in /bin. When you do so, however, you may find that you get an error. This is because Python's executable installed in the /usr/bin/python3 folder rather than /usr/bin/python. This is a relatively easy fix:

sudo ln -s /usr/bin/python3 /usr/bin/python

Once you’ve done this, first run Open the /bin folder and type:


This should set up the folders for Loris, and a quick check to make sure the script ran is to type ls -l /var/www/loris2. If you get an error message the script has not worked properly. If you get a folder called icons, a file named index.txt, and most importantly a file named loris2.wsgi you are set.

Finally, you just need to run from the root folder:

./ install

Next steps

From here, you should be set as far as the installation goes and can work with the instructions from the Apache Deployment Notes page. The apache2 and libapache2-mod-wsgi packages mentioned here should already be installed, but if you want to doublecheck you’ll need to update libapache2-mod-wsgi to libapache2-mod-wsgi-py3. So type the following:

sudo apt install apache2 libapache2-mod-wsgi-py3

One final note: if you don’t tend to do a lot of work with Apache config files you may wonder where to put the information they note you need to add to the configuration file. In my implementation I put them at the bottom of the <VirtualHost *:80> section, just above the </VirtualHost> closing tag.

I hope this helps you get IIIF up and running without any real hassles, but if you have any questions I am more than happy to help. Just contact me via the email address on my CV. You’d be better off, though, contacting the developers directly. Not only are they very helpful and responsive (not always a surety when dealing with open-source developers) making them aware of your issues can help them to know what directions the tool needs to be taken in in future development.

Add new comment

The content of this field is kept private and will not be shown publicly.

Restricted HTML

  • Allowed HTML tags: <a href hreflang> <em> <strong> <cite> <blockquote cite> <code> <ul type> <ol start type> <li> <dl> <dt> <dd> <h2 id> <h3 id> <h4 id> <h5 id> <h6 id>
  • Lines and paragraphs break automatically.
  • Web page addresses and email addresses turn into links automatically.
Article Type