02 Run a RACK Box container

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

Step 1. Set up Docker or Podman

Both Docker and Podman allow you to run Linux containers on a Linux, MacOS, or Windows computer. Docker is an all-in-one solution (only one program to install and you are done), but its graphical user interface, Docker Desktop, is no longer free for large enterprises. Podman costs nothing since it is open source, but you have to perform more steps to install and set it up on a MacOS or Windows computer. Once you have set up Podman, it has the same command line functionality as Docker so you can simply replace docker with podman in all the docker commands below.

To install Docker on your computer, follow these instructions here:

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 will use all of your computer's CPUs and 50% - 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 20 GB (16 GB may be enough if you don't have much RAM).
3. Click the Apply & Restart button to restart Docker with the new resource settings.

To install Podman on your computer, follow these instructions here:

https://podman.io/getting-started/installation

Here is a quick tutorial for getting started with Podman:

https://podman.io/getting-started/

From here on, simply replace docker with podman whenever you need to type a docker command below.

Step 2: Download a rack-box container 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 rack-box image to your computer:

docker pull gehighassurance/rack-box:v14.0

Step 3: Start your RACK box

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

docker run --detach -p 3030:3030 -p 8050:8050 -p 8080:80 -p 12050-12091:12050-12091 gehighassurance/rack-box:v14.0

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. If you run podman instead of docker, you will have to type a command to see your RACK box's logs, podman logs --follow --latest.

The Dashboard window also has a CLI icon you can click to open a terminal with a shell inside the container. You can type commands to inspect the container's filesystem and processes in that terminal. The Dashboard window also has stop and trashcan icons you can click to stop and/or delete the container when you don't want to run your RACK box any more. If you run podman instead of docker, you will have to type the equivalent podman commands instead, podman exec --interactive --tty --latest bash, podman stop --latest, or podman rm --latest.

Step 4: Visit your RACK box's welcome page

Visit http://localhost:8080 or type "localhost:8080" 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 3030:3030 -p 8050:8050 -p 8080:80 -p 12050-12091:12050-12091 -e WEB_HOST=192.168.1.151 gehighassurance/rack-box:v14.0

Now other computers should be able to visit your RACK box's welcome page by typing http://192.168.1.151:8080 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 RACK box container

Please be aware that Linux containers are designed to be shorter-lived than virtual machines. A Linux container image like gehighassurance/rack-box:v14.0 is immutable and read-only. When you type "docker run", you are starting up a new Linux 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 can see your changes if you stop a running Linux container and start it again, but Linux containers are typically intended to be thrown away after each run. Once you have stopped a Linux 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 persist changes to your RACK box over a long period of time, virtual machines are better than Linux 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:v14.0

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:v14.0.

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 Hub repository.

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. Use the Docker Dashboard or a "podman exec" command to open a root shell inside the container.

3. 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

4. Visit http://localhost:12080 in your web browser.

5. Click on Manage Datasets.

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

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

8. Click on Upload files.

9. 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.