Installing LUNA

Owned by Luna
Last updated: Feb 04, 2014 by amiller (Unlicensed)Version comment
19 min read

Introduction

LUNA is an additive component to Insight. You will need to have a working Insight installation and collection(s) to make full use of LUNA.
LUNA can be installed into any of the supported Insight configurations with the exception of Oracle 8. Add the necessary database and ensure you have a minimum of 512MB of free memory, or the recommended 1500MB of free memory, on your server.
There are two major components to LUNA, the LUNA Publisher and LUNA. Each item requires a database. Follow the same guidelines described in the Insight installation to prepare these databases. Both databases will only store user generated information and will not store contents of the collections. This means the storage requirements for these databases are fairly small. 100MB should be plenty of space.

  • Create two databases. One for LUNA and one for the LUNA Publisher


Running the Installer

The LUNA installer, like the Insight installer, requires a GUI. If you are installing on Linux or Solaris, you will need X Windows to run the installer or other GUI interface.
Start the LUNA installer on your system and follow the prompts described in the following section.

Serial Number

The install requires a Serial Number to continue the installation process.
As a licensed institution, you should have been issued one. If not, contact our support department to obtain a valid licensed Serial Number.lunasupport@lunaimaging.com

LUNA Application Configuration

If this is the first time you install LUNA, then you must choose the first option "Configure LUNA Applications and create database tables".
If this is a subsequent installation and you just want to upgrade or reconfigure the LUNA application without deleting any user generated information, then choose "Upgrade or Reconfigure LUNA (Do not create db tables)".
NOTE: If you are upgrading, Stop Jboss before running the installer
LUNA and the LUNA Publisher are deployed using Java W AR http://en.wikipedia.org/wiki/WAR_(file_format) files. This option will just configure the WAR file and deploy it.


For Upgrade or Reconfigure Only
Choosing install sets for upgrade
If you have modified your jboss version for any reason, you may need to apply those changes again once the install is complete.


Choose Install Set

For the Initial installation, you will generally choose Typical. This will include all system components.

  • LUNA
  • LUNA Publisher
  • JBoss
  • Tomcat (New in 6.2.1)
  • Media Manager & Media Processor
  • Administrator Tools


My Uploads Server Only

As of version 6.2.1+, LUNA supports uploading of end user's images and content. This feature requires a Media Manager and the Media Processor components.
Since these components place image processing on the server, you may want to separate this activity to another machine depending on the level of use expected.
If you choose to install the My Uploads Server independently, then you should install this component first. During the install of the LUNA component, you will be asked the server name and port of your My Uploads server.
This will install a Media Manager, Media Processor and Tomcat.

Custom Install

For subsequent installations, you may wish to choose to install a specific component.
You can choose to install any of the following system components.

  • LUNA
  • LUNA Publisher
  • JBoss
  • Tomcat (New in 6.2.1)
  • Media Manager & Media Processor
  • Administrator Tools




Install Location

This will be the base of all the LUNA components selected.


For Upgrade or Reconfigure Only

Since you are upgrading, your previous install log can be used to provide the installer with the same choices that you made the last time you installed.

Choose your Install log. This should be located in the root directory of where you installed LUNA. The name should be something like LUNA_Server_Suite_6.0_installLog.log.















For Upgrade or Reconfigure Only

Since you are upgrading, you will now be asked how to connect to your database. Once connected, the installer will read some of your Application Configuration table to assist you in the rest of the upgrade. See Choosing a D ataba se Type _Choosing_a_Database_Type for more information on making choices for this section.

Specifying an Administrative Username and Password for LUNA

LUNA requires you to specify an administrative username and password. This username and password will be used for authentication within the Administrator Tools and for accessing the JBoss management consoles. Users with this username and password have access to tools that can manage LUNA collection access and Credentials and modify LUNA's configuration, so be careful who it is shared with. NOTE: This password is not encrypted. Do not use your network or system administrator password.

Institution Name


