Server Installation

There are two methods of installation for the AllegroGraph server, one for administrators and one for non-administrators. Administrators can install the RPM file, and non-administrators can extract the files from a TAR.GZ file and install in a location of their choosing.

Installation from the RPM (Red Hat/Fedora systems)

To execute the commands in this section, you must run the commands as "root".

Obtain agraph-4.7-1.x86_64.rpm from the Franz download page.

Install the RPM:

# rpm -i agraph-4.7-1.x86_64.rpm 

Then run the configuration script:

# /usr/bin/configure-agraph 

The script asks several questions about configuring AllegroGraph. Please see Running the Configuration Script for advice on how to reply to the script. Note that the last few lines of the script show how to start and stop AllegroGraph on your server. These lines will be similar to this example:

You can start AllegroGraph by running:  
/sbin/service agraph start  
 
You can stop AllegroGraph by running:  
/sbin/service agraph stop 

To verify that AllegroGraph is running correctly, open a browser and direct it to the AllegroGraph WebView URL:

http://localhost:10035 

You may substitute your server's IP address for "localhost." The port number is the AllegroGraph port, which defaults to 10035. This opens the WebView interface, which lets you manage users and interactively examine the data in your repositories.

To uninstall AllegroGraph (see also Uninstalling the Server below):

# rpm --erase agraph 

Note that the uninstallation does not remove other directories created by AllegroGraph, which may contain configuration files, catalogs or log files. Those live in /var/lib/agraph, /var/log/agraph, /var/run/agraph and /etc/agraph. Be careful when removing these directories.

Installation from the TAR.GZ (all systems)

The commands in this section do not require "root" access.

Obtain agraph-4.7-linuxamd64.64.tar.gz from the Franz download page. Place it in a directory of your choosing. Then extract the installation files:

$ tar zxf agraph-4.7-linuxamd64.64.tar.gz 

This creates the "agraph-4.7" subdirectory, where the installation script resides. The installation script is "install-agraph". You must provide the path to a writable directory where you want to install AllegroGraph.

$ agraph-4.7/install-agraph /home/joe/tmp/ag42  
 
Installation complete.  
Now running configure-agraph. 

The script asks several questions about configuring AllegroGraph. Please see Running the Configuration Script for advice on how to reply to these questions. Note that the last few lines of the script show how to start and stop AllegroGraph on your server. These lines will be similar to this example:

You can start AllegroGraph by running:  
/home/joe/tmp/ag42/bin/agraph-control --config /home/joe/tmp/ag42/lib/agraph.cfg start  
 
You can stop AllegroGraph by running:  
/home/joe/tmp/ag42/bin/agraph-control --config /home/joe/tmp/ag42/lib/agraph.cfg stop 

Now, the server can be started as shown above:

$ /home/joe/tmp/ag42/bin/agraph-control --config /home/joe/tmp/ag42/lib/agraph.cfg start  
AllegroGraph 4.2 server  
Daemonizing... 

To verify that AllegroGraph is running correctly, open a browser and direct it to the AllegroGraph WebView URL:

http://localhost:10035 

You may substitute your server's IP address for "localhost." The port number is the AllegroGraph port, which defaults to 10035. You will need to your default AllegroGraph username and password to log in. This opens the WebView interface, which lets you manage users and interactively examine the data in your repositories.

Running the Configuration Script

The server installation instructions in the previous two sections link to this section to avoid repeating detailed information about the AllegroGraph configuration script. You should follow these directions until the script exits and then return to the installation instructions.

The AllegroGraph installation script creates an AllegroGraph configuration file (agraph.cfg) with settings appropriate to your environment. The script creates the minimal configuration files to get you started. The configuration file may be edited later.

The configuration script either runs automatically (when installing from the TAR.GZ file) or must be started manually (when installing from the RPM file). It can also be run non-interactively as described below.

The configuration script asks several questions. The default answers are usually adequate, and can be reconfigured later if necessary.

Welcome to the AllegroGraph configuration program.  This script will  
help you establish a baseline AllegroGraph configuration.  
 
You will be prompted for a few settings.  In most cases, you can hit return  
to accept the default value.  
 
Location of configuration file to create:  
[/home/joe/tmp/ag42/lib/agraph.cfg]:  
Directory to store data and settings:  
[/home/joe/tmp/ag42/data]:  
Directory to store log files:  
[/home/joe/tmp/ag42/log]:  
Location of file to write server process id:  
[/home/joe/tmp/ag42/data/agraph.pid]: 

If you are logged on as the root operator when you run the script, it will ask you to identify a non-root user account that AllegroGraph will run under. You can usually take the default value:

