Installation and Setup
From Ara Irititja KMS Wiki
The Installation and Setup instructions have been written for an audience who possess an intermediate skill level and understanding of the following computer concepts:
- Operating System File and Permission System
- Installing Software
- System interaction via the command line
- Mac and/or Windows Operating Systems
- Basic knowledge of Browsers, Web Servers (Apache) and Databases (MySQL)
- Hardware and System Configuration
Installation of Required Server Software
If you are an experienced System Administrator, you may wish to configure your own Apache/MySQL/PHP server and install the additional required software yourself. (See Server Requirements) If this is the case, then proceed to the Configuring the Server's Root Directory section once you have configured your server.
Alternatively, the following instructions will take you through the process of installing a pre-bundled Apache/MySQL/PHP server distribution with the required supporting software. Windows users will install the BitNami WAMPStack distribution and Mac users will install the BitNami MAMPStack distribution.
Begin these instructions once you have installed one of the required Browsers, the Flash Player browser plug-in, and updated your Operating System will all patches and updates.
Configuring the Server's Root Directory
- Copy the contents of the /Archive Software/ folder from the disc into Apache's DocumentRoot directory. If you have installed WAMPStack/MAMPStack using the instructions in this document, the DocumentRoot directory can be found at:
WAMPStack: C:\Program Files\BitNami WAMPStack\apache2\htdocs\
- Change the permissions of the DocumentRoot directory and all its enclosed files and folders so that Apache is the owner and has read, write and execute permission enabled.
To do this with MAMPStack:
Open a Terminal window and enter the following two commands:
sudo chown -R daemon:admin /Applications/mampstack/apache2/htdocs
sudo chmod -R 755 /Applications/mampstack/apache2/htdocsYou may need to enter your password when prompted.
To do this with WAMPStack:
Check that the 'Administrators' group has read, write and execute permissions enabled for the C:\Program Files\BitNami WAMPStack\apache2\htdocs\ directory. It is likely that these permissions have already been enabled.
- Change the permissions of the 'public' directory inside the DocumentRoot directory to allow read, write and execute permissions to all Users.
To do this with MAMPStack:
Open a Terminal window and enter the following command:
sudo chmod -R 777 /Applications/mampstack/apache2/htdocs/publicYou may need to enter your password when prompted.
To do this with WAMPStack:
Enable the read, write and execute permission for 'Users' group on the C:\Program Files\BitNami WAMPStack\apache2\htdocs\public directory.
- If you intend on running the software in a stand-alone or non-dedicated server configuration, you may want to place an alias/shortcut to the 'public' directory on your desktop for convenient access to the public folder.
To do this with MAMPStack:
Open a Terminal window and enter the following command on a single line:
sudo ln -s /Applications/mampstack/apache2/htdocs/public ~/Desktop/"Archive 'Public' Folder"You may need to enter your password when prompted. Note: the command 'ln' begins with a lowercase 'L' and not the numeral '1'.
To do this with WAMPStack:
Open the C:\Program Files\BitNami WAMPStack\apache2\htdocs\ directory. Right mouse click the 'public' directory and select 'Create Shortcut' from the menu that appears. You will be asked whether you would like the shortcut to be placed onto your Desktop, confirm by clicking 'Yes'.
Proceed to section Installing and Configuring Red5 Media Server.
Installing and Configuring Red5 Media Server
Red5 is a media streaming server used to record and playback audio and movie annotations. The server needs to be installed and configured for use with the Archive software.
There are two versions of Red5 (version 0.8) available on the supplied disc, one for Java 5 (1.5) and another for Java 6 (1.6). The two versions are clearly identified in separate directories on the disc. When following these instructions be sure that you are using the appropriate version for the computer the Archive is installed on.
Archive Software Configuration and Initial Import
This section describes the process of configuring the archive software and importing content from the FileMaker version of Ara Irititja Software. If you have not prepared the FileMaker export files using the instructions in Ara Irititja Archive FileMaker Export section of this wiki, then you should do so before continuing with the configuration of the System.
System Configuration Options
Before beginning the setup of the archive software, it is important to understand the configuration options of the System. Many of these options can be changed post-setup, however there are a few non-editable options which can only be set during the initial setup process. These non-editable options have been marked with an asterisk (*) in the descriptions below.
|* Archive Identifier||The Archive Identifier is a code used to indentify an installed instance of the Archive Software across a multi-archive project. The code must be unique for each Archive installation. It is used as a prefix to the Archive Numbers generated by an Archive. The indentifier may be a series of letters and numbers of no more than ten characters in length.|
|Archive/Project Title||The main title of the project or organisation administering the archive software. Eg. "Ara Irititja".|
|Community/Instance Title||A subtitle used to identify the community or instance of the software. Eg. "Amata School"|
|Date Timezone||The timezone of where the Archive Software is installed.|
|* Profiles Receive Archive Numbers||Determines whether the records of Profiles — People, Places, Collections, Fauna, Flora, etc — are given Archive Numbers in addition to Archive Items.|
|Store Original Media on Server||Determines whether the original media file is retained on the server.|
|Original Media Storage Path||The absolute path to the directory of where original media files are to be stored. Apache must be given permission to read and write to the nominated directory.|
|Disk Free-space Warning||A warning message is displayed to administrators when the available free-space on the System and storage disks is less than a specified percentage.|
|Session Duration||The duration in minutes of allowable user inactivity before automatically logging the user out of the System.|
MySQL Database Configuration
|* MySQL Executable Path||The absolute path to the 'mysql' executable.|
|* MySQLDump Executable Path||The absolute path to the 'mysqldump' executable.|
|Host||The hostname used to connect to the MySQL Server.|
|Username||The username of the account used to connect to the MySQL Server|
|Password||The password of the account used to connect to the MySQL Server|
|Database Name||The name of the database.|
|* ImageMagick's 'convert' Path||The absolute path to the 'convert' executable.|
|* GhostScript Path||The absolute path to the GhostScript executable.|
|Archive Max. Dimension||The maximum height and width to constrain archive viewable images when created by the Archive.|
|Thumbnail Max. Dimension||The maximum height and width to constrain archive viewable thumbnails when created by the Archive.|
|Archive JPEG Quality||The JPEG compression quality applied to archive viewable images and thumbnails when created by the Archive.|
|Mp3 Sampling Frequency||The sample frequency applied to archive playable audio files created by the Archive.|
|Mp3 Bit Rate||The bit rate applied to archive playable audio files created by the Archive.|
|* 'ffmpeg' Executable Path||The absolute path to the ffmpeg executable.|
|* 'mp4file' Executable Path||The absolute path to the mp4file executable.|
|* Wowza/Red5 Application||The path of the Wowza/Red5 application configured for capturing annotations.|
|Movie Compression Quality||The compression quality applied to the movie's image when recording an annotation.|
|Movie Bandwidth||The bandwidth limit to enforce on audio and movie annotations when recording an annotation.|
|Movie Frame Rate||The frame rate for movie annotations.|
|Audio Sampling Frequency||The sampling frequency applied to annotations while recording.|
Archive Setup: Configure, Install and Import
Configuring the System is a one-off task that must be performed before launching the Archive for the first time.
- Open a browser window and enter the URL to the home directory of your installation. The URL will be http://localhost/ if you have followed the instructions in this document. Click the 'Begin Archive Setup' button to proceed.
If you are repeating this setup process, then enter the url to the 'install.php' page inside the 'installation' directory of your Archive. The URL will be http://localhost/installation/install.php if you have followed the instructions in this document.
- On the 'Archive Configuration' page, enter your configuration settings.
If you have installed WAMPStack/MAMPStack using the instructions and software in this document, then you can choose your installation configuration in the 'Platform Presets' pop-up list. These presets will populate the following options with the correct values for your configuration.
- MySQL Executable Path
- MySQLDump Executable Path
- Database Name
- ImageMagick's 'Convert' Path
- GhostScript Path
- 'ffmpeg' Executable Path
- The remaining options must be manually set.
In the 'Password' text field under the 'MySQL Database Configuration' heading, enter the password for the MySQL 'root' Account setup during the installation of WAMPStack/MAMPStack.
Once you have entered your settings, click 'Save Setting and Initialise Database' to continue.
- On the 'Install Schema' page, make sure Ara Irititja is selected under the 'Archive and Traditional Knowledge Schema' heading. Click the 'Install Schema' button.
- On the 'Import Archive' page, enter a Name, Username and Password for the Super Administrator account used to administer the System. The Username and Password must be a minimum of four characters in length.
- If you are importing from FileMaker, select 'Ara Irititja/Our Story FileMaker Export' as the import source under the 'Import Data into Archive' heading and proceed to the next step. Otherwise, select 'Don't import anything, leave as empty shell.' as the import source and click 'Set Account and Import' button. Proceed to step 8.
- Enter the file path to the exported Export.mer merge file and Open Images folder.The instructions on preparing these files can be found in the 'Ara Irititja Archive FileMaker Export' section of this document.
You may be presented with a checkbox that allows the preservation of Archive Numbers used in the FileMaker Archive. This option is only available if you have configured the Achive to not provide records of Profiles with Archive Numbers. You should only enable this option if your Archive Numbering in FileMaker is consecutive across all Archive Item types. Not all Ara Irititja FileMaker Archives were configured with consecutive numbering.
- Once the file paths have been entered, click 'Set Account and Import' button. The importation process may take several hours to process. It is not uncommon for a very large (80,000+ records) Archive to take 30 or more hours.
- Once the installation has finished, any errors and warnings will be displayed on screen. You can download a text file containing the errors and warnings logged during the installation process. See Understanding Import Errors and Warnings section of this document.
In addition, an installation log can be found in the home directory of Archive Software. The log file can be accessed at:
- MAMPStack: /Applications/mampstack/apache2/htdocs/install.log
- WAMPStack: C:\Program Files\BitNami WAMPStack\apache2\htdocs\install.log
- Click 'Launch Archive' to enter the Archive.
Once you have successfully setup your Archive, you should remove the 'installation' directory from the Archive's root directory. It is a security risk to leave this directory in its current location. A user could reinstall the System without consent — destroying Archive data!
Understanding Import Errors and Warnings
There are a number of issues that can occur during the import process which could lead to loss of data. In some cases, these issue can be fixed within the new Archive, however most errors and warning require correction within the FileMaker Archive. Once these issue have been corrected, the importation process must be repeated.
Use the FileMaker Import Errors and Warnings Guidelines to address your import issues.
Software Update Diagnostic Tool
The Archive Software contains a Software Update wizard which provides a simple method of delivering software updates and upgrades to your Archive. The wizard accepts a 'package' which is automatically extracted and installed into the System.
To ensure this system is working correctly, a diagnostic package has been created to test that your Archive has been correctly configured. It is recommended that you run this diagnostic process immediately after you have completed the Archive Setup process. The update does not perform any updates to your system, it only tests your installation configuration.
To run a diagnostic update:
- Enter the Archive using a Super Administrator account.
- Under the 'Administration' menu, select 'Home' to enter the Administration Home screen.
- Click the 'Software Update' link under the 'System' heading. This link will only be available if you have logged in as a Super Administrator.
- In the Software Update wizard, choose the 'packagediagnostic.zip' file found on the disc that accompanies this documentation. Click 'Continue' once the file has been selected.
- If the Archive Software is correctly configured you will receive a message indicating the update is ready to be installed. Click 'Install Update' to begin the diagnostic process.
- Once the diagnostic has finished running, you will be presented with an update report. A 'Successful Software Update' message indicates your System has been correctly configured to accept future software updates using this process. Click 'Launch Archive' to continue using the archive.
If you receive any errors or deviations from the below instructions, it is likely your installation has not been configured correctly. In this event, pay particular attention to the file permissions outlined in the 'Configuring the Server's Root Directory' section of this document. You may be able to correct these permission issues without having to re-run the Archive Setup process. Repeat the above instructions until a 'Successful Software Update' message is received.
If you have received errors during the System Configuration process, below are possible reasons for the errors:
- The installation of ImageMagick, GhostScript,ffmpeg and mp4file may be faulty. Try reinstalling these programs.
- Ensure the permissions of Apache's DocumentRoot directory have been correctly set.
- An incorrect path to a file or folder may have been entered during the installation process.
- Corrupt, missing or incorrectly typed media files may cause warnings, or the record to be skipped, during the installation process.
|Adobe Flash Player||http://get.adobe.com/flashplayer|
|Java Runtime Environment||http://www.java.com|
|Microsoft Internet Explorer||http://www.microsoft.com/windows/internet-explorer/|