# Introduction

The Madison Digital Image Database is a freely distributed, open source web application originally developed at James Madison University and now supported mainly by vrcHost LLC. MDID is a digital media management system with sophisticated tools for discovering, aggregating, and presenting digital media in a wide variety of learning spaces.The project started in 1997 in response to increasing curriculum requirements within JMU's School of Art and Art History and evolved over time into a cross-disciplinary instructional application used at several hundred institutions in the United States and around the world.

Version 3 of MDID is completely redesigned and re-coded from the ground up in order to meet emerging user expectations, such as support for audio and video, integration with Blackboard and other web sites, more flexible metadata structures, a richer and more robust discovery interface, granular access controls, PowerPoint compatibility, shorter development cycles, support for composite objects, and novel presentation mechanisms. It runs on most operating systems. MDID3 ships with a companion application, the MediaViewer. The MediaViewer is used primarily in mediated classrooms to display slideshows (groups of ordered images). It features intuitive zoom and pan controls, intelligent navigation, image caching, catalog data display, and support for dual monitors.

It is freely available for download from the Internet under an open source license.


# Documentation

At this time, there is only limited documentation available. The following documents were retrieved from the original MDID support site at James Madison University.

[MDID Curation](https://s3.amazonaws.com/mdid/mdid.org/MDID+Curation.pdf)

[MDID Training](https://s3.amazonaws.com/mdid/mdid.org/MDID3+Training.pdf)

[MDID Help](https://s3.amazonaws.com/mdid/mdid.org/MDID3+Help.pdf)


# Presentations

A number of presentations about MDID have been made available on SlideShare:

[MDID presentations on SlideShare](https://www.slideshare.net/search/slideshow?q=mdid)


# Installation

These are the installation steps for MDID 3.7. Instructions for each release are included with each package in the `docs/install` folder.

## Installation on Ubuntu Linux

The following instructions are for Ubuntu Linux 22.04 LTS, but should work with minor changes on other distributions as well.

Unless noted otherwise, all commands should be run as `root`.

### Server Preparation

#### Packages

```
apt-get update
apt-get install -y python3 python3-pip libjpeg-dev libfreetype6-dev \
    nginx mysql-server libmysqlclient-dev python3-dev \
    libldap2-dev libsasl2-dev unixodbc-dev memcached \
    rabbitmq-server supervisor ffmpeg openjdk-11-jre-headless \
    python3-virtualenv libssl-dev poppler-utils
```

#### Enable nginx

```
rm -f /etc/nginx/sites-enabled/default
update-rc.d nginx enable
service nginx start
```

#### Create user account

```
adduser --disabled-password mdid
mkdir -p /opt/mdid
chown mdid:mdid /opt/mdid
```

#### Create virtual environment

```
sudo -iu mdid  # switch to mdid user
cd /opt/mdid  # or another directory of your choice
python3 -m virtualenv -p python3 venv
source venv/bin/activate
pip install mdid
# or to install test version:
# pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple mdid
mdid init
```

#### Install Solr

MDID currently requires Solr 8; you may have to adjust the exact version as available when running the following commands. Please note that you want to use at least version 8.11.1 of Solr to avoid the Log4j vulnerability.

```
mkdir -p /opt/solr_install /opt/solr
cd /opt/solr_install
wget https://archive.apache.org/dist/lucene/solr/8.11.1/solr-8.11.1.tgz
tar xzf solr-8.11.1.tgz solr-8.11.1/bin/install_solr_service.sh --strip-components=2
./install_solr_service.sh solr-8.11.1.tgz -f -d /opt/solr -i /opt/solr_install -n
sed -i -E 's/#SOLR_HEAP="512m"/SOLR_HEAP="2048m"/' /etc/default/solr.in.sh
ln -s /opt/mdid/var/solr /opt/solr/data/mdid
chown -R solr:solr /opt/solr/data/mdid/
service solr start
```

#### Configure MySQL

```
ln -s /opt/mdid/service-config/mysql /etc/mysql/mysql.conf.d/mdid.cnf
service mysql restart
```

#### Create database

Create a new MySQL database or restore an existing database from a previous MDID3 installation. Adjust the database name, user name, and password as needed:

```
mysql -u root
create database mdid character set utf8;
create user mdid@localhost identified by 'rooibos';
grant all privileges on mdid.* to mdid@localhost;
\q
```

#### Configure MDID

Edit `/opt/mdid/config/settings.py` and change the database and other settings as needed.

Also, if possible, change the asterisk in `ALLOWED_HOSTS` to your server host name, if you know it, for example `['mdid.yourschool.edu']`.

Run the following command to initialize static files and migrate the database to the latest version:

```
sudo -iu mdid  # switch to mdid user
source /opt/mdid/venv/bin/activate
mdid collectstatic
mdid migrate
```

#### Configure nginx

```
ln -s /opt/mdid/service-config/nginx /etc/nginx/sites-enabled/mdid
```

Place your server SSL certificate files named `server.key` and `server.crt` in `/opt/mdid/ssl`, or generate some sample self-signed certificates for temporary use:

```
openssl genrsa -out /opt/mdid/ssl/server.key
openssl req -new -key /opt/mdid/ssl/server.key -out /opt/mdid/ssl/server.csr
openssl x509 -req -days 365 -in /opt/mdid/ssl/server.csr -signkey /opt/mdid/ssl/server.key -out /opt/mdid/ssl/server.crt
```

#### Configure crontab

```
sudo -iu mdid  # switch to mdid user
crontab /opt/mdid/service-config/crontab
```

#### Configure supervisor

```
ln -s /opt/mdid/service-config/supervisor /etc/supervisor/conf.d/mdid.conf
supervisorctl reload
```

### Shibboleth support

To use Shibboleth for user authentication, follow the steps below to modify your working MDID installation to connect to your IdP.

#### Install additional packages

```
apt-get install apache2 apache2-utils libapache2-mod-shib libshibsp-dev \
    libshibsp-doc
```

#### Configure Shibboleth

Configure your Shibboleth SP in `/etc/shibboleth/shibboleth2.xml`, including setting the application ID to `mdid`.

Make sure to add a key or generate a new key using `shib-keygen`.

Uncomment the attributes you want to use in `attribute-map.xml`.

#### Configure apache

Modify `/etc/apache2/ports.conf` and change all instances of port 80 to port 8100.

Enable apache modules and configure site:

```
a2enmod rewrite
a2enmod proxy
a2enmod proxy_http
a2enmod headers
ln -s -f /etc/apache2/mods-available/shib2.load /etc/apache2/mods-enabled/shib2.load
ln -s /opt/mdid/service-config/apache /etc/apache2/sites-enabled/999-mdid.conf
apachectl restart
```

#### Configure nginx

In your nginx site file `/opt/mdid/service-config/nginx`, change the port number in the `proxy_pass` statement from 8001 to 8100.

#### Configure MDID

Add the following settings to your MDID configuration file at `/opt/mdid/config/settings.py`, changing attribute names as required:

```
SHIB_ENABLED = True
SHIB_ATTRIBUTE_MAP = {
    "HTTP_MAIL": (True, "mail"),
    "HTTP_GIVENNAME": (False, "givenName"),
    "HTTP_SN": (False, "sn"),
    "HTTP_USERNAME": (True, "username"),
}
SHIB_USERNAME = "username"
SHIB_EMAIL = "mail"
SHIB_FIRST_NAME = "givenName"
SHIB_LAST_NAME = "sn"
```

By default MDID will not show a logout link, but if your Shibboleth setup allows logouts, you can configure the logout URL with

```
SHIB_LOGOUT_URL = "http://link.to.your.shibboleth.logout"
```

#### Restart all services

```
service shibd restart
apache2ctl graceful
nginx -s reload
supervisorctl restart mdid:*
```


# Upgrading

## Upgrading to MDID 3.7 from earlier versions of MDID 3

Due to the new method of installing MDID 3.6 and later it is strongly recommended to perform a new installation and then put the database and images in place.

* Follow the installation steps outlined for your operating system
* Change the database settings in `config/settings.py` to point to your existing database
* Run `mdid migrate` to migrate the database
* Run `mdid solr reindex` to refresh the full-text index

## Upgrading from MDID2

* Perform a new installation with a blank database.
* Copy the `config.xml` file from your MDID2 installation to a place accessible from the new installation.
* If necessary, adjust the `<database>` section in the `config.xml` file so that it can be used to connect to the database from the new installation.
* Run `mdid mdid2migrate path/to/config.xml`
* Copy the full-size images from the MDID2 installation to a place accessible to the new installation.
* In MDID3, under Management>Manage Storages, fix the paths to the different storage directories.
* Run a full re-index with `mdid solr reindex`.


# Downloads

## MDID 3.6

Starting with MDID 3.6, a package is [distributed via PyPI](https://pypi.org/project/mdid/). You can find the latest versions there and install them with `pip`.

## Older Versions

Selected releases are listed on this page. You can find a list of all [available builds](https://s3.amazonaws.com/vrchost-jenkins/index.html) or go directly to the [source repository](https://github.com/vrchost/rooibos).

### MDID 3.5

This is the first version running on Python 3/Django 1.11. Since this new platform includes significant changes, please report any issues that may occur.

Latest update (as of 2021-11-14) rooibos-master-v3.5.0-90-g7bce8a60-build21 as [.tar.gz](https://s3.amazonaws.com/vrchost-jenkins/builds/master/appveyor-build/rooibos-master-v3.5.0-90-g7bce8a60-build21.tar.gz) and [.zip](https://s3.amazonaws.com/vrchost-jenkins/builds/master/appveyor-build/rooibos-master-v3.5.0-90-g7bce8a60-build21.zip)

(For possible later updates, go to [available builds](https://s3.amazonaws.com/vrchost-jenkins/index.html))

### MDID 3.4

For Python 2.7. Last version to support this deprecated version of Python.

Latest update (as of 2020-08-18) rooibos-3.4.x-v3.4.0-10-g405df40-build167 as [.tar.gz](https://s3.amazonaws.com/vrchost-jenkins/builds/3.4.x/rooibos-3.4.x-v3.4.0-10-g405df40-build167.tar.gz) and [.zip](https://s3.amazonaws.com/vrchost-jenkins/builds/3.4.x/rooibos-3.4.x-v3.4.0-10-g405df40-build167.zip)

(For possible later updates, go to [available builds](https://s3.amazonaws.com/vrchost-jenkins/index.html))