Support/Doc | About | Purchase | Advanced Search

The AllegroGraph Docker Container

The AllegroGraph Docker container is now available on Docker Hub.

Running AllegroGraph in a Docker container on Mac OS X and Windows is as easy as:

Installing Docker Toolbox
Getting Started with Docker AllegroGraph
Installing Gruff

Linux users can use the same container, but do not need Docker Toolbox.

Installing Docker Toolbox

NOTE: if you already have VirtualBox installed, follow these instructions to completely uninstall VirtualBox, then come back here to install Docker Toolbox.

For Mac and Windows (users on Linux would just install Docker):

Download the Docker Toolbox installer and execute it. NOTE: we use the "Docker Quickstart Terminal" below for demonstration.

Create the default machine:

# Only execute this command once!!
$ docker-machine create --driver virtualbox default
Running pre-create checks...
Creating machine...
(default) Copying /Users/layer/.docker/machine/cache/boot2docker.iso to /Users/layer/.docker/machine/machines/default/boot2docker.iso...
(default) Creating VirtualBox VM...
...
Setting Docker configuration on the remote daemon...
Checking connection to Docker...
Docker is up and running!
To see how to connect your Docker Client to the Docker Engine running on this virtual machine, run: /usr/local/bin/docker-machine env default

If you are using the "Docker Quickstart Terminal", your environment variables are already set up. You should be able to execute this command and see output similar to this:

$ docker ps
CONTAINER ID        IMAGE               COMMAND             CREATED             STATUS              PORTS               NAMES
$

This shows you have no running docker containers.

Set up port forwarding for AG WebView and Gruff:

Mac OS X:

$ /Applications/VirtualBox.app/Contents/MacOS/VBoxManage controlvm default natpf1 "tcp-port10035,tcp,,10035,,10035"

Windows:

$ "\Program Files\Oracle\VirtualBox\VBoxManage.exe" controlvm default natpf1 "tcp-port10035,tcp,,10035,,10035"

You will get an error about the rule existing if you execute the above command twice.

Getting Started with Docker AllegroGraph

To download the AllegroGraph container, you execute this one time:
```
$ docker pull franzinc/agraph
```
or
```
$ docker pull franzinc/agraph:v6.2.2
```
to get a specific version. The v6.2.2 part is called a tag and you can browse the available tags to find a specific version of AllegroGraph.
To run AllegroGraph (you only need to do this once):
```
 
$ docker run -d -m 1g -p 10000-10035:10000-10035 --shm-size 1g --name agraph franzinc/agraph:v6.2.2
bdfa5170cba598cae00f224441eba007425e69f40b836ae0d9ca144b46f465aa
$ docker ps
CONTAINER ID        IMAGE                  COMMAND                  CREATED             STATUS              PORTS                                  NAMES
2b8073e03155        franzinc/agraph:v6.2.2   "/bin/sh -c '/app/agr"   12 seconds ago      Up 5 seconds        0.0.0.0:10000-10035->10000-10035/tcp   agraph
$ 
```
A description of the arguments:
- -d runs the container in background and print container ID.
- -m 1g assigns 1 GB of memory to the container.
- -p argument and values are to make those ports available to applications (i.e., browsers and Gruff).
- --shm-size 1g set the shared memory limit to 1 GiB. AllegroGraph requires 422MiB of shared memory segment for each running repository.
- --name agraph assigns the name "agraph" to the contain, to be used in place of the container id (which is a very long hex number).
- franzinc/agraph:v6.2.2 specifies which image to run.
You would need to use the docker run form again only after executing docker rm agraph to remove the container created by docker run.

Using AG WebView with Docker AllegroGraph

After the above docker run command, to use AG WebView browse to http://localhost:10035. The default user name and password is test and xyzzy.

Stopping and Restarting Docker AllegroGraph

Stop the running AllegroGraph:
```
$ docker stop agraph
```
If you want to reboot your host (the machine on which Docker is installed and running) and you want to preserve the running state of your AllegroGraph, then before shutting down the host computer stop the "agraph" container (see above), reboot and do
```
 
$ docker start agraph
```

Is my data persistent?

If you started the container with the docker run command above, then your data is being stored in the same container in which you are running AllegroGraph, in the volume /data. Read on to make a separate container for your data, so that it will be persistent independently of the container running AllegroGraph.

Create the container from our data image:

$ docker create --name agraph-data franzinc/agraph-data:v6.2.2 /bin/true

Lastly, run franzinc/agraph, using this container:
```
$ docker run -d -p 10000-10035:10000-10035 --volumes-from agraph-data \
             --name agraph franzinc/agraph
```
The --volumes-from says to mount volumes from the specified container, which in this case provides an empty /data.

Now stopping and deleting the agraph container will not perturb your data, which is in the agraph-data container.

What if I need to execute ancillary AllegroGraph commands?

agload

docker exec

agload

actors.ntriples

$ docker cp actors.ntriples agraph:/data/actors.ntriples
$ docker exec agraph su agraph -c "/app/agraph/bin/agload test /data/actors.ntriples"
Load finished 1 source in 00:00:04 (4.01 seconds).  Triples added:       166,497, Average Rate:   41520.00 tps.
Terminating agload processes, please wait...
$

agraph

Increasing memory available to Docker AllegroGraph

First, you need to shutdown everything:
```
$ docker stop agraph
$ docker-machine stop default
$ /Applications/VirtualBox.app/Contents/MacOS/VirtualBox &
```
You should see the VirtualBox Manager window. Now, click on the "Settings" then "System" buttons to see the system settings, where you can change the amount of memory available to the boot2docker-vm virtual machine, which in turn effects the amount of memory available to Docker containers.
Start things back up with the changed memory configuration:
```
$ docker-machine start default
$ docker start agraph
```

Installing Gruff

Unlike with the AllegroGraph VM, which has Gruff installed inside the VM, when using AllegroGraph and Docker you run Gruff on your host computer. See the Gruff download for more information on downloading and installing Gruff.

Uninstalling Virtualbox

If you have an older version of VirtualBox installed, Docker Toolbox will likely not work well, so we recommend, if you have VirtualBox installed, that you completely uninstall it before installing Docker Toolbox, since it contains an installation of Virtualbox. Note: following the uninstall instructions will leave untouched your VirtualBox virtual machines.

Find the "Uninstallation" section for your operating system in the VirtualBox documentation.

If you have a previous version of Docker installed, you might consider moving ~/.docker [Mac OS X] or C:\USERS\USERNAME\.docker [Windows] aside, so it isn't used, unless you have existing Docker containers you are using.