User to run as:  
[agraph]:  
 
User 'agraph' doesn't exist on this system.  
Create agraph user:  
[y]: 

The configuration script will then ask for a user name and password to be your AllegroGraph superuser. This account is internal to AllegroGraph, and is not your server logon account. The example below shows the user "test" with password "xyzzy". This is the account expected by the tutorial examples, so it is convenient to create that account now. User account management is easy to perform through the AllegroGraph WebView interface, so this initial user/password combination is easily changed later.

Now you must set up an initial user account for AllegroGraph.  This  
account will have "super user" privileges within AllegroGraph.  
 
SuperUser account name:  
[super]: test  
SuperUser account password:  
xyzzy 

Finally, you are asked for the instance timeout seconds. This is the length of time (in seconds) a database will stay open without being accessed. The default is 604800, which is 60 x 60 x 24 x 7, that is one week in seconds. In contrast, an hour is 3600.

Instance timeout seconds:  
[604800]: 

The value will be written into the agraph.cfg file like InstanceTimeout 604800. If you remove that line from the file, the timeout interval will be one hour (3600 seconds).

The script writes out the agraph.cfg file in the <yourInstallDirectory>/lib directory for the TAR.GZ installation, and in the /etc/agraph subdirectory for the RPM installation. These are the default locations. Make a note of where your agraph.cfg file resides.

/home/joe/tmp/ag42/lib/agraph.cfg has been created.   
 
If desired, you may modify the configuration.  

The script concludes with a display of start and stop commands customized to your installation. These commands vary between the TAR.GZ installation and teh RPM installation, and depending on the location of your AllegroGraph installation directory. Make a note of the start and stop commands for your installation.

You can start AllegroGraph by running:  
/home/joe/tmp/ag42/bin/agraph-control --config /home/joe/tmp/ag42/lib/agraph.cfg start  
 
You can stop AllegroGraph by running:  
/home/joe/tmp/ag42/bin/agraph-control --config /home/joe/tmp/ag42/lib/agraph.cfg stop 

This concludes the discussion of the configuration script. Please return to the installation instructions (above) and continue from there.

Running the configuration script non-interactively

You can run the configure-agraph script non-interactively, which allows you, for example, to run it from another script. To do so you specify --non-interactive on the configure-agraph command line along with additional arguments which provide answers to the questions that the script would have asked. See just above for information on the questions and answers.

If an error occurs, a message is output and the script exits with a non-zero status code. Most arguments have reasonable defaults but some do not and must be specified (either --super-password or --super-password-file must be specified, for example).

Here are the arguments in addition to --non-interactive:

--config-file <path>

Location of the configuration file to create (defaults to $configfile).

--data-dir <path>

Directory to store data and settings (defaults to $datadir).

--log-dir <path>

Directory to write log files (defaults to $logdir).

--pid-file <path>

Where to store the AllegroGraph PID file (defaults to $pidfile).

--runas-user <user>

Which user to run the server under. Only applicable when starting AllegroGraph as root.

--create-runas-user

Tells the script to create the user named in --runas-user if it does not already exists.

--super-user <name>

Name of AllegroGraph-internal user that gets super user privileges. Defaults to 'super'.

--super-password <password>

Password of this super user.

--super-password-file <path>

Allows you to specify a file containing the super user password, so that it doesn't appear in the command line.

The file and directory defaults when running as root are configfile=/etc/agraph/agraph.cfg, datadir=/var/lib/agraph, logdir=/var/log/agraph, and pidfile=/var/run/agraph/agraph.pid. The defaults when not running as root are basedir=~/agraph, configfile="$basedir/etc/agraph.cfg", datadir="$basedir/data", logdir="$basedir/log", and pidfile="$datadir/agraph.pid".

Installing the License Key

When you download the free version of AllegroGraph, no License Key is provided or required. The free version lets you load a maximum of 50,000,000 triples, and has no expiration date.

Franz issues a special License Key to users of the paid version of AllegroGraph. The License Key defines a maximum number of triples and an expiration date for the license, and is issued to an individual client company. Your License Key will be issued by the Franz sales department, and will arrive in your email. A typical license key looks like this (non-working) example:

Licensee Customer Name  
LicenseLimit 1000000  
LicenseExpires 2010-06-16  
<LicenseCode>  
829P93952R9E8P7X4E8W565Z7A2A4Z592E4W5E49693P9K325X296S3R945A789D4  
S843K9455787K3R3A2K6Z6N8K8V6V658A3V3D293H8X5S7X3V9A4R6533979V246V  
6J8Y3T928MA69B928R7E4D8C7C4T6X9F28626Z448E986R6E9B6F4S9J9U6H8A7Q8  
S324C67783Y89495Q8W867B7S349Q6C6T5W42A59P8Q5M967R5B554C2K3Q424T  
</LicenseCode> 

