Introduction

The official AllegroGraph server Docker container image is available on Docker Hub.

When you start an AllegroGraph container, you specify the port range in the run command (given below). If you use the docker run command below, AGWebView connects with the AllegroGraph image with [host]:10035 ([host] is localhost if docker and the browser are on the same machine). A browser version of Gruff is built into AllegroGraph (and runs through AGWebView). The standalone version of Gruff is also available and it too connects with [host]:10035.

Installing Docker Desktop

Running AllegroGraph in a Docker container on macOS and Windows requires downloading Docker Desktop and starting the AllegroGraph container.

Go to https://www.docker.com/products/docker-desktop for instructions on downloading and installing Docker Desktop on macOS or Windows.

Proceed to the next section when Docker Desktop is installed.

Getting AllegroGraph onto Docker

You communicate with Docker using a shell window.

The next step is to pull (i.e. download) the AllegroGraph image so that it is available in Docker. The following command does the pull:

$ docker pull franzinc/agraph 

That will download necessary layers:

$ docker pull franzinc/agraph  
Using default tag: latest  
latest: Pulling from franzinc/agraph  
4f4fb700ef54: Pull complete  
7b42fc91ca07: Pull complete  
1875ee4c7be9: Pull complete  
df8f2686285d: Pull complete  
a7fb677622dc: Pull complete  
be6e0c8e5439: Pull complete  
4569a75cc3ef: Pull complete  
3df1847997d3: Pull complete  
4d02aae5737a: Pull complete  
Digest: sha256:350a6cabb5a20594d9e45f4f0a2739ddb6ec87790162c5cc190b0d3c0166270b  
Status: Downloaded newer image for franzinc/agraph:latest  
docker.io/franzinc/agraph:latest  
$ 

The command pulls the latest version of AllegroGraph (7.3.1 at the time of publishing this document). You can pull a specific version by including the version number. This command will pull version 7.0.0, for example:

$ docker pull franzinc/agraph:v7.0.0 

In this document we assume you have pulled the latest version.

Starting an agraph container

Again at a shell prompt, you run AllegroGraph with the following command:

$ docker run -d -e AGRAPH_SUPER_USER=test -e AGRAPH_SUPER_PASSWORD=xyzzy -p 10000-10035:10000-10035 --shm-size 1g --name agraph --restart=always franzinc/agraph 

The return value is the container id, which is a long hex integer:

0bce26b1724656d31a30cc85c9024c2c06d39f8b839d2a77e639c758bc4912a9 

We specify a name (--name agraph) which also identifies the container so that the container id need not be used.

It is only necessary to execute this command once. The arguments are as follows:

The container created by this command will persist until removed by docker rm. You would use this docker run form again only if you have removed the container.

Using AGWebView with AllegroGraph on Docker

To connect to AGWebView, on the machine running Docker, open a browser tab with the URL

localhost:10035 

(From another machine, fully specify the host in place of localhost.)

The username and password are specified by arguments listed above. New users can be added and existing user passwords and permissions can be changed in AGWebVew with the Admin | Users menu item (see Managing Users). Accessible files from the host machine can be loaded into AllegroGraph as usual.

Stopping and Restarting Docker AllegroGraph

You stop the running AllegroGraph with the command:

$ docker stop agraph  
agraph  
$ 

And you restart it with

$ docker start agraph  
agraph  
$ 

If you specified --restart=always in the docker run command above, AllegroGraph container will always restart when the Docker server restarts.

Configuration directives and licenses in the agraph container

The agraph container described in this document will create basic configuration file agraph.cfg and store it within the container in the directory /agraph/etc/. You can copy the config file to a local directory outside of the container as follows (we are assuming the container name is agraph, as it is using the commands above):

$ docker cp agraph:/agraph/etc/agraph.cfg [Local directory] 

Then edit the copied file using a suitable editor. Here is the original file (what you see might be different):

# AllegroGraph configuration file  
RunAs agraph  
SessionPorts 10000-10034  
Port 10035  
SettingsDirectory /agraph/data/settings  
LogDir /agraph/data  
PidFile /agraph/data/agraph.pid  
InstanceTimeout 604800  
 
<RootCatalog>  
 Main /agraph/data/rootcatalog  
</RootCatalog>  
 
<SystemCatalog>  
 Main /agraph/data/systemcatalog  
 InstanceTimeout 10  
