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.

From the RPM (Red Hat/Fedora systems)

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

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

Install the RPM: 

# rpm -i agraph-6.1.5-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.

Unless you are using the free version (which allows up to 5 million triples), you must add a license key to the configuration file. See below for more information. If you are using the free version, go to Client Installation below.

From the TAR.GZ (all systems)

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

Obtain agraph-6.1.5-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-6.1.5-linuxamd64.64.tar.gz

This creates the "agraph-6.1.5" subdirectory, where the installation script resides.

Running the installation script on untarred files

The installation script is install-agraph. It takes the path to a writable directory where you want to install AllegroGraph as a required argument. It also accepts the following options:

--no-configure
If supplied, AllegroGraph will be installed in the argument directory but the configuration program will not be run. This allows installing and configuring to be done without user input (by running the configuration script non-interactively, as described below). You can also run the configuration program, agraph-configure, interactively after the non-configuring installation finishes (as described in the Configuration section below).
--supersede
If supplied, an existing installation directory specified as the required argument to install-agraph will be overwritten without further warning or request for confirmation.
--help
Print information on the options to install-agraph.

Here is how a typical interactive installation is initiated: 

$ agraph-6.1.5/install-agraph /home/joe/tmp/ag6.1.5  
 
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/ag6.1.5/bin/agraph-control --config /home/joe/tmp/ag6.1.5/lib/agraph.cfg start  
 
You can stop AllegroGraph by running:  
/home/joe/tmp/ag6.1.5/bin/agraph-control --config /home/joe/tmp/ag6.1.5/lib/agraph.cfg stop

Now, the server can be started as shown above: 

$ /home/joe/tmp/ag6.1.5/bin/agraph-control --config /home/joe/tmp/ag6.1.5/lib/agraph.cfg start  
AllegroGraph 6.1.5 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.

Unless you are using the free version (which allows up to 5 million triples), you must add a license key to the configuration file. See below for more information. If you are using the free version, go to Client Installation below.

Configuration

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 program which configures AllegroGraph is configure-agraph. It is called automatically by install-agraph described above unless the --no-configure option is specified. It can be called to configure an unconfigured AllegroGraph (this is necessary when AllegroGraph is installed with the RPM method). In this section we describe interactive configuration. See below for information on running configure-agraph non-interactively.

NOTE: The Linux user account ("agraph") and the AllegroGraph superuser account ("test:xyzzy") are not interchangeable: the first is a regular operating system account, the second is used only by AllegroGraph and has nothing to do with the operating system. Each has a specific role to play.

  • If you are logged in as root, the installation script will prompt you to name a non-root account for AllegroGraph to run under. (It would be a security risk to let AllegroGraph run as root.) This account defaults to "agraph" and is designated in agraph.cfg as "RunAs agraph". The "agraph" account has no password and is used only by AllegroGraph server.

  • The installation script will always prompt for the name and password of your initial AllegroGraph superuser. (In the paragraphs below this user appears as "test" with password "xyzzy".) This is the account that gives access to your triple stores. It appears in your initial agraph.cfg as "SuperUser name:password". The first time AllegroGraph runs, it will use this line to create the superuser account. After that you can delete the entry from the configuration file for added security.

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 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/ag6.1.5/lib/agraph.cfg]:  
Directory to store data and settings:  
[/home/joe/tmp/ag6.1.5/data]:  
Directory to store log files:  
[/home/joe/tmp/ag6.1.5/log]:  
Location of file to write server process id:  
[/home/joe/tmp/ag6.1.5/data/agraph.pid]:  
Port:  
[10035]:

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  
SuperUser account password (again):  
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/ag6.1.5/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 the RPM installation, and depending on the location of your AllegroGraph installation directory. Make a note of the start and stop commands for your installation (see Server Control in Server Configuration and Control for more information on the agraph-control program). 

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

