Introduction

AllegroGraph Server runs natively on Linux x86-64. To run AllegroGraph on other operating systems (such as Windows or MacOS) we suggest you set up a Linux virtual machine, as described in this document, or use our Docker container image.

There are also cloud service options such as AllegroGraph on AWS Marketplace.

For the Linux virtual machine, we provide a VMware virtual machine image to help facilitate this installation or you can create one on your own. The AllegroGraph virtual machine can be downloaded from the AllegroGraph download page.

Performance in the virtual machine will be slower than running natively, so we encourage you to install AllegroGraph natively for performance evaluation.

Guide to the AllegroGraph Virtual Machine

Download the Virtual Machine Image

The AllegroGraph virtual machine image can be downloaded from the AllegroGraph download page.

After download, unzip the file into your desired location on your computer.

NOTE: The native Windows unzip for many versions of Windows cannot unzip the downloaded folder due to its size. You will need to use a free program like 7-Zip.

Download and install the VMware Player

Launch VMware Player and start the VM

VMware player

File choice for the vmx file

Once the VM starts playing, you should see this screen:

VM Login

Double-click on Franz Inc. and you will be prompted for a password. The password is allegrograph. Once you have entered the passowrd, you will see this screen:

AG VM initial screen

There is an icon bar to the left and several icons in the main area. The icons in the icon bar are:

In the main area, there are icons for the Franz directory file window, the Trash folder, and the ag-triple-data folder, which contains various example datasets.

Using the shell

You use the shell to start and stop AllegroGraph, to determine the VM's IP address, and to run programs like the vi editor. Display the shell by double-clicking on the terminal icon in the icon bar.

The VM shell

The illustration show the shell when it comes up. Three predefined commands are displayed as a startup message:

All these commands will work regardless of the current directory in the shell.

Starting AllegroGraph

Type agstart to the shell prompt:

Starting AllegroGraph

The server starts and runs in the background. Because we are using the default agraph.cfg which does not include a license, we are restricted to 5 million triples. The local port (10035) is reported. See Using AGWebView below for information on using AGWebview to control AllegroGraph.

The agstart command works regardless of the current directory of the shell.

Stopping AllegroGraph

You stop AllegroGraph with the agstop command. This illustration show agstop being called (at the bottom) just below the call to hostname described next.

Hostname and agstop

Determining the IP address

The third predefined command listed when the shell is opened is hostname. When called with the -I argument it returns the hostname which can be used by browsers outside the VM for connecting with the AllegroGraph server. See the Remote Connection to the VM for information on allowing connections to the VM just from the local machine (running the VM) or from any accessible machine. (That depends on using a NAT or a Bridged connection. The VM uses a NAT connection when initially started.)

Once you have the IP address, you can use AGWebview to control AllegroGraph.

Using AGWebView

Using hostname -I we determined that the IP address, usuable at least on the machine running the VM, was 192.168.248.128 (you will likely get a different IP address). AllegroGraph by default listens on port 10035. So bringing up a browser on the local machine and entering 192.168.248.128:10035 will open AGWebView:

Anonymous login to VM AGWebView

Anonymous login is permitted by default in the VM AllegroGraph so AGWebView typically comes up with the Anonymous login. Clicking on User Anonymous in the menu bar displays alogin choice (shown in the picture) and choosing that displays the usual AllegroGraph login prompt:

Regular AGWebView Login

See the AGWebview document for information on controlling AllegroGraph with AGWebView.

The agrapg.cfg file

AllegroGraph is customized by its configuration file agraph.cfg. That file is located in the /home/franz/ag/lib/ directory. It can be opened with the vi built in editor with the command vi /home/franz/ag/lib/agraph.cfg as we have done in the illustration:

The config file open in vi

See the Server Configuration and Control document for a list of configuration directives. If you have an AllegroGraph license, it goes at the end of the file.

agtool

agtool is a general command utility for AllegroGraph, see the agtool General Command Utility document. It is located in the /home/franz/ag/bin/ directory.

Running Gruff in the VM

Gruff is a graph visualization and graphical query builder designed to work with AllegroGraph. GRUFF can be run in a browser. Open AGWebView (here we have the anonumous login shown above):

Anonymous login to VM AGWebView

Clicking on the GRUFF icon on this page, and also on a repoitory page, will bring GRUFF up in a your browser. See the Gruff in AllegroGraph document.

The Wilburwine preloaded dataset

The AllegroGraph VM has various example data files located in the /home/franz/franz/ag-triple-data/ directory. The file is named wilberwine.ntriples.gz. You can load this file into AllegroGraph with the command

/home/franz/ag/bin/agtool load wilburwine /home/franz/franz/ag-triples-data/wilbutwine.ntriples.gz 

The same directory also contains other example datasets.

Remote Connection to the VM

NAT vs. Bridged Network Connections

The AllegroGraph VM is configured with a network adaptor that uses NAT. In this configuration, the VM shares the IP address of the host server. Only the host machine (and possibly other VMs running on the same host) will be able to connect to the AllegroGraph VM. No other machines on the host network will be able to connect to the AllegroGraph VM.

In Bridged mode, the AllegroGraph VM and the host machine will share the host's network connection, but the VM will attempt to join the same network that the host belongs to. In this configuration, any machine on the same network as the host will also be able to connect to the AllegroGraph VM.

To change the type of network connection, make sure your AllegroGraph VM is selected and open the Player | Manage menu and select Virtual Machine Settings.

The VM settings menu item

This displays the settings dialog. To connect from a remote machine, you want to turn off NAT and enable Bridged instead. (The illustrations are from a VM running on Windows.) We have selected the Network Adaptor setting in the illustration.

The VM Settings Dialog

This dialog is from Windows. The Mac dialog is similar but has somewhat different wording.

Windows

Select "Bridged: Connect directly to the physical network." Check the option that says "Replicate the physical network connectivity state." Close the dialog box and reboot the virtual machine.

Mac

Select "Connect directly to the physical network (Bridged)." Select "Autodetect." Close the dialog box and reboot the virtual machine.

Getting back to the NAT setting

Select instead NAT: Used to share the host's IP address. Close the dialog box and reboot the virtual machine.

Appendix 1: Device/Credential Guard on Windows

Note that this information, which was correct at the time this document was written, discusses MicroSoft Windows, VMware, and Docker, none of which are products of Franz Inc. It is possible that details will have changed and the advice given here might be out of date. The problem is not related to Franz Inc. products.

A feature of Windows, Windows Device Credential Guard, is not compatible with VMware. Trying to run a virtual machine on WMware when that feature is enabled will fail with a message similar to the following:

Device Credential Guard error

The solution is to run, at an Administrator command prompt,

bcdedit /set hypervisorlaunchtype off 

and to restart your computer. Note that Docker requires that the Device Credential Guard be enabled, which means you apparently cannot run Docker and VMware at the same time. You re-enable the Device Credential Guard by running, at an Administrator command prompt,

bcdedit /set hypervisorlaunchtype auto 

and restarting your computer.

To repeat the note at the top of this appendix, this information is about products which are not products of Franz Inc., and while what is said here was tested and correct at the time of writing, things may have changed since. Users should contact the various vendors of the mentioned software products for more information.