The "License Key" consists of all four fields: the Licensee, LicenseLimit, LicenseExpires and LicenseCode. They must all be present in order for the Key to work. The first three values reflect the terms of your contract with Franz. The LicenseCode verifies the other values.

To install your License Key, copy the entire block of text (Licensee, LicenseLimit, LicenseExpires, and LicenseCode) and paste it into your agraph.cfg file. (In the examples above, the agraph.cfg file was located at /home/joe/tmp/ag42/lib/agraph.cfg.) The License Key can go into any part of the file as long as it is outside of a catalog definition. Save the file and restart the AllegroGraph server.

If there is any problem with your License Key, AllegroGraph will revert to the behavior of the free version. It will return an error when you first exceed 50 million triples and every time thereafter.

Uninstalling the Server

When installing from a tar.gz file, it is not necessary to uninstall the older AllegroGraph versions from a computer, but when installing from an RPM distribution, it is required unless you install the new distribution with the -U option. (You may wish to uninstall earlier versions installed with tar.gz even though it is not necessary to save space and reduce clutter.)

The main issue with uninstalling is ensuring you do not delete files or directories that you may need with the new installation or, if you are ceasing to use AllegroGraph, you may need if you start using it again.

You should save:

• The settings/ directory

• The agraph.cfg file from the lib/ directory of the existing installation

• The transaction logs (generally on production servers only)

It is recommended that you copy all files and directories you wish to keep to a new directory named somthing like agraph-vXXX-saved-files/ (where XXX is the version number without dots, like v45). This directory should not be a subdirectory of any AllegroGraph directory. Also, tools described in Backup and Restore like agraph-backup can be used to save the contents of the settings directories and also databases.

RPM uninstall

Once everything is saved, you uninstall a RPM installation with the command

# rpm --erase agraph 

This command will not remove directories created by AllegroGraph, which may contain configuration files, catalogs or log files. Those live in /var/lib/agraph, /var/log/agraph, /var/run/agraph and /etc/agraph. You should already have saved what you need, but make sure before deleting these remaining directories.

tar.gz uninstall

You uninstall by deleting the AllegroGraph installation directory using standard OS tools. On UNIX, for example, you would do so with a command like

% rm -rf my-old-allegrograph-install-directory/ 

Note that unlike RPM uninstallation, this command removes everything from the directory and the directory itself. There is no way to recover files or directories which you intended to keep but which where not copied elsewhere once the command is executed.

You should also remove other directories pointed to by the old configuration file such as TransactionLogDirs and TransactionLogArchives etc. once you have saved material in those directories you wish to keep.

Client Installation

This section describes installing the Python, Java and Jena clients to AllegroGraph.

Python Client

The tutorial examples can be run on a Linux system, running AllegroGraph and Python on the same computer ("localhost"). The tutorial assumes that AllegroGraph and Python 2.5 have been installed and configured using the following procedure.

In addition to Python, AllegroGraph also requires the Python cjson and pycurl libraries. To determine if these packages are installed on your system, try:

rpm -q python python-cjson python-pycurl 

For most Linux systems, the installation command is:

sudo yum install python python-cjson python-pycurl 

For Ubuntu systems, try:

sudo apt-get install python python-cjson python-pycurl 

These installations will require administrator privileges.

If your distribution does not offer these libraries then installation from source is recommended. See your system administrator.

The AllegroGraph Python client files are in

agraph-4.7-client-python.tar.gz 

which you may obtain from the Franz download page. Place it in a directory of your choosing. Then extract the Python Client files:

$ tar zxf agraph-4.7-client-python.tar.gz 

This creates the agraph-4.7-client-python subdirectory.

Edit your agraph.cfg configuration file (agraph.cfg). You'll find it in the <yourInstallDirectory>/lib directory for the TAR.GZ installation, or in the system's /etc/agraph/ directory for the RPM installation. These are the default locations. Make a note of the port number, which defaults to 10035.

Port 10035 

In this file you'll see an entry describing the RootCatalog. It will be similar to this:

<RootCatalog>  
  Main /yourInstallDirectory/data/rootcatalog  
</RootCatalog> 

The Python tutorial examples require this RootCatalog plus an additional catalog subdirectory that you must add to the config file. The tutorial example code expects to find a catalog called "python-catalog" so please don't change the name. You can specify any writable directory as the location of the repository data.

<Catalog python-catalog>  
  Main /yourInstallDirectory/data/python-catalog  
