Note: If you are reading this as the INSTALL
text file
in the Ganymede distribution directory, you are missing a bunch of
hyper-links that link to extra information about many topics discussed.
If you can, view this document with a web browser as
doc/install.html
.
-1. Quick Install Cheat Sheet |
I really, really, really recommend you try and read through this whole document to learn how to install Ganymede, but if you absolutely, positively refuse to read something this long, here is the thumbnail sketch:
Pretty easy, huh? Of course, the devil is in the details, and to learn about those, you'll want to read the rest of this file in detail, as well as whatever documentation comes with any schema kit you may be using.
0. Overview |
Ganymede is a client-server system with three distinct components that need to be installed in order to use it. These parts are the Ganymede server, the Ganymede client suite, and the schema kit.
The server acts as a central repository and control system, storing your network directory information in its built-in object database and updating various network services when changes are made. The server is designed to be installed on a UNIX system, and depends on Java and scripting languages such as Perl or Python to carry out its internal and external operations.
The Ganymede client suite includes a variety of command-line, web, and GUI clients that can connect to the Ganymede server over the network. The Ganymede distribution includes a script to install these clients on UNIX systems, but most of the clients can be accessed over the web from a PC or Macintosh with a suitable version of Java installed.
A schema kit contains all the pieces needed to turn the raw Ganymede engine into a custom-tailored database system shaped to fit a particular application. A schema kit defines the kinds of data to be held in the Ganymede server's database, custom logic to provide intelligent management of that data, and external scripts that take the data from the Ganymede server and integrate it into your network. Assuming that you don't want to try and develop your own database definition from scratch, you'll want to download a pre-built schema kit for use with your Ganymede server.
The Ganymede distribution that you downloaded includes everything you need to install the server and client suite, but does not include a schema kit. You will need to visit ftp://ftp.arlut.utexas.edu/pub/ganymede/ or one of the mirrors listed at http://www.arlut.utexas.edu/gash2/Download.html in order to download a schema kit.
This document will cover the installation of Ganymede from start to finish, using the 1.0 version of our newly developed userKit as an example. Any other schema kits that are developed will have some differences, but will likely be installed and used in similar ways.
1. Requirements |
The Ganymede server is designed to be easy to install for anyone running a Unix, Linux, or Mac OS X system with Java, Perl, Bourne Shell, and Apache Ant installed. Ganymede 2.0 is designed to work with Java 6 or later. You will need the full Java Development Kit (JDK or SDK) on your UNIX server so that you can compile any custom plug-in classes.
Ganymede has no dependencies on any Java classes other than what comes with the JDK or in the Ganymede distribution.
You can download Oracle's official release of the Java platform for Mac OS X, Linux, Windows or Solaris at http://www.oracle.com/technetwork/java/javase/downloads/index.html/. The Ganymede server has primarily been developed and tested on Linux, but the Ganymede clients have been successfully run on Solaris, Linux, Windows XP, Vista, Mac OS X Jaguar and later, FreeBSD, AIX, HP/UX, and others.
If you're running Linux, your distribution probably provides an up-to-date version of OpenJDK, which Ganymede is also fully compatible with.
As well as Java, you will need /bin/sh, Perl 5.003 (or later), and Apache Ant to build and install the Ganymede software. The Ganymede distribution, server and client, is designed to be unpacked and installed on a UNIX-style system.
There are command line client scripts for Unix style systems (ganymede, ganymedeAdmin, xmlclient), but most of your users will probably use Java Web Start to run the graphical clients on their desktops.
To run the Ganymede clients in a web browser on a desktop PC running some version of Windows, you will want to download and install version 6 or better of the Java Runtime Environment (JRE) for Windows. Oracle's Java Runtime Environment includes support for Java Web Start, a code module that will allow you to launch the Ganymede client directly from your choice of web browser.
In order to user Java Web Start, you'll need a web server on your network that can serve the clients to your network. We typically run a limited web server on the same system that we run the Ganymede server, but you don't have to.
We don't provide any files for launching the Ganymede client from the Mac, Windows, or Linux GUI environments, but Java Web Start will offer to create desktop icons to run the Ganymede client the first time your users run Ganymede from the web.
2. Configuring and Building the Distribution for Your Site |
The Ganymede 2.0 distribution comes without any code precompiled for you. In order to get everything compiled and ready for you to install, you will need to run the configure script in the distribution directory. The configure script is a custom-written Bourne shell script which searches around on your system to find Perl, Java, and the Apache Ant build tool, and then uses that information to bootstrap the rest of the configuration process.
One of the first things configure will do is to build the Ganymede software for you, and create the jar files that you will use to deploy Ganymede. When configure compiles Ganymede for you, it will create SSL key and certificate material that is unique to your installation. The SSL key is placed into the server's ganymedeServer.jar file, and the matching certificate material is placed into the client's ganymede.jar and the admin console's ganymedeAdmin.jar files. In this way, your Ganymede client and admin console will be tied to your Ganymede server. By generating unique keys and certificates for each installation, you can be assured that the clients you distribute are talking to your Ganymede server.
After building the Ganymede software, configure will copy a few scripts from the scripts/ directory into the top-level distribution directory, editing them to set the proper location for the Perl interpreter on your system, and otherwise setting everything up for you to proceed with installation. These scripts are installClient, installWeb and installServer. You will use these scripts to install the command-line UNIX clients, the web applet clients, and the server itself, respectively.
3. Installing the Server |
Installing the Ganymede server is the next thing to be done after you have unpacked and configured the distribution. You should plan on installing the Ganymede server on a system that has Java and Perl installed, and which has a web server available to provide downloads of the Ganymede client applets for your users who will be accessing Ganymede through a web browser.
The installServer script produced in the distribution directory by the configure script will ask you a series of questions, then install the Ganymede server in its own directory.
These questions include the following:
This is just asking for the directory that contains your system's java binaries. The configure script will attempt to provide a reasonable default for this question, but you may have to correct it if you have more than one version of java installed on your system and it chooses wrong.
This question is asking where you want to install the server at in your UNIX system's filesystem. The Ganymede server tree should not be installed in a location that is accessible to the average user, as all of your directory data is held in this directory tree. There is no default answer for this question, so you will have to pick a location. You can use either absolute or relative directory names here.
Note that when you install the server, the installServer script customizes the server installation with the paths where you have installed the server. If you ever decide to move the server in your filesystem, you will need to create a symlink at the old location to allow the old paths to resolve properly, or you will need to go through the various scripts and files and make sure that any reference to the old path has been updated.
This information is used to configure the RMI system in the server and in the stopServer and xmlclient clients that are installed into the server tree. This may be an i.p. address or a fully qualified DNS host name. The installServer script will provide the name of the system you are on as a default.
Note that the Ganymede server needs to know a name or address for the server that will resolve to an i.p. address that is accessible by your clients.
By answering this question with either a fully qualified DNS name or a network-accessible numeric address, the Ganymede server will be able to generate a proper network address for clients to use.
If you discover after installing the server that you need
to change the name that the Ganymede server uses to identify
its network address, you can edit
the ganymede.properties
file and change the ganymede.serverhost
definition to something that will resolve to a network
accessible address.
The RMI registry is a network lookup service that is used to initialize communications between the Ganymede clients and the Ganymede server. By default, port number 1099 is used for RMI registration. If you are running certain other Java services, you may already have an RMI registry running, in which case you should pick another port number to run the Ganymede registry on. You may want to use 1100, 1101, or another non-used tcp port.
The answer to this question will control what TCP port number the Ganymede server uses to listen for communications from clients once the clients have logged in. By default, communications to this port will be SSL encrypted.
The Ganymede server is able to send out email in response to a variety of system events. If you don't want the Ganymede server ever to send email, you can leave this blank. Otherwise you should enter the DNS name or IP address of a mail server that will accept unauthenticated SMTP mail from the Ganymede server.
This question is asking you what Ganymede should put in the 'From:' field of mail that it sends out in response to system events. In many configurations, the Ganymede server will send out mail using the name of the user whose action triggered mail, but for things like system shutdown/restart, etc. it needs an email address to go by. If this email address is not valid, users who reply to system event mail from Ganymede will have their replies bounce.
The default 'supergash' name is probably okay here, but you can change it if you want. Note that you will be able to create additional admin accounts with superuser privileges later if you like, but you need to have this initial, generic superuser account to bootstrap the system.
This password provides complete access to the Ganymede server's database, and is necessary for a variety of system operations.
The monitor account is an unprivileged (non-admin end user equivalent) user that is granted the privilege to login to the Ganymede admin console and monitor the server's performance and activity logging, without being able to stop the server, edit the schema, or trigger server tasks.
The password for the monitor account.
Once you answer all these questions, the installServer script will proceed to install the Ganymede server in the location specified.
Once installed, you will have a server directory that contains a number of directories, some documentation files, and a ganymede.properties file that the Ganymede server executables use as a configuration resource.
The bin/ directory contains:
The db/ directory contains:
The jars/ directory contains the compiled java classes that actually comprise the Ganymede server and the Java-based stopServer and xmlclient clients.
The doc/ directory contains copies of all of the Ganymede documentation.
The backups/ directory is used by certain schema kits to store backup copies of any networking files written out by the schema kit's builder tasks. These back up copies will be written into subdirectories that are named by date, and which will be automatically zipped up once a day. Nothing in this directory is used by the Ganymede server for any purpose other than your peace of mind in case you have a problem with the Ganymede server and need to get back an old copy of a passwd or nis file in a pinch. If you don't want to spend the disk space on archival copies of your network data files, just edit the ganymede.properties file and comment out the 'ganymede.builder.backups' property.
4. Installing A Schema Kit |
Once you have the server installed, you can proceed to install a schema kit, which will customize and configure the server for your requirements.
When you download and unpack a schema kit, you should find documentation that will walk you through the installation process. Essentially it comes down to running a installKit script, which will ask you where you installed your server and where Java is, and will then create a schema directory under your server directory. This directory should include:
The most important of these as far as the server is concerned is the custom.jar file. Once that file is in place, you can proceed to run the Ganymede server, which will then start up and find the extra classes needed to run the server with your schema kit.
The schema kit that you install should include a README that will talk in great detail about the operational aspects of running the server with that schema kit installed. This will include but is not limited to what sort of data is written out to disk when transactions are committed in the server, and how that data is integrated into the network environment.
For now, however, we are going to continue with a generic discussion of how one runs the server, how one typically loads data into the server, etc. For further details on all of this works with the schema kit you choose to use, see the schema kit README file.
5. Running the Ganymede Server |
Once you have installed your schema kit, you can go ahead and run the server. You do this by running the runServer script in the server's bin/ directory.
The Ganymede server is a pure Java application, so when you run it, you are really running your platform's java execution environment (which may be an interpreter, a JIT compiler, or an advanced hybrid). Java doesn't provide a lot of access to operating-system level functionality, so the Ganymede server doesn't know how to detach itself from your terminal window or console, and it doesn't know how to respond gracefully to kill signals.
The Ganymede 2.0 runServer script takes care of detaching the
Ganymede server from the console and automatically captures the
server's stdout and stderr streams to the server.log
file
in the server installation directory.
You can view the server's log as the server runs with the
tail
command, using the -f
option, as
follows:
server% tail -f server.log
That way, if your window is killed or you absent-mindedly hit
ctrl-c, you will only kill off the tail
command. You
want the server itself to run in the background, undisturbed.
The installServer script is pre-configured with various options to run the Ganymede server smoothly on your system. If you look at runServer, however, you will see that there are a number of ways you can edit the runServer script to tweak the Ganymede server's behavior.
Of particular interest in this regard are the
-resetadmin
and the -logrmi
parameters.
These are both documented in the runServer script itself, but it is
worth discussing them here. The -resetadmin
parameter
causes the Ganymede server to reset the administrative 'supergash'
password in the system to the value defined in the server's ganymede.properties file.
It is reasonable to remove the 'ganymede.defaultrootpass' property
from the ganymede.properties file if
you don't want to leave your Ganymede 'root' password lying around in
plaintext, but if you ever forget the password, you'll want to keep
the -resetadmin
parameter option in mind. You should not
remove the ganymede.defaultrootpass property until the server has
successfully started up and created its ganymede.db file at least once,
however.
If the -logrmi
parameter is used, the Ganymede server
will log all network calls made by clients to a file titled
debug.log.. This may degrade performance very slightly, but it will
provide an invaluable trace and exception log if the server ever hangs
or crashes. Unless you know you will never need to worry about the
possibility of exceptions in the server, I'd recommend you leave the
-logrmi
parameter as you find it. The
installServer script will install the runServer script with
-logrmi
enabled. If you want to have the RMI log placed
somewhere else, you can use logrmi=filename
rather than
accepting the default RMI log file that -logrmi
will
generate for you.
While the server is running, you should see one Java process running, that being the Ganymede server. All builds and other background activity are done with threads in this single process.
When you want to shut the server down, you can send the running Java process a QUIT signal directly with the kill command on Unix-type systems, or you can order it to shut down from the Ganymede admin console (which we'll talk about below), or by using the stopServer script in the server's bin/ directory.
Whichever you choose, the server will kick any active users off the system, consolidate its database to disk, wait for any running builder tasks to complete, and then cleanly shut down. The Ganymede server is designed to recover smoothly on restart if it is forcibly killed or if the system crashes or is rebooted at any point during its execution, but if the server is not shut down cleanly, it might spend a bit of time consolidating data from its journal when it starts up again.
6. Loading Data Into the Server |
Now you have installed the server, integrated a schema kit into the server directory, and started the server running. You can now proceed to use the schema kit to load data into the server.
When you first run the Ganymede server, the server will look in its db/ directory for its ganymede.db file. When it doesn't find it, it will initialize itself with its default database configuration. The Ganymede server will only know about those objects and fields that it uses for its own operations. Before the Ganymede server can handle the data for your network's directories, you will need to define your custom object and field types in the Ganymede server.
The Ganymede admin console has an 'Edit Schema' menu item which you can use to bring up a graphical schema editor. With the schema editor, you can define new object types and define fields within the object types. Designing and implementing a new schema definition is a bit involved, and is beyond the scope of this installation guide.
Fortunately for you, though, you're using a schema kit, so we will just let it do that work. For the rest of this discussion, we'll pretend you have downloaded and installed a schema kit that is almost entirely not unlike the userKit schema kit that we are releasing with Ganymede 2.0. If you are not using that schema kit, you'll have to improvise along the same lines.
If you look in the schema/ directory that the schema kit's installKit script placed in your server directory, you should see a loader.pl script and a schema.xml file. The loader.pl script is designed to take the database definition information contained in the schema.xml file and combine it with your data to create a data.xml file that you can then load into the Ganymede server.
Actually running the loader.pl script should be relatively straight forward, but you will want to consult the schema kit's documentation for information on what sort of data it can import, what configuration options the schema kit's plug-in logic classes support, and the full details on integrating Ganymede and that schema kit into your environment.
For now, we'll just assume that loader.pl has produced a data.xml file that is formatted according to the Ganymede XML File Format Guide. Now all you need to do is cd to your server's top-level directory and run
server% bin/xmlclient schema/data.xml
This will cause the xmlclient to log into the server and upload both the schema kit's schema definition and your data to the server. xmlclient will produce some output while it runs, but it is designed for speed over interactivity, and so it may go quiet for long periods of time while it waits for the server to chew through the XML that it has submitted. If you like, you can run the Ganymede admin console before starting xmlclient and actually watch as the xmlclient talks to the server and creates all your objects in the database.
If all goes well, you should expect to see a bunch of messages about it editing the server's schema and then creating a bunch of objects from your data. If something goes amiss, you should see some information telling you where in the xml data stream it found something that it didn't like. With luck, a little hand-editing of the data.xml file will let you put things right and try again.
There is quite a lot more to say about how the schema kits are constructed and how they operate, but this isn't the place for it. Check in the schema kit for documentation on operations with the schema kit. For now, be aware that the data.xml file generated by the userKit's loader.pl script is designed to initialize the Ganymede database from scratch, and not to import new data to a server that has already been up and running with data for awhile. For the full story on how to write XML files to do data editing in the Ganymede server, see the xml.html file in the doc/ directory.
7. Installing UNIX Client Files |
The Ganymede system has two primary clients, the Ganymede GUI client and the Ganymede admin console. Both can be run from a UNIX command line with a shell script that will run java on them, or from a web browser with support for Java 6 or better.
We have provided an install script for installing the Ganymede clients on a UNIX system. installClient will prompt you for the name of the machine that will be running your Ganymede server, and the directory which will contain the client. The install script will then customize and install scripts for you so that the end-user client and admin console can easily be run.
Don't try to install the client files and the server into the same directory.. the two are meant to be installed separately, in separate directories. This is important because the server files need to be kept out of the reach of non-privileged users, while the client files are intended to be available for anyone to run.
Note that we don't provide any kind of script to install the Ganymede clients on a Windows or Macintosh system directly, but you can use a JNLP launcher like Java Web Start to achieve this. See the Web Server Configuration section of this document, below, for details on supporting JNLP launch.
In general, you should be able to run the Ganymede clients on any platform that supports Java 6 or better, as the clients are written in pure Java. The Ganymede clients are dual-mode, and will work both as an applet and as a command line application. If you are trying to run the clients on a platform that supports Java 6 but which doesn't have a JNLP launcher available, you may want to examine the ganymede and ganymedeAdmin launch scripts installed by the installClient script and create appropriate translations of the launch scripts for your platform.
8. Prepare web access clients |
The installWeb script is used to install, on your UNIX system, the html, cgi, JNLP and java files needed to support client access to Ganymede from a web browser. When you run installWeb, it will ask you a small number of questions, including the following:
The answer to this question is used to configure the applet launch page that your users will access to run the Ganymede applets. This should be the name of the system on which you are going to run the Ganymede server.
As with installClient and installServer, this is asking you for the port number that the Ganymede server is placing its internal rmiregistry on. This number must match the one used when you installed the server.
This is asking for the name of a directory in which to install the web access files. If this directory does not exist, it will be created in the directory containing it. This directory will need to be mappable to a url by a web server running on the same machine that will be running your Ganymede server.
This question is asking what URL the installed web access files will map to in your web server. The installWeb script needs this information in order to configure the Java Network Launch Protocol (JNLP) files for the Ganymede client and admin console for use with the Java Web Start launch manager.
If you don't get this right when you install the clients, the Java Web Start option will not work properly. You can edit the installed client.jnlp and console.jnlp files to fix this after the fact, if need be.
This is asking for the directory that contains (or will contain) the Ganymede text mode clients, in particular xmlclient. The directory containing xmlclient must be accessible by the user account that your web server runs under, so that the ganypass.pl CGI script can properly communicate with the Ganymede server.
installWeb will configure and install a bunch of files into a designated directory, including an index.html file, a couple of jar files containing the classes for the Ganymede gui client and admin console, a CGI script that will allow your users to change their passwords through their web browser using an HTML file, and various support files. These files are customized during installation to point to the proper location for your Ganymede server.
With Java RMI-using applets, it is typically necessary to download the applets from a web server running on the same machine as the RMI server, so that the default restrictions on an unprivileged applet suffice to allow a network connection to be made back to the RMI server. The Ganymede 2.0 applets are signed, however, so you are not required to run a web server on the same machine as your Ganymede server, as you were for the Ganymede 1.0 series. Running a web server on your Ganymede server may make it easier to redeploy the client jar files and etc., if you need to upgrade things later, though.
Wherever you decided to serve the Ganymede clients from, you'll probably want to set up an appropriate path or alias. If you are using Apache, you might set up an alias in your httpd.conf file that maps a URL path like "/ganymede" to your web client directory. Whatever directory you are serving Ganymede files from should be configured to allow running CGI scripts with the extension '.pl', to support the password change CGI script that is installed in that directory, if you want that. If you want to support the Java Web Start launch option, you will also need to configure your web server to recognize .jnlp files as being of MIME type application/x-java-jnlp-file. See section 9, below, for details on this.
Once the web server has been configured and the web clients installed, your users will be able to access your web client directory to run the Ganymede applet launcher (through the index.html file), or to run the Ganymede password change CGI script, ganypass.pl. The ganypass.pl script is useful because it allows any web browser that supports HTML forms to be used to change a user's password, whereas the full Ganymede client launcher requires both JavaScript and Java support.
If you do want your users to be able to run the full Ganymede client, you will need to be sure that their web browsers are configured properly, either with support for running Java 1.6 applets directly, or for passing a JNLP file to Java Web Start.
IMPORTANT NOTE: whenever you run applets from the launch page using the 'Native' mode, the applets can only run as long as the log-in applet is still displayed in the web browser. If you close the main browser window or click to a different page (either by following a link or by clicking back on the browser), the applet will be shut down. Both the Ganymede client and admin console have been written so that this shut-down is handled in an orderly fashion, but the shut-down is unavoidable, so be sure not to disturb the applet frame while you are using the client or console.
In general, we recommend the 'Java Web Start' launch method above all others, but you do need to do a bit more configuration work to support this option.
9. Configure your web server to support Java Web Start |
Ganymede supports the use of Java Web Start (see http://en.wikipedia.org/wiki/Java_Web_Start) to handle launching the Ganymede client and admin console. With Java Web Start, your users should be able to run the Ganymede client applets on their Windows, Mac, or Linux desktops without needing to bother with a web browser.
In order to support any JNLP launcher service on the client, your web server has to be configured to identify the proper MIME type for the Java Network Launch Protocol (.jnlp) files that tell the Java Web Start system how to manage the Ganymede clients.
These days, all web servers you are likely to use should know
the appropriate mime type for JNLP files, but if you have problems
launching the clients, make sure that your web server environment
knows to assign .jnlp
files the
application/x-java-jnlp-file
MIME type.
In addition to the server-side configuration, your users' web
browsers must be configured to run the JNLP launcher when a
resource of MIME type application/x-java-jnlp-file
is
downloaded. The Java Web Start package should take care of that
automatically on Windows and Mac OS X, but on a Linux or FreeBSD
system, your users may have to do some manual configuration.
If you don't configure your server and your users' clients for the use of JNLP, your users will not be able to use the Java Web Start launch option, but they should still be able to run the Ganymede clients from their web browser, with somewhat less convenience.