h1. IIIF Image API Server

"Image API Server":https://guides.iiif.io/guide_for_implementers/#image-api is responsible to deliver the images. 

Since OpenAtlas relies on Debian packages, we recommend to use "IIPImage":https://iipimage.sourceforge.io/ as "IIIF Image API":https://iiif.io/get-started/image-servers/. But any other working "IIIF Image API Server":https://github.com/IIIF/awesome-iiif#image-servers can be used, if it can handle "Tiled Multi-Resolution TIFF":https://iipimage.sourceforge.io/documentation/images and uses a folder to handle the images.

For installation of the IIPImage server see install notes of OpenAtlas. 

h3. Installing Cantaloupe 5 on Debian

# Check if Java 11 is installed, if not install *default-jre*
<pre><code class="shell">
java -version
-bash: java: command not found
sudo apt install default-jre
</code></pre>
# Download cantaloupe /var/www/ and extract it, and rename it for easier use.
<pre><code class="shell">
cd /var/www
wget https://github.com/cantaloupe-project/cantaloupe/releases/download/v5.0.5/cantaloupe-5.0.5.zip
7z x cantaloupe-5.0.5.zip
mv cantaloupe-5.0.5 cantaloupe
</code></pre>
# Make a copy of *cantaloupe.properties.sample* without *.sample* and open it.
<pre><code class="shell">
cd cantaloupe
cp cantaloupe.properties.sample cantaloupe.properties
vim cantaloupe.properties
</code></pre>
# Set FilesystemSource.BasicLookupStrategy.path_prefix to the path, where the images are.
<pre><code class="shell">
FilesystemSource.BasicLookupStrategy.path_prefix = /var/www/iiif/
</code></pre>
# Additionally you can set "endpoint.admin.enabled" to true, to get access to the config via the browser.
<pre><code class="shell">
# Enables the Control Panel, at /admin.
endpoint.admin.enabled = true
endpoint.admin.username = admin
endpoint.admin.secret = password
</code></pre>

h4. Apache config 

# Enable headers and proxy_http
<pre><code class="shell">
sudo a2enmod headers
sudo a2enmod proxy_http
</code></pre>
# Create a new Apache2 config and enable the site. You can either use an own domain or an existing one with the port 8182(http)/8183(https)
<pre><code class="shell">
sudo vim /etc/apache2/sites-available/cantaloupe.conf
</code></pre>
<pre><code class="shell">
<VirtualHost *:80>
  # X-Forwarded-Host will be set automatically by the web server.
  RequestHeader set X-Forwarded-Proto "https"
  RequestHeader set X-Forwarded-Port "80"
  RequestHeader set X-Forwarded-Path /

  ServerName apache-server
  AllowEncodedSlashes NoDecode
  ErrorLog        /var/log/apache2/cantaloupe_error.log
  CustomLog       /var/log/apache2/cantaloupe_access.log combined

  ProxyPass / http:// YOUR-DOMAIN.at:8182/ nocanon
  ProxyPassReverse / http://YOUR-DOMAIN.at:8182/
  ProxyPassReverseCookieDomain YOUR-DOMAIN.at apache-server
  ProxyPreserveHost on
</VirtualHost>
</code></pre>
<pre><code class="shell">
sudo a2ensite cantaloupe.conf
sudo service apache2 restart
</code></pre>


# If you use certbot, you can convert the certificate to an .pfx file. First create a folder in /etc/:
<pre>
sudo mkdir /etc/cantaloupe/
openssl pkcs12 -export -out /etc/cantaloupe/ssl-certificate.pfx -inkey /etc/letsencrypt/live/YOUR-DOMAIN.at/privkey.pem -in /etc/letsencrypt/live/YOUR-DOMAIN.at/cert.pem -certfile /etc/letsencrypt/live/YOUR-DOMAIN.at/fullchain.pem
sudo chown bkoschicek:www-data /etc/cantaloupe/ssl-certificate.pfx
</pre>
# Change the settings either at the admin interface or config:
<pre><code class="shell">
# !! Configures the HTTPS server. (Standalone mode only.)
https.enabled = true
https.host = 0.0.0.0
https.port = 8183

# !! Available values are `JKS` and `PKCS12`. (Standalone mode only.)
https.key_store_type = PKCS12
https.key_store_password = PASSWORD
https.key_store_path = /etc/cantaloupe/ssl-certificate.pfx
https.key_password = PASSWORD
</code></pre>
# Again restart Apache, and you can visit cantaloupe with http://YOUR-DOMAIN.at:8183

h4. Cantaloupe as Debian Service

# Open a terminal and create a systemd service unit file for Cantaloupe. You can name the file cantaloupe.service:
<pre><code class="shell">
sudo vim /etc/systemd/system/cantaloupe.service
</code></pre>

# Add the following content to the cantaloupe.service file:
<pre>
[Unit]
Description=Cantaloupe Image Server
After=network.target

[Service]
ExecStart=/usr/bin/java -Dcantaloupe.config=/var/www/cantaloupe/cantaloupe.properties -Xmx2g -jar /var/www/cantaloupe/cantaloupe-5.0.5.jar
Restart=on-failure
User=root
WorkingDirectory=/var/www/cantaloupe/

[Install]
WantedBy=multi-user.target
</pre>
# Enable and start the Cantaloupe Service:
<pre><code class="shell">
sudo systemctl daemon-reload
sudo systemctl enable cantaloupe.service
sudo systemctl start cantaloupe.service
</code></pre>


h3. Installation on Windows (development only)

Since IIPServer is not so easy to install on Windows, and we don't really need it for development, I suggest to work with "Cantaloupe":https://cantaloupe-project.github.io/ to get an on-the-fly IIIF server. 

* Install vips and restart your PC (vips.exe should be in your PATH variable) 
<pre>
scoop install main/libvips
</pre>

* "Download Cantaloup":https://github.com/cantaloupe-project/cantaloupe/releases/download/v5.0.5/cantaloupe-5.0.5.zip
* Extract it somewhere easy to find, e.g. *C:\cantaloupe-5.0.5*
* Copy C:\cantaloupe-5.0.5\cantaloupe.properties.sample and rename it to _cantaloupe.properties_
* Open _cantaloupe.properties_ and add a path where the image files are to *FilesystemSource.BasicLookupStrategy.path_prefix* e.g. 
<pre>
FilesystemSource.BasicLookupStrategy.path_prefix = C:\Users\bkoschicek\PycharmProjects\iiif\
</pre>
* Open "GitBash"https://gitforwindows.org/ (or try to get it working in PowerShell), navigate to the root folder of *Cantaloupe* and start it with (leave the bash open!)
<pre>
java -Dcantaloupe.config=C:/cantaloupe-5.0.5/cantaloupe.properties -Xmx2g -jar cantaloupe-5.0.5.jar
</pre>
* If a image is in the give folder (e.g. _C:\Users\bkoschicek\PycharmProjects\iiif\_) you can view the info.json with:
<pre>
http://localhost:8182/iiif/2/image.jpg/info.json
</pre>
and the image with
<pre>
http://localhost:8182/iiif/2/image.jpg/full/full/0/default.jpg
</pre>