Install a Docker RACK Box - ge-high-assurance/RACK Wiki

After you follow these instructions, you will be able to run a RACK box in a Docker container on a Linux, MacOS, or Windows computer.

Step 1. Set up Docker

If you have not set up Docker on your computer yet, follow Docker's instructions to install Docker:

https://docs.docker.com/get-docker/

You may need to increase the resources given to Docker in order to run a RACK box. Click the right mouse button on Docker's whale icon in the system tray and select "Settings". When the Settings window appears, click on Resources and see whether the following resource settings appear. If you don't see these resource settings, it means you don't need to change anything; Docker can use all of your computer's CPUs and 80% of your computer's RAM if it needs to.

If you do see these resource settings, make the following changes:

  1. Increase the number of CPUs to 4 if you have enough CPUs (2 may be enough if you don't have many CPUs).
  2. Increase the amount of Memory to 4.00 GB (or more if you have plenty of RAM).
  3. Click the Apply & Restart button to restart Docker with the new resource settings.

Step 2: Download a Docker rack-box image

If this is the very first time you are using Docker, you may want to test a tiny "hello world" image to make sure Docker is working properly first. Open a command window and type the following commands:

docker pull hello-world
docker run hello-world

When you know Docker is working, type the following command to download a Docker rack-box image to your computer:

docker pull gehighassurance/rack-box:v9.1

Step 3: Start your RACK box

Now you are ready to start your RACK box. Type the following command to run your new rack-box image on your computer:

docker run --detach -p 80:80 -p 12050-12092:12050-12092 -p 3030:3030 gehighassurance/rack-box:v9.1

You can troubleshoot some problems by monitoring your RACK box's logs. Click the right mouse button on Docker's whale icon in the system tray and select "Dashboard". When the Dashboard window appears, it will display the currently running containers. Click on your RACK box's container and its logs will appear in the Dashboard window.

In addition, you can click a CLI icon in the Dashboard to open a shell window inside the container. You can type commands to inspect the container's filesystem and processes using the CLI. You also can click the stop and trashcan icons in the Dashboard to stop and/or delete the container when you don't want to run your RACK box any more.

Step 4: Visit your RACK box's welcome page

Visit http://localhost or type "localhost" in your web browser's address bar, hit Enter, and you should see your RACK box's welcome page appear in your browser. The welcome page will tell you some things you can do with your RACK box.

Step 5 (optional): Allow other computers to access your RACK box

If you want to allow other computers to access your RACK box, you need to know which IP address other computers can use to connect to your computer. Suppose your computer can be reached by using the IP address 192.168.1.51. Stop your previously running container and rerun your rack-box image using the additional argument -e WEB_HOST=192.168.1.151:

docker run --detach -p 80:80 -p 12050-12092:12050-12092 -p 3030:3030 -e WEB_HOST=192.168.1.151 gehighassurance/rack-box:v9.1

Now other computers should be able to visit your RACK box's welcome page by typing http://192.168.1.151 into their web browser's address bar. They also should be able to visit your RACK box's SPARQLgraph user interface and call your RACK box's services. If you don't set WEB_HOST to an IP address that both your computer and other computers can use, the other computers won't be able to use your SPARQLgraph user interface and call your RACK services.

Tutorial: How to save changes to your Docker RACK box

Please be aware that Docker containers are designed to be shorter-lived than virtual machines. A Docker image like gehighassurance/rack-box:v9.1 is immutable and read-only. When you type "docker run", you are starting up a new Docker container with a brand-new filesystem copied from the rack-box image. If you upload some data to your RACK box which makes some changes to the container's filesystem, those changes are lost when you remove the container. Regardless of whether you remove your container, only stop your container, or reboot your computer for some reason, simply typing "docker run" a second time always will start up a brand-new container with its own pristine filesystem so you won't see any changes you made the last time.

You still will see your changes if you stop a running Docker container and start it again, but Docker containers are typically intended to be thrown away after one or two runs. Once you have stopped a Docker container, you will have to be careful not to let it be deleted. A "docker container prune" or "docker system prune" command will delete all stopped containers automatically and your changes will be lost again. If you want to save changes to your RACK box over a long period of time, virtual machines are better than Docker containers.

Nevertheless, there is a way to save your changes more permanently or share them with others. After making some changes to your RACK box, you can save your changes to a new immutable rack-box image with a "docker commit" command:

docker container commit CONTAINER my-name/rack-box:v9.1

Replace CONTAINER above with your container's name or id in the Docker Dashboard and replace my-name with any name you want in order to give your saved image a different name than gehighassurance/rack-box:v9.1.

This command will create a new rack-box image containing all of your changes to the original rack-box image. Then you can run your new image instead of the original image whenever you want or even share your changes with others by pushing your rack-box image to a Docker repository.

:godmode: Replace the RACK database (god mode)

If you are working closely with the RACK ontology developers and want to update the pre-seeded RACK database without waiting for a new RACK-in-a-Box release, this procedure will give you administrative access to the Fuseki server so you can do whatever you want with the RACK database.

  1. Start your container.

  2. Open the Docker Dashboard by right clicking the Docker whale icon in the system tray and selecting Dashboard.

  3. Select your running container and click the CLI (->) icon to pen a terminal window with a root shell inside the container.

  4. Type these commands in the root shell which will forward port 12080 to port 3030 in order to let you access the Fuseki server's administrative interface:

    apt update
    apt install -y socat
    socat tcp-listen:12080,fork,reuseaddr tcp:localhost:3030
    
  5. Visit http://localhost:12080 in your web browser.

  6. Click on Manage Datasets.

  7. Delete the RACK database if that's what you want to do.

  8. Click on New to create a new database. Call it RACK.

  9. Click on Upload files.

  10. Upload a new RACK.nq file to initialize the RACK database again.

However, the RACK CLI is now installed in the rack-box image so you can connect a CLI terminal to your container and do anything you want to do with the RACK CLI instead. You can clear the RACK database, import data into the RACK database, and so on with RACK CLI commands.