Getting started with IIIF and Omeka S

by Maarten Coonen 2 minute read

In our previous post we described the “NDE Versnellen 2023” project in which we planned to make our Omeka S instance fully NDE compatible by implementing the IIIF-functionality on top of it.

This post presents the results of that project by guiding you through an easy-to-setup Dockerized environment consisting of Omeka S with IIIF preconfigured. We made this Dockerized Omeka S environment freely available under a GPL-3.0 open source license.

Please note that this Dockerized environment was designed for development purposes. We would not recommend production usage in its current state! Read our next post with deployment instructions instead.

Before you start

In order to run our Dockerized Omeka S, you need a system with the following characteristics and software installed.

  • A supported operating system, such as various Linux distros or MacOS. Details on Docker website
  • Docker & Docker Compose
  • Git

Create a working directory

cd ~
mkdir work
cd ~/work

Clone our git repositories

Load our software from the Maastricht University Library GitHub. The steps below are based on this readme and repeated here for convenience.

In order to resolve DNS requests to the local containers, you need to add the following line to your local /etc/hosts file.

127.0.0.1	localhost omeka.local solr.local db.local iipsrv.local cantaloupe.local viewer.local

Download the Omeka S Docker project:

git clone https://github.com/MaastrichtU-Library/omekas-docker.git

Download the Omeka S theme and helper scripts

cd ~/work/omekas-docker/externals
git clone https://github.com/MaastrichtU-Library/omekas-helpers.git
git clone https://github.com/MaastrichtU-Library/omekas-theme-um.git

Set database connection settings

  1. Edit the ~/work/omekas-docker/docker-compose.yml file and enter values for:
     MYSQL_ROOT_PASSWORD:
     MYSQL_DATABASE: 
     MYSQL_USER:
     MYSQL_PASSWORD:
    
  2. Copy the example database config for Omeka S
     cp ~/work/omekas-docker/omeka-s/config/example_database.ini ~/work/omekas-docker/omeka-s/config/database.ini
    
  3. Edit the database.ini file with a text editor and enter the same values for:
     user     = 
     password = 
     dbname   = 
     host     = 
    

Run Omeka S in Docker

Build the Omeka S infra with:

docker compose build

Additionally, to build the external IIIF-tooling, use:

docker compose -f docker-compose-iiif-external.yml build

Run the Omeka S infra with:

docker compose up -d

To run external IIIF-tooling as well, use:

docker compose -f docker-compose-iiif-external.yml up -d

To see logs, use:

docker compose logs -f

There are some manual configuration steps to perform after the Docker containers have started.

When all containers have started, you will find the services at the following URLs:

  • Omeka S: http://omeka.local (usr/pwd: admin@example.org / foobar)
  • mySQL backend: http://db.local
  • Solr backend: http://solr.local
  • IIP IIIF server: http://iipsrv.local
  • Cantaloupe IIIF server: http://cantaloupe.local (usr/pwd: admin / foobar)
  • Mirador external IIIF viewer: http://viewer.local

Well done

If everything worked out, you now have a working Omeka S with IIIF features running locally. Stay tuned for our next post with instructions for production usage.

Maastricht University Library

Maastricht University Library

Library Systems and Development