Whyis is a nano-scale knowledge graph publishing, management, and analysis framework.

View the Project on GitHub

Whyis and Docker

Whyis can be used with Docker and Docker Compose to instantiate a fully functional Whyis Docker instance that can be run as many times as required. For an introduction to Docker concepts and terminology, see:

Whyis is packaged as two sets of Docker images:

  1. a monolithic image, which includes everything needed to run whyis is a single image

New users should start with the monolithic image.

  1. split images, which separates services into different containers and must be run with docker-compose or another orchestration system

For an introduction to Docker Compose, see:

Common concerns

All of the whyis images mount directories from the host in the docker-compose.yml files:

On Mac OS X you must allow Docker to mount these directories by going into Docker’s Preferences -> File Sharing and adding their absolute paths. For example:

Monolithic image

Installation and Use



Each run of the container should be considered a fresh slate for your Whyis application to be run on. In other words, most changes done to the container will be erased after each run.

To start the monolithic image from Dockerhub in detached mode, run:

docker run -p 80:80 -p 5000:5000 -d -it tetherlessworld/whyis

This will automatically download the latest version of the whyis image from the Docker Hub. It will also print out your container ID and map ports 80 and 5000 to the host machine.

Once the docker image is running, you will need to open a new terminal and open a shell into the docker container.

To find the container ID, run:

docker ps

To open a shell inside the docker container

docker exec -it <container_id> bash

This works on Linux systems and in the Windows command prompt. Some third-party shells on Windows (such as git bash), may require instead using

winpty docker exec -it <container_id> bash

To just pull the image or update the image to the latest version, run:

docker pull tetherlessworld/whyis

To verify that the server is working correctly, open a browser to localhost:80. This should display a Whyis login screen.



Building and pushing

The whyis monolithic image is built in two parts:

  1. a whyis-deps image, which contains the environment and dependencies for whyis
  2. the whyis image, which is the user-facing image and contains the custom code for whyis; it depends (FROM) on whyis-deps

We assume that whyis-deps changes infrequently, whereas whyis changes frequently. The Continuous Integration server only builds and pushes whyis, retrieving whyis-deps from Dockerhub in the process. When whyis-deps changes, you will need to push it to Dockerhub manually.

Assuming you have logged in with docker login, you can use docker/compose/dev to build whyis-deps and push it to Dockerhub:

cd docker/compose/monolithic

Note: You will have to be be a member of the Tetherless World organization to be able to run these steps.

Split images

The monolithic image was split into images for the databases Whyis relies on (redis, blazegraph) and the Whyis server application (whyis-server).



cd docker/compose/split
docker-compose -f db/docker-compose.yml -f app/docker-compose.yml

which starts both the database (db/) and server (app/) containers.


Similar to the monolithic image, the whyis-server image is built from multiple parent images, which change less frequently than the code.

cd docker/compose/split

The db/docker-compose.yml can be used to start the databases without the server, so that (for example) the server can be run locally:

cd docker-compose/split
docker-compose -f db/docker-compose.yml

Further, docker/compose/split/app-dev references a version of whyis-server that mounts /apps from the parent directory of the current whyis checkout, for local development.

Other notes

Data directory

By default, the split docker-compose.yml will mount a directory named data in the same directory as your /apps folder on the host machine. Due to how Docker allocates volumes, this folder will have the wrong permissions and cause Blazegraph to fail on the first setup. To avoid this, run the following instructions before running docker-compose:

cd /
mkdir data
chmod ugo+rwx data

You should then be able to start and stop the containers without further permission issues.

Whyis image tags

By default the docker-compose.yml use latest tags for the whyis images. This can be overriden by specifying the environment variable WHYIS_IMAGE_TAG.