</Catalog> 

You'll have to stop and restart the AllegroGraph Server to force it to load the edited configuration file.

You'll need to set a PYTHONPATH environment variable. This binds the variable PYTHONPATH to the location of the src2/ subdirectory where you unpacked the Python client tar file. From a 'bash' prompt:

export PYTHONPATH=/yourPathway/agraph-4.7-client-python/src2 

If you are using non-default values for the port number, user name or password, you will have to edit tutorial_examples_40.py to enter these values. Navigate to the "agraph-4.7-client-python/tutorial" directory to edit the file. Be sure that the AG_PORT variable is set to your AllegroGraph port number, and that the AG_USER and AG_PASSWORD variables reflect the name and password of your AllegroGraph super user account. Save the file.

To test the installation, run the tutorial examples:

$ python tutorial_examples_40.py all 

The command window will fill with output from the example functions. The examples run for about 2.5 minutes and touch most of AllegroGraph's features. To run a specific example, enter its number after the file name, that is:

$ python tutorial_examples_40.py 13 

The explanations of these tutorial examples are in the AllegroGraph Python Tutorial.

If the tutorial examples throw an error in example6(), see the discussion of Session Port Setup.

Java Client

The tutorial examples can be run on a Linux system, running AllegroGraph and running the Java Client as an Eclipse project on the same computer ("localhost").

The AllegroGraph Java client files are in

agraph-4.7-client-java.tar.gz 

which you may obtain from the Franz download page. Place it in a directory of your choosing.

Open your Eclipse development environment, and import the Java Client as an Eclipse project. You may import the project directly from the tar.gz file. From within Eclipse, select File > Import. In the Import dialog box select "Existing Projects into Workspace" and click Next. Browse to the location of the archive file and click Finish. There is no need to unpack the file. The new project will be called "AllegroGraph 4.7 Java Client."

Edit your agraph.cfg configuration file (agraph.cfg). You'll find it in the <yourInstallDirectory>/lib directory for the TAR.GZ installation, or in the system's /etc/agraph/ directory for the RPM installation. These are the default locations. Make a note of the port number, which defaults to 10035.

Port 10035 

In this file you'll see an entry describing the rootcatalog. It will be similar to this:

<RootCatalog>  
  Main /yourInstallDirectory/data/rootcatalog  
</RootCatalog> 

The Java tutorial examples require this RootCatalog plus an additional catalog subdirectory that you must add to the config file. The tutorial example code expects to find a catalog called "java-catalog" so please don't change the name. You can specify any writable directory as the location of the repository data.

<Catalog java-catalog>  
  Main /yourInstallDirectory/data/java-catalog  
</Catalog> 

You'll have to stop and restart the AllegroGraph Server to force it to load the edited configuration file.

Navigate to the AllegroGraph 4.7 Java Client/src/tutorial/ directory. If you are using non-default values for the port number, user name, or password, you will have to edit TutorialExamples.java. Be sure that the SERVER_URL variable is set to the URL and port number of your AllegroGraph server, and that the USERNAME and PASSWORD variables reflect the name and password of your AllegroGraph super user account (created by the installation script). Save the file.

To test the Java Client, run the TutorialExamples.java file (within Eclipse). Run the file using a single argument of "all". The console will fill with output from over twenty tutorial examples. The examples run for about 2.5 minutes and touch most AllegroGraph features. To run a specific example, enter its number instead of "all".

The explanation of these examples is in the AllegroGraph Java Tutorial.

If the tutorial examples throw an error in example6(), see the discussion of Session Port Setup.

Jena Client

The Jena client is a variant of the Java client. Simply follow the Java client setup (above). When you have imported the project into Eclipse, run the JenaTutorialExamples.java file instead of the TutorialExamples.java file.

The explanation of these examples is in the AllegroGraph Jena Tutorial.

Session Port Setup

If you connect to AllegroGraph on a remote server (using an SSH client, for example), it is possible that you will see a connection error when you reach the sixth tutorial example. The solution is to add a SessionPorts entry in agraph.cfg, specifying a range of ports for AllegroGraph to use, as in:

Port 10035  
SessionPorts 9091-9100 

Any range of unused ports will do. Ten ports are sufficient for initial installation and testing. Don't forget to restart AllegroGraph after editing the config file.

Then you must configure your SSH client to map the same range of ports from your local computer to the remote server. Local port 9091 must map to remote port 9091, etc. This should clear up the connection issue.

If the problem persists, it is possible that a firewall is obstructing the required ports.

If you are running AllegroGraph and the client on the same "localhost" computer, the allocation of session ports is handled automatically and transparently.