This name is used on the LUNA Collections page to indicate the owner of the local LUNA Collections.
The format is:
<institution name> Collections

In the example below, it is set to Luna.





JBoss and Tomcat Setup

The LUNA application and LUNA Publisher are served via JBoss or Tomcat. The installation will take care of all major configurations with JBoss and Tomcat but you may choose to select different ports for the application to run on.
Note: You are also choosing how much memory to allocate to the application. Make sure this much memory is freely available or the server will have out of memory errors.



My Uploads Media Manager, Media Processor and the LUNA server

My Uploads allows users to upload image and various other file types from their desktop directly into LUNA.
This address must be available to all end users who will be accessing this feature.
Important! This is not your Insight Media Manager
Typically this will be the same address and port as your LUNA and LUNA Publisher but it can be installed on a different server.

LUNA Configuration

This section allows you to choose how the LUNA application is generally configured.

Insight User Manager Address

LUNA can use your existing Insight User Manager to grant access to your collection resources. You do not need to create the accounts. As a user is logged in, the username is passed to the LUNA system (not including the password) and the user is granted access to the same collections that they had access to in Insight.

Header Graphic Hyperlink

You have the option to make a link in the Header Graphic go to a specific http address. By default the address will return to the LUNA collections Page (/luna/servlet).
This feature is useful if you want to create a launch page for the LUNA application and from LUNA the user can return to the launch page.

Personalized Footer

You have the option to add a personalized Footer in LUNA. This footer will be placed at the bottom of all LUNA pages.
Just create a simple web page with a black background and place it on a web server.
Click here to see a Luna Footer Example

OAI-PMH Setup

If you would like to share some of your collections with OAI-PMH then enter a repository name and an Admin Email account. If not leave these fields blank.

Enable Google ads

If you would like to place ads on the content of your site to generate potential revenue to support your collections, just check the ads box. The ads will be placed on the right side of the application. Go to http://www.google.com/intl/en/ads/ to sign up for an AdSense account. You will be prompted later in the installation to provide additional information specific to your AdSense account.

Enable End User Registration

LUNA has built in end user self management. If you would like your end users to manage their own accounts (allowing them to create Media Groups, presentations and search External Media), select this item. Later in the configuration you will be asked for your email server information for outgoing messages.

Access LUNA Commons Collections

Selecting this option indicates you want to receive free collections from the LUNA Commons. You will be required to provide additional information later in the installation process.

Share Select Collections with the LUNA Commons

Selecting this option indicates you want to share some of your collections with the LUNA community. You will be required to provide additional information later in the installation process.

Enable SSL for Login

To prepare your system to support SSL during login, select this item. You will also need to install a certificate to implement the SSL login capabilities.

Enable Google Analytics

Prepare your system to support Google Analytics. You will also need to have a Google Analytics account to make use of this option. See http://www.google.com/analytics

Include File Data at the bottom of the Media Information panel

This option allows you to disable the File Data contained at the bottom of the Media Information Panel. To show this information check the box, uncheck to hide it.

Enable CAPTCHA for multiple failed Logins

To help reduce the risk of brute-force attacks, LUNA has a CAPTCHA challenge option. The CAPTCHA will be presented when the user fails to enter the right username/password combination within a set number of tries.




Facet Threshold

The Facet threshold determines the minimum number of items required before a facet value is displayed. If you want all values to display, set the value to 0.
Please note, this will affect the display performance of the Categories page. The lower the number the more values will need to load per category.
The default for this setting is 5

Custom Authenticator

As of the 6.3.6 release, some custom Authenticators have been added to LUNA's configuration. The majority of installs should just choose "Normal". If, however, you are integrating LUNA with Shibboleth then choose "Custom".

Custom Shibboleth Authenticator



