Installing the OHMS Viewer on a Third-Party Webhost

This guide walks through the steps for installing and using the OHMS Viewer in a third-party web host environment such as GoDaddy.com, Hostgator, DreamHost, or Blue Host.  As a test, the Nunn Center has been successfully using a viewer in a third-party web host environment for many years.  This guide assumes you are familiar with the basics of OHMS.  To learn more about how the OHMS system works, the relationship between the OHMS Viewer and the OHMS Application, and how OHMS works with your Content Management System, watch the video How OHMS Works or other videos and documents here.

Initial Installation

  1. Download the latest version of the OHMS Viewer from Github.  The latest version can always be accessed here.
  1. Place the viewer code into a subfolder within your web root.  Name this folder “ohms-viewer” or something like that. You may call this directory anything you wish to call it, but this will serve as the root of your hyperlink to the OHMS xml file you will be providing your users.  Depending on your Webhost, you may need to use an external FTP application such as Filezilla to move the unzipped installation files into your new directory.  Some hosts allow the upload of the zip file, and will “extract” the contents.  Mine requires I unzip on my local computer and use an FTP application to upload the contents.

OHMS-Viewer-directory

  1. Next, you must create the location from which the OHMS Viewer will access the OHMS xml or “cache” files exported from OHMS. The cache files can be located on the same server, inside the OHMS Viewer directory, or on another server.  We typically create a directory called “cachefiles.”

OHMS-Viewer-Cachefiles-arrow If you do place the cachefile directory within the same folder containing the OHMS Viewer, just be conscious of this when you upgrade your OHMS Viewer.  The OHMS Viewer upgrade process involves overwriting preexisting files with the new ones.  We purposely left out an empty “cachefiles” directory in the viewer installation/upgrade so that your folder containing your xml or cachefiles will not be inadvertently overwritten.  That said, be careful if your “cachefiles” directory is inside the viewer installation.  I typically make a quick backup of the cachefile directory prior to doing an upgrade.

  1. Navigate to the new OHMS-Viewer directory. Go to the “config” folder and rename the file “config.template” to “config.ini

 

Setting up the Config File

  1. Open the config.ini file (this should open with a very basic text-editing program such as Text Wrangler or TextEdit, Wordpad, EditPad Pro or even Notepad.  Within config.ini, you’ll see a lot of settings that you can assign values to. Here is a list of each config.ini item and what it does:
    •  tmpDir – This is the absolute hosting path to where the XML files are contained. You may need to get this information directly from your web host. For example:
      • /var/www/OHMSViewer/cachefiles
      • /home/content/uniqueID/html/ohms-viewer/cachefiles
    •  players – A comma-delimited list of players that you want to support. Unless you are customizing OHMS to play with your own player, this should not be changed.
    • Timezone – This is your local timezone. This must be entered in an appropriate format. For a list of acceptable timezones, please visit http://php.net/manual/en/timezones.php.  For the Nunn Center the config field looks like this:
      • timezone = America/New_York
    • Repository: Set the repository name. Replace the existing entry that states [Your Repository Name] with your repository name as entered in the “repository” data field of your cache files. The names must match exactly (the same uppercase or lowercase letters and any punctuation). For example, if your repository’s name is [John J. Doe Center, University of Us] then that is what must be entered (without the double quotes).
    •  css – The filename of a custom CSS file that you would like the viewer to apply. You only enter the filename, not a path. The path is assumed to be <viewer_folder>/css.
    • footerimg – A relative path to a footer image. For instance if your image was at /var/www/OHMSViewer/imgs/footer.jpg, then the value for this would be imgs/footer.jpg.
    • footerimgalt – A caption for the footer image, mainly used for accessibility purposes (screen readers) to describe what the image is.
    • contactemail – Primary contact email for this viewer.  This will be the default contact link in the viewer footer.
    • contactlink – Fully qualified URL to the website for the user/organization who is setting up the viewer, for example http://www.nunncenter.org
    • copyrightholder – This is just the name of the user/organization who owns the copyright to the interviews contained within the viewer.
    • open_graph_description – The name of the organization using the viewer, as you’d like it to appear on social media.
    • open_graph_image – Image to be used for social media. Entered in the same format as footerimg above.
    • ga_tracking_id – Google Analytics Tracking ID
    • ga_host –  Your Google Analytics host name

 

OHMS Viewer in Action

  1. Place an OHMS xml file into your “cachefile” directory (or whatever you called it).
  2. Construct a link in a browser:

Troubleshooting

Most issues I have encountered setting up OHMS in a third-party webhosting environment have been minor and all related to the setup of the confi.ini file.  Here are some of the more frequent errors:

  • Repository Name does not correlate exactly with the “Repository Name” in the OHMS Application and in the exported xml file.  This must be exact to work.
  • Absolute Hosting Path for the tmpDir.  Webhosts like Godaddy.com, Dreamhost, Network Solutions, and Hostgator can make your absolute hosting path a bit ambiguous.  You would think that if your domain was www.oralhistory.edu that the path to a cachefile directory  installed at the top level of your account would simply be www.ohms.edu/cachefiles  but it usually is not.  As indicated above, get the absolute hosting path from your webhost provider.  Godaddy.com makes this information available in the Server Details section of your account page.  You can simply copy and paste the absolute hosting path, and then add the location of your cachefile directory.
  • Filenaming: Filenames are important.  Names of the viewer directory, names of the xml file are vitally important.  Did you change the name of the Config.template to Config.ini?