GSAC Quick Installation
    March 15, 2016  Stuart Wier, UNAVCO

    This document is a short version of the material in the web page http://www.unavco.org/software/data-management/gsac/installation/installation.html
    and also the material in the GSAC package file README Part 1 (except about installing federated GSACs). If this guide is unclear, look in those places.
    This guide of 150 lines replaces about 600 lines.  After completing this guide, you will use the GSAC README part 2 which does not have a short version.
    This document is in the GSAC package at gsac-code/.

    You have a suitable Linux system, with Java JDK 1.6 or 1.7, the subversion ('svn') respository control tool, and 'ant' the Java compilation and build tool.
    And a database for GSAC with complete metadata about sites (stations or monuments), their instruments, and their data files, as appropriate for your instruments and data files.

    Beginning January 29, 2015, GSAC can be made with either Java 1.6 or Java 1.7.  The Java Library files were updated from the older GSAC code, for both cases.  
    If you use Tomcat with Java JRE 1.6 you will need GSAC built with Java 1.6.

    Building your code for GSAC services has two major parts:
    a. Download the GSAC package and build its core code (called the GSL, the GSAC service layer), which includes some templates for your "local GSAC files".
    b. Complete your "local GSAC files". Your "local GSAC files" are new Java for GSAC to read from your database, and also to specify what services your GSAC offers.
    This README Part 1 (and the GSAC Quick Installation guide) tells how to do "a."
    GSAC instructions use a hypothetical "Boulder" data repository; you will of course use your own terms.
    README Part 2 tells how to do "b," complete your "local GSAC files". You will create two important new Java code files (for example BoulderSiteManager.java) in your "local GSAC files".

    (To install a Federated GSAC, do all this quikc install, and then see the README part 1, section 4, in the gsac-code/src/org/gsac/README file.)

    Choose or make a top-level working directory for GSAC, and go there. For example:

mkdir ~/GSAC2016/
cd    ~/GSAC2016/

    Check out the GSAC code from SourceForge by entering this command:

svn export http://svn.code.sf.net/p/gsac/code/trunk gsac-code

    This creates a new top level directory for all GSAC files, a new directory called gsac-code/, and downloads all the files in the GSAC package.
    Your new directory need not be called gsac-code/, as in the example svn export command above.  But the GSAC installation guides use gsac-code/ so it is easier to use that.

    The GSAC package from SourceForge contains code for both Java 1.6 and 1.7.  The difference is entirely due to Java library files. GSAC's code is virtually unchanged. 
    The Java 1.7 GSAC has recent Java security improvements (this addition to GSAC was requested by a U.S. government lab using GSAC.)
    The Java 1.6 GSAC works with existing Tomcat Java 1.6 servers used by several GSAC operators.

    The GSAC package exported from SourceForge is ready to build GSAC with Java 1.7.  Make sure your javac compiler is for Java 1.7.
    The command "which javac" should show a Java 7 comoiler, such as /usr/lib/jvm/java-7-oracle/bin/javac

    For Java 1.6 GSAC, do the following:
      a. in gsac-code/src/org/gsac/gsl/ do the command cp build.xml.Java6 build.xml
      b. in gsac-code/src/org/gsac/gsl/ edit the file GsacServer.java to use the "import block for Java 1.6" and comment-out the "import block for Java 1.7"
      c. in gsac-code/src/org/gsac/gsl/database/ edit the GsacDatabaseManager.java to use the lines labeled "Java 1.6 version" and to comment-out the lines for "Java 1.7 version."
      d. Make sure your javac compiler is for Java 1.6, not Java 1.7.
      More file changes are in the README part 2 file detailed later.

    Build the GSAC core code:  

cd to gsac-code/

    Do an initial ant build with the command:

ant

    This process sends information to the screen, like 

compile:
    [javac] Compiling 89 source files to /home/developer/GSAC2016_Mar15/gsac-code/src
    [javac] Note: Some input files use or override a deprecated API.
