Previous Next

Installing GSAC-WS

Installing the GSAC Web Services Software Package

Check the System Requirements below. You will also need a Database for GSAC, described below.

To install GSAC:

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

mkdir ~/GSAC/

cd ~/GSAC/

Check out the GSAC code from SourceForge (go to https://sourceforge.net/projects/gsac/; and click on 'Code' menu item in the 'Summary Files' menu line, to get the command)
by entering this command:

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

Go to the GSAC core code area:

cd gsac-code/src/org/gsac/

In that new directory is a file called README. This is the first file, Part 1, of two README files to complete GSAC installation, in the GSAC software package. Follow the instructions in the README part 1 file The end of the README Part 1 file tells where to find the README Part 2 file in the GSAC package. Then follow the instructions in README Part 2. Having the README files inside the code package ensures that the installation instructions are consistent with the code package.

See also About a GSAC Installation below.

System Requirements


You can install GSAC web services for a data repository when you have:

A Database for GSAC


An essential part of GSAC installation and operations is a database which you provide, about sites (stations or monuments) in your network, their instruments, and their instrument data files. The GSAC database contains information about sites which you wish to offer online, and about sites' data files which you wish to offer for download. The database must contain up-to-date, complete, and correct information if GSAC services are to represent your data repository correctly. (The database GSAC that reads may also be helpful in managing your data repository, aside from GSAC operations. To manage a data center, a well-designed database is much less error prone, and much more suited to computer operations, than text files such as IGS site logs or SINEX files.)

There are two ways to supply a database for GSAC. First, you can use an exisiting database, if your existing database has all the types of station, instrument, and data file metadata required by GSAC.

See the Prototype GSAC database schema notes, and the Prototype's MySQL schema .sql file, on the UNAVCO GSAC web site to learn about the database fields (columns) required by GSAC to provide its complete suite of web services. The Prototype GSAC database schema notes and dump (.sql) files can help you see if you have adequate types of metadata in an existing database to support GSAC web services.

In the case of using an existing database, you willneed to modify GSAC's PrototypeSiteManager.java and PrototypeFileManager.java files, to use your database table names and field names which are not the same names as in the Prototype GSAC database, to make new code to read from your database. Some changes in coding SQL queries may be required depending on your database design, when it differs from the GSAC prototype schema. The more you are willing to modify the PrototypeSiteManager.java and PrototypeFileManager.java files, and write new Java code using GSAC Java method calls, the more your database schema can differ from the standard GSAC database. The files PrototypeSiteManager.java and PrototypeFileManager.java in the GSAC package are a good place to begin writing new Java code for your new SiteManager and FileManager classes.

Alternately you can make a new database for GSAC for your data center, using the standard or prototype GSAC database schema provided by UNAVCO, unmodified. In that case the "Prototype" Java files in the GSAC package, PrototypeSiteManager.java and PrototypeFileManager.java, should allow installation of a working GSAC using your database in a few a hours, after your new database is populated.

You can create a new GSAC database (lacking any of your data to begin with), using the simple command "source Prototype_GSAC_Database.sql" in a mysql session. See more details three paragraphs below.

This standard or prototype schema for GSAC may be revised in future, but it is quite complete now. The prototype schema supports geodesy data search and discovery, and all the GSAC formats of search results including web pages, and output types such as SINEX and GAMIT station.info files.

The tables and fields (columns) in the prototype GSAC schema show the essential parameters needed for GSAC, and their data types. The prototype design corresponds to common geodesy needs, such as encapsulating station receiver-antenna sessions, and helps avoid error-prone database practices, such as storing latitude values or time values in a character strings. The prototype design includes features to insure reduced problems in an archive database. For example, only actual dates and numbers can be stored in date and number fields. Databases which store dates or numbers as character strings are error-prone and difficult to manage. GSAC uses all times and dates in UTC, in ISO 8601 format.

To create a new MySQL GSAC prototype database using the Prototype_GSAC_Database.sql file:

- if you do not have MySQL, install it. On some Linux systems you can simply do the command
sudo apt-get install mysql-server.
This requests a you to enter a "root" password, which should be a new password just for MySQL, not your Linux system root password.
- start the MySQL server, for example in Linux with "sudo /etc/init.d/mysql restart"
- cd to the folder with the file Prototype_GSAC_Database.sql
- edit the .sql file to change the name of the database, before you use mysql to create the database. You can change all instances of `Prototype_GSAC_Database` to your new db name, something like MyCenter_GSAC_database; the name is not particularly important and will not be visible to GSAC users.
- run mysql as mysql root and create a new MySQL account for GSAC, called for example gsacdbuser.
- run the mysql command line tool, such as, in Linux, "mysql -u gsacdbuser -p"
(MySQL documentation is online, as at http://dev.mysql.com/doc/refman/5.1/en/index.html).
- in mysql (mysql>) do the command source Prototype_GSAC_Database.sql; (including the ;)

This creates a GSAC prototype MySQL database, which is of course initially empty of your GNSS metadata. You will next populate the database with information about your stations, instruments, and data files for download.

UNAVCO can aid and advise about GSAC installations and operations. UNAVCO has a responsibility to ensure that GSAC itself installs properly. UNAVCO can help install GSAC, in some cases including providing a provisional working database with some of your data center's information, if some conditions are met including your use of the provisional database schema. UNAVCO will populate the provisional database with an initial but incomplete set of data, just enough to ensure that GSAC is working.

Completely populating your database, and maintaining it, is necessary to operate GSAC, but doing so is outside of GSAC software installation, and is your responsibility. Also, GSAC does not check data file quality or otherwise manage a data archive. GSAC is web services, not a content management system, and it does not "know" much about geodesy.

About a GSAC Installation


When you have a complete database, using the prototype schema, a working GSAC set of web services may be installed in few hours. In the case where you adapt GSAC to use an existing database, writing your custom SiteManager.java and FileManager.java files may require two days to two weeks by a competent Java programmer.

Installation of GSAC is much easier, faster, and simpler than trying to write code to create the web services already available in GSAC. With GSAC a geodesy or geophysics data center can quickly offer a set of modern web services for remote users to query the data center about sites and instruments, and download data files. And GSAC services are consistent with, and interoperable with, other GSAC repositories.

GSAC is built by compiling Java code, which works on current and recent computers. This approach is needed since GSAC is adapted to work with your local database. A "shrink-wrapped" installer package can't do that.

The disk space used by the GSAC package and a typical working local GSAC is 555 MB. The GSAC Tomcat "war" file to enable GSAC on your Tomcat web applicaiton container is 8 MB. A database to support GSAC, using the prototype schema, is about 10 MB when it includes information about 40,000 data files. GSAC does not copy, duplicate, or store any geodesy data files or metadata. GSAC reads from an existing database. GSAC is not a content management system, or software to run a data repository. GSAC is web services.

Federated GSACs

Two or more GSAC repositories may choose to collaborate to offer a single "federated" GSAC repository which, while maintaining the independence of each individual GSAC repository, allows for merged or joint searches of all the collaborating GSACs at once.

A "federated GSAC" is an independent GSAC and is a new separate GSAC installation. Unlike a basic data repository GSAC, it does not use a local database with information about local data resources. Rather it "knows about" two or more other data repository GSACs, and queries them for information, using their published API search capabiliities. A federated GSAC does not store any data from the collaborating individual GSAC repositories. Among several advantages, this means a federated GSAC always shows the most recent data available from the collaborating individual GSAC repositories.

Installing a federated GSAC is different from installing a data repository GSAC. See the GSAC installation README Part 1 file. A federated GSAC can run on a web server remote from servers at data repositories with databases and FTP/HTML download of data files. Or one web server can run one or more individual (data repository) GSAC repositories, and a federated GSAC, at the same time with no internal connections between them.

Previous Next