</SystemCatalog> 

We add a new catalog entry for the mycat catalog:

# AllegroGraph configuration file  
RunAs agraph  
SessionPorts 10000-10034  
Port 10035  
SettingsDirectory /agraph/data/settings  
LogDir /agraph/data  
PidFile /agraph/data/agraph.pid  
InstanceTimeout 604800  
 
<Catalog mycat>  
  Main /agraph/data/mycat  
</Catalog>  
 
<RootCatalog>  
 Main /agraph/data/rootcatalog  
</RootCatalog>  
 
<SystemCatalog>  
 Main /agraph/data/systemcatalog  
 InstanceTimeout 10  
</SystemCatalog> 

and we copy the file back:

$ docker cp [local directory]/agraph.cfg agraph:/agraph/etc/agraph.cfg 

and stop and restart AllegroGraph:

$ docker stop agraph  
agraph  
$ docker start agraph  
agraph 

Now you will see the new mycat catalog.

Make all desired changes to the config file, including adding your license if you have one (running without a license works but is restricted to 5 million triples).

The default user and the default working directory

When the container is run, the default user is agraph. The default working directory is /agraph/. Working directories are specified with the -w option to docker exec but the default usually suffices. Users are specified with the -u option to docker exec.

To see what files are in a directory, a command like the following, which lists the files in /agraph/data/, can be used (what you will see will be different; note the mycat directory for the catalog we created above):

$ docker exec agraph ls -l /agraph/data/  
total 1096  
-rw-r----- 1 agraph agraph 1048576 Apr 20 20:15 agraph-fallback.log  
-rw-r----- 1 agraph agraph   20871 Apr 20 20:15 agraph-system-info.txt  
-rw-r----- 1 agraph agraph   27850 Apr 20 20:16 agraph.log  
-rw-r--r-- 1 agraph agraph       3 Apr 20 20:15 agraph.pid  
drwxr-x--x 2 agraph agraph    4096 Apr 20 20:15 mycat  
drwxr-x--x 2 agraph agraph    4096 Apr 20 20:05 rootcatalog  
drwxr-xr-x 3 agraph agraph    4096 Apr 20 20:15 settings  
drwxr-x--x 3 agraph agraph    4096 Apr 20 20:05 systemcatalog  
$ 

How to execute ancillary AllegroGraph commands

You use docker exec to run commands like agtool. In the following example, we run agtool load to load the file kennedy.nt, which we first copy from our shell's current directory to the /agraph/data/ directory in the container.

$ docker cp kennedy.nt agraph:/agraph/kennedy.nt 

Now we run agtool load:

$ docker exec agraph agtool load mykennedy /agraph/kennedy.nt  
2020-04-20T21:08:57| Load finished 1 source in 127ms (0.13 seconds).   
Triples added:         1,214, Average Rate:        9,559 tps.  
$ 

This command loads the data in kennedy.nt into the repository mykennedy. See the Data Import document for information on the various arguments. We use the minimal repository spec mykennedy because the host, scheme, and port are all defaults (localhost, http, 10035) and the command is run by the same user as is running AllegroGraph (and thus automatically has superuser privileges). More complex repo specs can be used as needed, as described in the Data Import document.

agtool load writes a local log file. That file is written to the /agraph/ directory as that is the default working directory. And we *see the log file in the listing of /data:

$ docker exec -it agraph ls /agraph  
agload.log [and other files]  
$ docker exec -it agraph cat /agraph/agload.log  
2020-04-20T21:08:57| Load finished 1 source in 127ms (0.13 seconds).   
Triples added:         1,214, Average Rate:        9,559 tps.  
$ 

Gruff

A browser version of Gruff is included with AllegroGraph 7.3.1. The standalone version of Gruff is not installed in the Docker container. Just as you can use AGWebView in a browser by specifying the host, scheme, and port (as described above), you can run the standalone Gruff and open repositories as usual.

Download the standalone Gruff here if desired.

Customer AllegroGraph images in Docker

The image obtained with

$ docker pull franzinc/agraph 

is a standard image supplied by Franz Inc. We also provide the sources used to create that image, and they can be used to create custom images to run in Docker. See the page https://github.com/franzinc/docker-agraph which contains the scripts and files required for building a custom AllegroGraph image.