This concludes the discussion of running the configuration script interactively. Please return to the installation instructions (above here for RPM installation, above here for TAR.GZ installation) 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). This argument corresponds to the LogDir top-level directive in the config file. See the description in Server Configuration and Control.
--pid-file <path>
Where to store the AllegroGraph PID file (defaults to $pidfile). This argument corresponds to the PidFile top-level directive in the config file. See the description in Server Configuration and Control.
--runas-user <user>
Which user to run the server under. Only applicable when starting AllegroGraph as root. This argument corresponds to the RunAs top-level directive in the config file. See the description in Server Configuration and Control.
--create-runas-user
Tells the script to create the user named in --runas-user if it does not already exists.
--port
Specifies the default port to be used by the server. Defaults to 10035. This argument corresponds to the Port top-level directive in the config file. See the description in Server Configuration and Control.
--super-user <name>
Name of AllegroGraph-internal user that gets super user privileges (defaults to 'super'). This argument corresponds to the SuperUser top-level directive in the config file. See the description in Server Configuration and Control.
--super-password <password>
Password of this super user. See the SuperUser top-level directive in Server Configuration and Control. The password is specified in that directive along with the super user name.
--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  
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"  
pidfile="$datadir/agraph.pid".

Return to configuration description above or to the installation instructions (above here for RPM installation, above here for TAR.GZ installation) and continue from there.

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 5,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 TAR.GZ installation example above, the agraph.cfg file was located at /home/joe/tmp/ag6.1.5/lib/agraph.cfg. The default location in the RPM installation is /etc/agraph/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 5 million triples and every time thereafter.

Now go to Client Installation below.

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:

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 Python client works with Python 2.6, 2.7 and 3.3+.

The AllegroGraph Python client files are in agraph-6.1.5-client-python.tar.gz which you may obtain from the Franz Agraph client download page. Download and place it in a directory of your choosing. Then extract the files: 

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

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

Requirements

Python versions 2.6+ and 3.3+ are supported.

The Python client depends on a few third-party Python modules. These will be downloaded from PyPI_ during installation and compiled on the target systems. Since some of the required packages use native extensions, it is necessary to have a proper development environment set up so that the compilation may succeed. This environment must include:

Below we describe more detailed setup instructions for some of the supported systems.

Windows

The required packages are available in binary form for Windows, so it is not necessary to install any compilers or headers.

RHEL 6/7 and compatible systems

On RHEL-like systems the requirements mentioned above can be satisfied by following these steps (note that root privileges are required):

Ubuntu

Ubuntu offers three variants of curl, built using different SSL libraries. These variants differ in their licensing and SSL related capabilities (see https://curl.haxx.se/docs/ssl-compared.html for more details). The list of packages that need to be installed depends on the chosen SSL implementation.

The following package is required in all cases to use Python 2: 

# This will bring in Python, dev headers and GCC as dependencies  
apt-get install python-pip

For Python 3 this becomes: 

apt-get install python3-pip

To use the OpenSSL backend in curl:: 

apt-get install libcurl4-openssl-dev libssl-dev

For GnuTLS: 

apt-get install libcurl4-gnutls-dev libgnutls28-dev

For NSS: 

apt-get install libcurl4-nss-dev libnss3-dev
Arch Linux

On Arch the following packages are needed to use the client with Python 2: 

pacman -S gcc python2 python2-pip libcurl

For Python 3 use: 

pacman -S gcc python python-pip libcurl

Installation

NOTE: It is highly recommended to perform the install in a virtual environment. See https://virtualenv.pypa.io/en/stable/ and http://docs.python-guide.org/en/latest/dev/virtualenvs/ for more information.

The client can be installed with the following command 

pip install ./agraph-{property agraph-version}-client-python

This will also download and install all required third-party packages.

Testing

To validate the installation make sure that you have access to an AllegroGraph server and run the following Python script:: 

from franz.openrdf.connect import ag_connect  
with ag_connect('repo', host='HOST', port='PORT',  
                user='USER', password='PASS') as conn:  
    print conn.size()

Substitute appropriate values for the HOST/PORT/USER/PASS placeholders. If the script runs successfully a new repository named repo will be created.

Tutorial

There is a Python tutorial, described here. The tutorial examples can be run anywhere that Python 2.6 or 2.7 works. The tutorial assumes that AllegroGraph and Python 2.6 or 2.7 have been installed and configured. The tutorial examples currently do not work with Python 3.x.

The tutorial examples provide a good test of the installation for Python 2.6 or 2.7.

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-6.1.5-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 6.1.5 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 6.1.5 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.