For Shibboleth Only
To configure LUNA for Shibboleth, you must first have your web server configured as a Service Provider (SP) for shibboleth. LUNA must also be setup with AJP so it runs through your web server that has been configured with Shibboleth. This configuration may be complex and we suggest you contact our support department: support@lunaimaging.com
Note: This documentation only covers the settings for LUNA and not specifics on Shibboleth configuration.

Choose Shibboleth and Replace Existing luna-security.xml.

Enter the Shibboleth Login URL which is the LUNA login address http://www.example.com/luna/servlet/login
Enter the Shibboleth Logout URL which will log you out of Shibboleth http://shibbolethServer.example.com/Shibboleth.sso/Logout


Access LUNA Commons Collections

See what is in the LUNA Commons, [http://www.lunacommons.org/

|http://www.lunacommons.org/] LUNA Commons Server Address

To access the LUNA Commons, you may need to enter the appropriate Community Commons server address (the default will work unless told otherwise).

Enter your Institution's Short Name and your Serial Number

When you were issued your Serial Number, you were also issued a Short Name for your institution. This Short Name and your Serial Number are your keys to access the LUNA Commons collections.
Enter a string of letters and numbers with no spaces or special characters. This string will be used in the LUNA Publisher to trigger a download of the LUNA Commons content.

Share Select Collections with the LUNA Commons

With LUNA you can share some of your collections with the larger LUNA Community.

    1. Enter Your LUNA Commons sharing URL.
      • This is the address to your LUNA server. The LUNA Commons Server will use this address to retrieve the collections you decide to share.
    2. Enter Your Access ID and Access Password
      • This will be used by the LUNA Commons server to gain access to your selected LUNA collections.
      • By default this has been set to your institution's Short Name and Serial Number.



    1. Create a new LUNA account
      • This account will be used to define what collections are being shared with the LUNA Community.
      • Once you have collections in LUNA, you can use the Admin Tools to assign collections to the Content Distribution Credential.


    1. Enter a string of letters and numbers with no spaces or special characters. This string will be used in the LUNA Publisher to trigger the creation of your public content that you will share with the LUNA Commons.


Google AdSense Configuration

If you are seeing this screen, then you have selected to enable Google ads on your site. You will need to provide specific information to enable this feature properly. During your account setup in AdSense, you were provided information appropriate to this feature.

SMTP Mail Server Setup

If you selected end user registration, then fill in the following form.

  • Your email domain address
  • SMTP Port Number
  • SMTP User (optional)
  • SMTP Password (optional)
  • Senders email account (the account end users will respond to if necessary)
  • Registration CC (optional) (will cc this email account on any self registration)




reCAPTCHA Setup

In order to make use of the CAPTCHA challenge, you will need to obtain a reCAPTCHA Public and Private key specific to your domain.
The process is very quick, just go to https://www.google.com/recaptcha and follow the instructions.
Enter the reCAPTCHA public key
Enter the reCAPTCHA private key
Enter the number of failed login attempts to present before the reCAPTCHA is displayed.

Examples of the normal login window and CAPTCHA login window


Google Analytics Setup

If you selected Google Analytics, you will need to enter your Analytics ID here.

LUNA Publisher Maintenance Setup

The information supplied in this panel is used when LUNA needs to be placed into a maintenance mode so that you can perform server adjustments or when the LUNA Publisher needs to replace the Lucene index with an updated version.
The maintenance mode is invoked via a URL with a security key. We suggest making the security key obscure by using only web friendly characters and letters.

NOTE: If you are Upgrading or Reconfiguring, then skip to LUNA Grap hi cs URL _LUNA_Graphics_URL

Choosing a Database Type

The installer is designed to connect to your database server and to create database tables, fields and indexes for your LUNA Server and LUNA Publisher. Please choose the database type you wish to use. The information you identify here will be used to configure LUNA.

LUNA Database Information

Provide the information necessary to connect to your database, including the hostname, database name (SID Name if you're using Oracle), and database port. The installer will offer default values based on information provided earlier. Review the defaults (and change them as needed).

Database Username and Password

Please specify the username and password for your database. This is the username and password that LUNA should use to connect to the database.

  • WARNING: the installer will DROP ALL LUNA TABLES once it has connected, so be sure that you are not installing over an existing version of LUNA. (The installer will warn you again before it actually drops any tables.)


Creating the LUNA Database

Once the installer has tested the connection, it will present you with the database creation script window. Click "Run Script" to create the LUNA tables and indexes.


LUNA Graphics URL

The LUNA Graphics URL is used to access LUNA theme header graphics. Just make sure this URL is externally accessible from the installed machine. Do not use localhost or any other internal domain unless you know for sure the content will not be used outside of your institution.


LUNA Publisher Database Information

Provide the information necessary to connect to your database, including the hostname, database name (SID Name if you're using Oracle), and database port. The installer will offer default values based on information provided earlier. Review the defaults (and change them as needed).

Database Username and Password

Please specify the username and password for your database. This is the username and password that LUNA Publisher should use to connect to the database.

  • WARNING: the installer will DROP ALL LUNA Publisher TABLES once it has connected, so be sure that you are not installing over an existing version of LUNA Publisher. (The installer will warn you again before it actually drops any tables.)

Creating the LUNA Publisher Database

Once the installer has tested the connection, it will present you with the database creation script window. Click "Run Script" to create the LUNA Publisher tables and indexes.

Lucene Index Folders

LUNA uses Lucene to search for content in your collections. These indexes can add up to hundreds of megabytes depending on the content you have in your collections. 160,000 objects takes about 400MB but this is entirely dependent on the size of your collections that you are accessing. So choose an appropriate location that can grow with your collections.


LUNA Temp Files Location

During the use of LUNA, content is exported and this location is used to store that information temporarily.

LUNA Storage

LUNA and the LUNA Publisher need space to store information extracted from Insight collections and a place to create the Lucene indexes during the publishing process. LUNA also uses this area for content distribution with the LUNA Commons Server. This area can easily grow to several gigabytes.

Media Manager for My Uploads Storage Location

The My Uploads server needs a location to store the content that is uploaded to it. Depending on the expected level of use, choose a storage location.

Start the Install Process

This may take several minutes depending on the server speed and how you are accessing the installer.


Before Installing LUNA and the LUNA Publisher you will see this IMPORTANT message.

*****IMPORTANT NOTE Updated in 6.3 *****

The Installer will now backup any existing LUNA and LUNA Publisher configurations. This backup will be placed in
<USER_INSTALL_DIR>/luna_backups
With any upgrade, you should perform your own backups of the file system and databases before installing any new version.
IMPORTANT LDAP AUTHENTICATION INFORMATION
As of LUNA version 6.3 your authenticator settings are being preserved during the upgrade process. The settings are now stored in a file called luna-security.xml at the same location as the applicationContext.xml


Starting LUNA and the LUNA Publisher


You can start these two servers by starting the Tomcat or the JBoss server.
Go to:
<Install Directory>/tomcat/bin
or
<Install Directory>/jboss/bin

For Tomcat:
We have also supplied you with our standard java service wrapper version for starting and stopping the application:
start_jboss.bat on windows and start_tomcat.sh for Linux and Solaris will start tomcat in a console mode.
If you would like to start tomcat as a service on windows, we have supplied you with the install_as_service.bat file.
If you want to run jboss in the background using the java service wrapper on Linux or Solaris, you can start it with:
./tomcat_service.sh start
The script has the following options:
console | start | stop | restart | status
For Jboss:
You can use the standard jboss supplied run scripts run.bat or on Linux and Solaris you can start the servers by executing the run.sh script. If you want to run this in the background we suggest running:
nohup ./run.sh &
We have also supplied you with our standard java service wrapper version for starting and stopping the application:
start_jboss.bat on windows and start_jboss.sh for Linux and Solaris will start jboss in a console mode.
If you would like to start jboss as a service on windows, we have supplied you with the install_as_service.bat file.
If you want to run jboss in the background using the java service wrapper on Linux or Solaris, you can start it with:
./jboss_service.sh start
The script has the following options:
console | start | stop | restart | status






Once started go to http://www.example.edu:8180/
You should see something like one of the following:

The LUNA application will now be available at http://www.example.edu:8180/luna/servlet and it will look similar to the following page:




My Uploads Server testing


Testing the Media Manager


In your browser, go to http://localhost:8180/MediaManager/srvr
You should get a message like the following:


Testing the JPEG2000 Decoder


http://localhost:8180/MediaManager/jp2ktest
You should get a page like the following:

If you see any errors, see the Testing the JPEG2000 Decoder & the Media Manager in the Install and Configuration Guide.

Adding Insight Content to LUNA

Introduction


It's fairly easy to add Insight content to LUNA but first you should know what LUNA is and what it is not.
LUNA is a search interface and a place to work with media content. LUNA is not the repository of the content. LUNA allows the end user to select, organize and make use of various image and media content.
As of version 6.2.1, LUNA supports three kinds of source content. You can access and use Insight content and you can access and use content from Flickr and content from your own desktop using the My Uploads feature.
Insight Studio is used to prepare content for LUNA using the LUNA Publisher. This tool is available from the Insight Studio Task Menu.

The LUNA Publisher

So what does it mean to add content to LUNA? Well it's pretty simple; it means extracting all descriptive data from Insight and placing it into an index that LUNA uses to search. It also sets up and provides LUNA with information to connect to the Insight collection.
The LUNA Publisher is the tool you use to do the following:

  • Schedule when and how often the LUNA collection index is updated from the Insight Collection.
  • Setup LUNA specific characteristics
    • Choose Media Summary fields (provides additional roll-over information).


    • Choose the Who, What, When, Where fields used for filtering search results.


    • Identify the URL to the LUNA header graphic.


  • Using the Merge and Load Task, all individual collection indexes are merged into a single index and then loaded into the live LUNA system.


LUNA Theme Header Graphic

The LUNA theme header graphic is the background that shows up at the top of the LUNA interface and can be different for each collection. This is used to provide collection identity.
The graphic needs to be 754 x 65 and should fit the theme being used by fading to a solid color on the right of the graphic (R=133, G=124, B=117 or the hex is #857C75).



To upload your Header Graphic, locate the Header Graphic section of your LUNA Publisher.
Click "Select header graphic".

Next, click "Upload File". You will then be presented with a confirmation dialog box.

You can also Preview the graphic once it is uploaded.

To setup a LUNA header graphic that will be used when more than one collection is being accessed, edit the Extended Collection Properties for the "-1" Collection ID.

The default is set to /luna/images/luna-default-header.jpg
Note: This path refers to an image stored within the LUNA software. This is used as the default location.

Let's Get Started


Prerequisites

You need the following to proceed:

  • LUNA and the LUNA Publisher need to be installed and running.
  • 6.x version of Insight Studio configured with access to the LUNA Publisher.
  • At a minimum, the language bundles on the Insight User Manager need to be updated.
  • Insight Studio access to the collections you will be adding to LUNA.
  • Inscribe access to the collection(s) you will be publishing.
  • Note: The LUNA Publisher pulls the descriptive metadata and media information from a form of Inscribe. In certain collections that were created prior to 5.x, this content may not be properly accessible. If you do not see the correct images or data in the Inscribe tool, contact Luna's support department for assistance in preparing your collection for LUNA.
  • Collections that were created in Insight 5.x+ will not have this issue.


Publishing a Collection

Start Insight Studio, select the collection you want to publish to LUNA and from the Main Task Menu select the LUNA Publisher.

Next, select "Launch LUNA Publisher".

This will launch a web browser and connect to the LUNA Publisher.




Once in the LUNA Publisher, you can make your selections in the following areas:

  • Enter a Task Description (optional).
  • Choose the Theme for your collection.
    • Only "default" and "blue" are available. These themes will change the color scheme of the entire application.

  • Choose the LUNA Header Graphic URL for your collection. If you have not selected one, the default graphic will be used.

 

 

    • If you are planning on sharing your collection with the LUNA Commons, this will point back to your instance of LUNA in all web crawlers. So any institution sharing your content publicly using the LUNA Commons will be advertising your site and content. This will increase your page rank in search engines like Google.

 

  • Choose the Insight User Group that will be used to access the data from your Insight Collections.

 

  • Select the Title Field from the drop down list. This Title will be used to identify individual media items on several pages within the LUNA application, such as the Detail view and as a label in a slideshow.

 

  • Select up to 4 Summary Fields to display. The Summary Fields will display as the user moves their mouse over the thumbnail images.

 

  • Drag and Drop up to 20 fields into the Who, What, Where and When categories.
  • Choose a recurring schedule for the LUNA Publisher to perform updates of the LUNA search index.

 

  • You have 4 options When completing this task
    • Save Task (will only save the task)
    • Save and Run Task (will save and run the task now)
    • Save and Schedule Task (will save then execute the task on a schedule)
    • Save, Schedule and Run Task


Once you schedule this task, the LUNA Publisher will do the following:

  • Archive the data from Insight.
  • Produce an Index for the Collection.
  • When the Merge and Load task is activated, all collections that have been indexed will be merged and the new Master Index will be created and placed on the live LUNA server.
  • Note: You need to activate the Merge and Load task before LUNA will make the collections live.

 

  • Note: Before continuing on to the step of activating the Merge and Load task, you'll need to wait until the task is complete. To confirm that the scheduled task has completed, click on Task List in the main menu at the top or refresh your browser. In the Task List, the message under the Status column should read "inactive", which means you can begin the Merge and Load task.

Activating the Merge and Load task


So what is Merge and Load?
During the Publishing process, a collection is turned into a searchable index for a specific collection. Each index is stored in the collection_indexes folder on your server.
Once you have published all collections that you currently want to make available in LUNA, these separate published indexes need to be merged into a single index. Then when the merge process is complete, the merged index needs to be loaded as the active current index. Once loaded you can search all collections that have been published to LUNA.
Now to activate the Merge and Load task
In the LUNA Publisher task list, locate the Merge and Load task. This will be the one without a delete button. Click the Modify button.

  • Now set your preference on how often the Merge and Load task will take place. If you want it to run every night at 2am, select all the days of the week and change the hour to 02.
  • You have 4 options When completing this task
    • Save Task (will only save the task)
    • Save and Run Task (will save and run the task now)
    • Save and Schedule Task (will save then execute the task on a schedule)
    • Save, Schedule and Run Task





Schedule URL Request


A URL Request is a special task and will most likely not be created by LUNA administrators. Two URL Request tasks are created by default during installation "Get LUNA Public Content" and "Prepare Public Content".
These tasks make request to the LUNA server to activate an operation on the server.
The "URL" specified in the request will be called at the time of the request and Name and Value pairs will be passed to that server in a Post action.
This is similar to what happens when you fill a form out on a website and press send.

Testing your LUNA Collections

Once your collection(s) have been Published, Merged and Loaded, you will be able to view your Collections in LUNA. You may need to login or adjust your credential settings to get access to your collections.
The address to your LUNA collection will be similar to the following.
http://www.example.edu:8180/luna/servlet




If you would like to access your collection(s) without the port number (8180), you will need to configure the system to use the AJP connector. There are instructions on how to work with the AJP Connector for both Apache and IIS available on the web.
This document does not cover how to configure the AJP connector.

Changing Sorting of your Collections in LUNA

You can adjust the order of how your Collections are displayed in LUNA's Collection listing page and Menu.
Open your Admin Tools and select the Media Collections Node. Double click on the collection name of the collection you would like to change the order of. You can only order collections you manage, not LUNA Commons collections.