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.2-1.x86_64.rpm from the Franz download page.
Install the RPM:
# rpm -i agraph-6.1.2-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.2-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.2-linuxamd64.64.tar.gz This creates the "agraph-6.1.2" 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-6.1.2/install-agraph /home/joe/tmp/ag6.1.2
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.2/bin/agraph-control --config /home/joe/tmp/ag6.1.2/lib/agraph.cfg start
You can stop AllegroGraph by running:
/home/joe/tmp/ag6.1.2/bin/agraph-control --config /home/joe/tmp/ag6.1.2/lib/agraph.cfg stop Now, the server can be started as shown above:
$ /home/joe/tmp/ag6.1.2/bin/agraph-control --config /home/joe/tmp/ag6.1.2/lib/agraph.cfg start
AllegroGraph 6.1.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.
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.
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 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/ag6.1.2/lib/agraph.cfg]:
Directory to store data and settings:
[/home/joe/tmp/ag6.1.2/data]:
Directory to store log files:
[/home/joe/tmp/ag6.1.2/log]:
Location of file to write server process id:
[/home/joe/tmp/ag6.1.2/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.2/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.2/bin/agraph-control --config /home/joe/tmp/ag6.1.2/lib/agraph.cfg start
You can stop AllegroGraph by running:
/home/joe/tmp/ag6.1.2/bin/agraph-control --config /home/joe/tmp/ag6.1.2/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.2/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:
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 Python client works with Python 2.6, 2.7 and 3.3+.
There is a Python tutorial, described here. 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.6 or 2.7 have been installed and configured using the following procedure. The tutorial examples currently do not work with Python 3.x.
It is recommended to install the Python client in a Python virtual environment.
To create such an environment in a directory DIR use the following command:
virtualenv --no-site-packages DIR To start using the new environment, type the following (on UNIX)
source DIR/bin/activate On Windows, the command is
call DIR/Scripts/activate It is important to update the packaging tools contained in the virtual environment to their latest versions. You can achieve this with
pip install -U setuptools pip wheel The AllegroGraph Python client files are in
agraph-6.1.2-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-6.1.2-client-python.tar.gz This creates the agraph-6.1.2-client-python subdirectory.
To install the client, run the following command in a Bash prompt
pip install -e /yourPathway/agraph-6.1.2-client-python This will download all required packages and install them into the virtual environment. Note that a few packages do not provide binaries for Linux and hence will be compiled from sources. This means that it is necessary to have a working C compiler and required headers available on the target system. In particular, development packages for Python and libcurl should be installed.
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.
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-6.1.2-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.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.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.
If you see an error similar to the following
ImportError: pycurl: libcurl link-time ssl backend (nss) is
different from compile-time ssl backend (none/other) Perform this procedure (enter the commands in Bash)
# Uninstall pycurl from the virtual environment:
pip uninstall pycurl
# Set the required compile-time option for pycurl
export PYCURL_SSL_LIBRARY=nss
# Reinstall, but ignore cached packages (force recompile)
pip install --no-cache-dir -e /yourPathway/agraph-6.1.2-client-python 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.2-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.2 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.2 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.