Skip to content

Latest commit

 

History

History
204 lines (150 loc) · 5.89 KB

README.org

File metadata and controls

204 lines (150 loc) · 5.89 KB
Raw

Getting started

Instructions for getting SCKAN up and running.

The successful completion of the steps in this file should result in a window with welcome.org greeting you and giving you quick access to an interactive query interface.

SCKAN is distributed as two docker images.

  1. An image with the software needed to run queries tgbugs/musl:kg-release-user
  2. An image containing only the loaded databases tgbugs/sckan:latest

The underlying data and the tgbugs/sckan:latest image are also archived on Zenodo. The latest data release can be obtained from https://doi.org/10.5281/zenodo.5337441.

Download Docker and X11

  1. Download and install docker for your platform.
  2. Download and install X11 for your platform.

Commands for specific operating systems are in the Examples section below.

X11 configuration

linux

xhost local:docker

macos

open -a XQuartz

# XXX Go to XQuartz > Preferences > Security
# and enable Allow connections from network clients
# you may need to restart XQuartz after this

xhost +localhost

windows

& 'C:\Program Files\VcXsrv\vcxsrv.exe' -multiwindow -clipboard -wgl :0

Running

# obtain the latest release images from dockerhub

docker pull tgbugs/musl:kg-release-user
docker pull tgbugs/sckan:latest

# create a container that can be used to mount the SCKAN data release as a volume

docker create -v /var/lib/blazegraph -v /var/lib/scigraph --name sckan-data tgbugs/sckan:latest /bin/true

# run the image

## linux

docker run --volumes-from sckan-data -v /tmp/.X11-unix:/tmp/.X11-unix -e DISPLAY=$DISPLAY -it tgbugs/musl:kg-release-user

## macos

docker run --volumes-from sckan-data -v /tmp/.X11-unix:/tmp/.X11-unix -e DISPLAY=host.docker.internal:0 -it tgbugs/musl:kg-release-user

## windows

docker run --volumes-from sckan-data -e DISPLAY=host.docker.internal:0 -it tgbugs/musl:kg-release-user

See the Mounting the sckan folder from the host section of the reference to run when mounting host folders to save your work.

If you update to a new version of tgbugs/sckan you will want to run the following to update the sckan-data container.

docker rm sckan-data
docker create -v /var/lib/blazegraph -v /var/lib/scigraph --name sckan-data tgbugs/sckan:latest /bin/true

Examples

Full workflows for various operating systems.

linux

Note that these commands assume >=docker-20 so make sure your package index is up to date.

sudo apt install docker docker.io  # ubuntu mint etc.
sudo usermod -a -G docker ${USER}

# you may need to get a new login shell at this point

xhost local:docker

docker pull tgbugs/musl:kg-release-user
docker pull tgbugs/sckan:latest

docker rm sckan-data
docker create -v /var/lib/blazegraph -v /var/lib/scigraph --name sckan-data tgbugs/sckan:latest /bin/true

docker run \
--volumes-from sckan-data \
-v /tmp/.X11-unix:/tmp/.X11-unix \
-e DISPLAY=$DISPLAY \
-it tgbugs/musl:kg-release-user

macos

Using https://brew.sh/.

brew install virtualbox xquartz
brew install --cask docker

open -a Docker

# The docker command will not appear until you
# go to Applications and run Docker and accept
# the license agreements and grant permissions

# there are some system level persmissions that
# you will need to set for virtualbox

open -a XQuartz

# XXX Go to XQuartz > Preferences > Security
# and enable Allow connections from network clients
# you may need to restart XQuartz after this

xhost +localhost

docker pull tgbugs/musl:kg-release-user
docker pull tgbugs/sckan:latest

docker rm sckan-data
docker create -v /var/lib/blazegraph -v /var/lib/scigraph --name sckan-data tgbugs/sckan:latest /bin/true

docker run \
--volumes-from sckan-data \
-v /tmp/.X11-unix:/tmp/.X11-unix \
-e DISPLAY=host.docker.internal:0 \
-it tgbugs/musl:kg-release-user

windows

Using https://chocolatey.org/.

choco install wsl2 wsl-ubuntu-2004 vcxsrv docker-desktop docker

& 'C:\Program Files\VcXsrv\vcxsrv.exe' -multiwindow -clipboard -wgl :0

docker pull tgbugs/musl:kg-release-user
docker pull tgbugs/sckan:latest

docker rm sckan-data
docker create -v /var/lib/blazegraph -v /var/lib/scigraph --name sckan-data tgbugs/sckan:latest /bin/true

docker run `
--volumes-from sckan-data `
-e DISPLAY=host.docker.internal:0 `
-it tgbugs/musl:kg-release-user

If you try to launch vcxsrv.exe more than once with the same display number set you will encounter a fatal error.

Other ways to use the docker images

Beyond the interactive query interface, these docker images can be run as standalone SciGraph and Blazegraph instances of SCKAN for use in a variety of applications.

For example to run a specific release as a standalone endpoint you can run the following.

docker pull tgbugs/sckan:data-2022-03-19T001639Z
docker create \
  -v /var/lib/blazegraph \
  -v /var/lib/scigraph \
  --name sckan-data-2022-03-19 \
  tgbugs/sckan:data-2022-03-19T001639Z \
  /bin/true
docker run \
--detach \
--volumes-from sckan-data-2022-03-19 \
-p 9000:9000 \
-p 9999:9999 \
--entrypoint /etc/services.sh \
tgbugs/musl:kg-release-user
curl http://localhost:9000/scigraph/vocabulary/term/brain