...
     [echo] GSAC server has been built. To run:
     [echo]       cd /home/developer/GSAC2016_Mar15/gsac-code/dist/gsacserver
     [echo]       java -Xmx512m -jar gsacserver.jar
...
BUILD SUCCESSFUL
Total time: 10 seconds

    Look for any error messages.  This process makes a Java jar file, named gsacws.jar, in gsac-code/lib/.
    This file contains the compiled GSAC core GSL code.  This jar file will be used to build your GSAC server executable, to build the Tomcat .war file, 
    and to build any other GSAC using the GSL on your system, such as a federated GSAC.

    Next, create GSAC configuration files and make new initial GSAC code for your GSAC.
    To set the Map Area, edit the file 

vi  src/org/gsac/gsl/htdocs/repositorymap.js 

    to set the longitude, latitude, and map zoom level for the center of the map GSAC shown shows in site search results on a web page.  
    For example use these lines:

var defaultLocation = new OpenLayers.LonLat(14.15, 48.5);  
var defaultZoomLevel = 5;

    The defaultZoomLevel value 3 shows a map about 10000 km across;  6 will show an area about 1200 km wide by 800 km high. 
    West longitudes are negative.  Do not use "W".  South latitudes are negative.  Do not use "S".

    Build the GSAC core code with command 'ant' again, executed in gsac-code/.  

cd to gsac-code/

ant

    Next, use the command "ant makerepository" to create your initial set of local implementation files:
    First make a new macros template file. Go to the template/ directory:

cd  to gsac-code/src/org/gsac/template/

    Copy the file macros.properties to a new properties file such as my.properties.  

cp  macros.properties  my.properties

    The new file name 'my.properties' does not matter. You only use this file one time.
    Edit the new properties file to set values for your repository GSAC.  For example, new values something like these:

vi  my.properties

    target.name=The Boulder GNSS Repository  ## To name the repository. Spaces are allowed.
    target.basename=bouldergsac     ## For your package's .jar file name, and for the Tomcat .war file name
    target.package=org.boulder.gsac  ## to set your GSAC Java package name.  This controls making and naming the new directory path to hold your local GSAC installation code.
    ## If your agency is not an "org", use the appropriate value such as pt, fr, es, de, is, gov, or edu.

    target.prefix=Boulder          
    ## to set the prefix for filenames for the new Java .java files and .class files for your GSAC installation. Like BoulderSiteManager.java.   No spaces.

    target.dbdriver=mysql.jar     
    ## to choose which Java database driver is used in GSAC code to read the database your GSAC will read.  Choose (uncomment) one of these three:
    #target.dbdriver=mysql.jar     
    #target.dbdriver=oracleDriver.jar
    #target.dbdriver=postgres.jar


   Next, change the working directory to

cd  to gsac-code/src/org/gsac/

    Then run this command, with your new properties file name in place of my.properties:

ant -propertyfile template/my.properties makerepository   

    The final lines of screen output should be something like this:

copyjava:
     [copy] Copying 1 file to /home/dev/GSAC2016/gsac-code/src/org/bouler/gsac
     [echo] Repository source package has been created
BUILD SUCCESSFUL
Total time: 1 second

    The ant ... makerepository process creates a new code area (new folders), and new Java files for your GSAC installation, 
    beginning with a new folder, such as in this case gsac-code/src/org/boulder/,
    and populates it with some new directories and files for your GSAC repository's code.
    This is where your "local GSAC files" are.


Edit the Javax Security java.policy file

    Add the following line with permission ... "register" 
    to your java.policy file in the 'grant' section, which may be under $JAVA_HOME/lib/security/ or under $JRE_HOME/lib/security/.
    In some operating systems the java.policy file is in  /usr/lib/jvm/java-7-oracle/jre/lib/security/java.policy. 

vi ... java.policy 

    grant {
    // JMX Java Management eXtensions
    permission javax.management.MBeanTrustPermission "register";
    }; 

    Next, cd to the just-made directory with new GSAC code for your repository, such as gsac-code/src/org/boulder/gsac/ 

    Follow the README file there to complete your GSAC installation. That is README Part 2.