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
- 32/64-bit Windows: VMware Workstation Player
- 32/64-bit Mac OS X (Intel): VMware Fusion
Launch VMware Player and start the VM
- Launch VMware Player
- Click on "Open a Virtual Machine"
Navigate to the AllegroGraph Virtual Machine.vmx file in the directory where you unzipped the AllegroGraph download (it is shown in the file dialog in the illustration). Open this file. Take ownership if prompted.
Click on "Play virtual machine". If on Windows you get a message saying (roughly) VMware Player and Device/Credential Guard are not compatible, please see Appendix 1: Device/Credential Guard on Windows below.
If prompted for Moved or Copied, select Copied.
Once the VM starts playing, you should see this screen:
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:
There is an icon bar to the left and several icons in the main area. The icons in the icon bar are:
Firefox: double-click to display a Firefox browser.
Terminal: displays a UNIX shell. You type commands to the prompt to start and stop AllegroGraph. See Using the shell below for more information.
File window: displays files in the local filesystem.
Ubuntu software: displays links to available Ubuntu software.
Ubuntu help program
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 illustration show the shell when it comes up. Three predefined commands are displayed as a startup message:
- Type 'agstart' to start Allegrograph
- Type 'agstop' to stop Allegrograph
- Type 'hostname -I' to find the external ipaddr of the Guest VM. Use this address to connect to the VM from other computers.
All these commands will work regardless of the current directory in the shell.
Starting AllegroGraph
Type agstart to the shell prompt:
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.
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 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:
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:
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):
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.
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.
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:
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.