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:
-druns the container in background and print container ID. If you leave this argument out, AllegroGraph will run in the foreground and log messages will be written to standard output. Control-C will stop AllegroGraph.-e AGRAPH_SUPER_USER=testspecifies the username of the initial superuser. This argument is optional. If left out, the superuser name isadmin. We specifytestas an example. Any suitable username can be used (a blank name, and names.and..are not allowed; the characters slash, backslash, colon and tilde (/ \ : ~) may not be part of the username).-e AGRAPH_SUPER_PASSWORD=xyzzyspecifies the password for the superuser. If left out, a random password is generated and written to the log. We specifyxyzzyas an example. Any password can be used.-p 10000-10035:10000-10035makes those ports available to applications (i.e., browsers and Gruff).--shm-size 1gsets the shared memory limit to 1 GiB. AllegroGraph requires 422MiB of shared memory for each running repository.--name agraphassigns the name "agraph" to the container, to be used in place of the container id (which is a very long hex number returned by the docker run command).--restart=alwayssays to start the AllegroGraph image whenever the Docker server is started. This argument is optional.franzinc/agraphspecifies which image to run (if you have a named version, put the version number at the end following a colon, like `franzinc/agraph:v7.3.1`)
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.