Installing the IIPImage binaries

The following instructions detail how to install and configure the IIPImage server binary as an fcgi module with either nginx or the popular Apache webserver under Mac OS X 10.9. Even if you are not using OS X, included below are useful default configurations for getting IIPImage up and running with nginx.

This guide assumes you have the Homebrew package manager installed.

Contents Installing IIPImage with NginX Installing IIPImage with Apache

Installing IIPImage with NginX

1. Install nginx and fcgi using your package manager.

    $ brew install nginx fcgi
   

2. We will now download the IIPImage JPEG2000 binaries appropriate for our operating system and move iipsrv.fcgi into an easily accessible location.

   First download and unzip iipsrv-0.9.9-j2k-OSX.zip from https://code.google.com/p/oldmapsonline/downloads/list. Then cd to where you unzipped the images:

    $ cd ~/Downloads/iipsrv-0.9.9-j2k-OSX
    $ mkdir -p /usr/local/share/iipimage
    $ cp iipsrv.fcgi /usr/local/share/iipimage/
   

3. Make a file called iipserver.conf in the sites-available directory within your nginx configuration directory. The default nginx configuration directory when installed with Homebrew is /usr/local/etc/nginx.

    $ cd /usr/local/etc/nginx
    $ mkdir -p sites-available
    $ touch sites-available/iipserver.conf
   

   Use your favorite text editor to insert the following into iipserver.conf:

    upstream iip {
        server unix:/tmp/iipserver.sock fail_timeout=0;
    }
    server {
        listen         8001;
        server_name  localhost;
        root /usr/local/var/www;
        location /fcgi-bin/iipserver.fcgi {
            fastcgi_pass    iip;
            fastcgi_param   PATH_INFO $fastcgi_script_name;
            fastcgi_param   REQUEST_METHOD $request_method;
            fastcgi_param   QUERY_STRING $query_string;
            fastcgi_param   CONTENT_TYPE $content_type;
            fastcgi_param   CONTENT_LENGTH $content_length;
            add_header 'Access-Control-Allow-Origin' '*';
        }
    }
   

4. We now must create a symbolic link to our iipserver.conf from the sites-enabled directory (using an absolute path for the link target is important!):

    $ mkdir sites-enabled
    $ ln -s /usr/local/etc/nginx/sites-available/iipserver.conf /usr/local/etc/nginx/sites-enabled/iipserver.conf
   

5. Now edit the main nginx configuration file at /usr/local/etc/nginx and insert the following (the important bit being the inclusion of the sites-enabled directory):

    worker_processes  1;
    events {
        worker_connections  1024;
    }
    http {
        include       mime.types;
        default_type  application/octet-stream;
        sendfile        on;
        keepalive_timeout  65;
        include /usr/local/etc/nginx/sites-enabled/*.conf;
    }
   

6. We'll be using Supervisor to manage IIPImage. To install Supervisor, run

    $ pip install supervisor
   

   If you do not have pip installed, first install it using $ brew install pip.

   (If running $ supervisorctl returns command not found, you may need to include /usr/local/share/python in your $PATH.)

7. To configure supervisor, we'll be using the default configuration file. The shortcut to create the default configuration is:

    $ echo_supervisord_conf > /usr/local/etc/supervisord.conf
   

   We must replace the last line of the file (the files option of the [include] block) with the following:

    files=/usr/local/etc/supervisor/conf.d/*.conf
   

   Now we need to configure IIPImage to work with supervisor, in /usr/local/etc/supervisor/conf.d/iipserver.conf:

    $ mkdir -p /usr/local/etc/supervisor/conf.d
    $ touch /usr/local/etc/supervisor/conf.d/iipserver.conf
   

   In iipserver.conf, insert the following, replacing YOURUSERNAMEHERE with your short username:

    [fcgi-program:iipserver]
    command=/usr/local/share/iipimage/iipsrv.fcgi
    socket=unix:///tmp/iipserver.sock
    user=YOURUSERNAMEHERE
    autostart=true
    autorestart=unexpected
    redirect_stderr=true
    redirect_stdout=true
   

8. Because the IIPImage binaries point to libraries that are not in their default location, issue the following command to point IIPImage at the fcgi library on our system:

    $ install_name_tool -change /usr/lib/libfcgi.0.dylib /usr/local/lib/libfcgi.0.dylib iipsrv.fcgi
   

   To test that this worked, we can do

    otool -L iipsrv.fcgi
   

9. We can now run our services!

    $ supervisord
    $ nginx
   

In your browser, navigate to http://localhost:8001/fcgi-bin/iipserver.fcgi. You should now see the IIPImage splash page, indicating that the IIPImage server has been successfully installed and configured!

Installing IIPImage with Apache

1. Install mod_fcgi using your package manager.

    $ brew tap homebrew/apache
    $ brew install mod_fastcgi
   

2. We will now download the IIPImage JPEG2000 binaries appropriate for our operating system and move iipsrv.fcgi into an easily accessible location.

   First download and unzip iipsrv-0.9.9-j2k-OSX.zip from https://code.google.com/p/oldmapsonline/downloads/list. Then cd to the location where you downloaded and unzipped the binaries:

    $ cd ~/Downloads/iipsrv-0.9.9-j2k-OSX
    $ sudo mkdir -p /Library/WebServer/Documents/fcgi-bin/
    $ sudo cp iipsrv.fcgi /Library/WebServer/Documents/fcgi-bin/
   

3. We will now configure Apache to talk to IIPImage. The default location for the main configuration file under OS X's Apache installation is /etc/apache2/httpd.conf.

   Use your favorite text editor to open /etc/apache2/httpd.conf.

   First, we'll include mod_fcgi into our Apache configuration. You should see a whole lot of LoadModule lines around line 55 of your config file. At the end of the block of LoadModule lines, insert the following (being sure that the path to mod_fastcgi.so as installed by the package manager is valid):

    LoadModule fastcgi_module /usr/local/Cellar/mod_fastcgi/2.4.6/libexec/mod_fastcgi.so
   

   Now, to configure Apache with IIPImage, insert the following block below the default <Directory /> block:

    <Directory "/Library/WebServer/Documents/fcgi-bin">
    AllowOverride None
    Options None
    Order allow,deny
    Allow from all
    Options +ExecCGI
    </Directory>
   
    AddHandler fastcgi-script .fcg .fcgi .fpl
   
    # Initialise the FCGI server - set some default values
    FastCgiServer /usr/local/share/iipimage/iipsrv.fcgi \
    -initial-env LOGFILE=/tmp/iipsrv.log \
    -initial-env VERBOSITY=2 \
    -initial-env JPEG_QUALITY=50 \
    -initial-env MAX_IMAGE_CACHE_SIZE=10 \
    -initial-env MAX_CVT=3000
   

   Finally, we'll be changing the port that Apache will listen on. This is optional. Replace Listen 80 towards the top of the file with your chosen port. We'll be using port 8001.

    Listen 8001
   

4. Because the IIPImage binaries point to libraries that are not in their default location, issue the following command to point IIPImage at the fcgi library on our system:

    $ cd 
    $ install_name_tool -change /usr/lib/libfcgi.0.dylib /usr/local/lib/libfcgi.0.dylib iipsrv.fcgi
   

   To test that this worked, we can do

    $ otool -L iipsrv.fcgi
   

5. Now we will start Apache.

    $ sudo apachectl start
   

   If you navigate your browser to localhost:8001 (or just localhost if you did not change the listen port), you should now see the IIPImage initialization page. IIPImage is ready to go!