Running ChaRT locally using a virtual machine image

Overview

This document will show users how to download, install, and run ChaRT locally on their own hardware using the ChaRT image (aka virtual machine). The current version of the ChaRT image uses SAOTrace v 2.0.5 and CIAO version 4.17.0.

Running ChaRT locally may be especially useful for users that require a large number of simulations. Since ChaRT hosted on the CXC servers is a shared resource; users with large jobs will benefit from running their jobs locally.

Note

This document is not intended to be a introduction to containers, images, virtual machines (VM), and related technologies. There are countless online resources that users can consult to get more information on these topics.

Outline

1. Install virtual machine software

Users will need to install software that can execute a docker archive format image. Two common choices are Docker and podman. Docker is a commercial product and requires administrative (root) privileges to run certain background services. Podman is an open source alternative to Docker that does not require root access (once installation and configuration is complete). Both products have their own licenses and terms of service that users must agree to before installation and use.

Docker and podman have exactly the same command line options. In this document we will be using the podman command. In addition to the command line interface, both Docker and podman have Desktop GUI interfaces.

The ChaRT image can be run on any operating system that supports Intel/AMD x86_64 virtual machines. This includes Linux, macOS (AMD and Apple silicon), and Windows machines.

2. Download ChaRT image

The next step is to download the ChaRT image: chart-2.0.5-4.17.0.tar.gz (894Mb).

Do not decompress (gunzip) nor unpack (untar) the file.

3. Load ChaRT image

The next step is to load the ChaRT image into the virtual machine softwares' repository. This is done using the image load command

$ podman image load -i ~/Downloads/chart-2.0.5-4.17.0.tar.gz

You can check that the image is loaded by running

$ podman image ls
REPOSITORY                           TAG               IMAGE ID      CREATED       SIZE
localhost/chart                      2.0.5-4.17.0  c5742ad601a7  20 minutes ago  2.68 GB

Disk Space

Note that by default the virtual machine software will likely be storing the images in your home directory. As can be seen the installed image requires 2.68Gb. Please make sure that you have sufficient disk space and/or quota before loading the image.

Each virtual machine software package has a different mechanism/option for selecting an alternative destination for images. Please consult the documentation for your VM package for details.

At this point the downloaded file is no longer needed and can be deleted.

4. Run ChaRT image

The next step before actually starting the ChaRT image is to select and create a directory where the ChaRT output files should be written. Unlike the ChaRT web application running on the CXC servers, the local ChaRT web server will write the outputs directly to the specified directory on the user's machine. In the example below we will be using /Users/mac_user/Temp/workdir/output as our output directory. The directory must have world-write permission.

$ mkdir -p /Users/mac_user/Temp/workdir/output
$ chmod 777 /Users/mac_user/Temp/workdir/output

Then the command to run start the ChaRT image looks like:

$ podman run --rm -t -p 8888:8888 --arch=amd64 \
    -v /Users/mac_user/Temp/workdir/output:/workdir/output \
    --name=chart localhost/chart:2.0.5-4.17.0

Serving HTTP on 0.0.0.0 port 8888 (http://0.0.0.0:8888/) ...

The arguments are as follows:

--rm will remove this instance of the container (and all files inside it) when the container exits. It does not remove the image which can still be used with future containers.

-t connects the standard output and error from the virtual machine to the host; upshot is that you will see outputs from the webserver and jobs display in the terminal window where podman was run.

-p 8888:8888 maps port 8888 on the host (ie your linux, mac, windows machine) to port 8888 on the container (virtual machine). The ChaRT web server is setup to serve on port 8888; but you can choose whatever port number, over 1000, you want on the host.

--arch=amd64 lets your host know that you are running a virtual machine that is built for AMD64 architecture (ie x86_64). This allows it to run on Apple silicon (M1/ARM chips).

-v /Users/mac_user/Temp/workdir/output:/workdir/output mounts the /workdir/output directory on the VM to the /Users/mac_user/Temp/workdir directory on the host machine. The output files will be available in the /Users/mac_user/Temp/workdir directory. The path on the left hand side of the colon is the path on the users machine (created using mkdir/chmod above); the value on the right hand side of the colon is the path within the container which is fixed to be /workdir/output.

--name=chart just gives the container a nice, easy to remember name.

localhost/chart:2.0.5-4.17.0 is the name of the image that you saw when you did the podman image ls command (above).

The Serving HTTP line tells you that the container is running and ready to run simulations.

5. Run ChaRT simulation

The ChaRT web service is now running locally on the user's machine. To access the website go to: http://127.0.0.1:8888 or http://localhost:8888 (assuming you used the default port 8888 as shown above).

This page will take you to a form to input your ChaRT parameters. The parameters on this page are the same as on the Run ChaRT page hosted on the CXC servers, except there is no email address required. Since all the simulations are done locally there is no need to email when the simulation is complete.

When the job is submitted, the active web server log shown in the terminal where the ChaRT container was started will show that the job has been submitted. Depending on the size of the simulation it may take a few seconds or minutes before the webpage updates with a job complete message (or any error messages).

Assuming a successful run, the ChaRT output ray files will be in the pickup directory you specified, eg

$ /bin/ls -l /Users/mac_user/Temp/workdir/output/HRMA_ra246.96696_dec-24.68080_en1.5_flux0.0001_dithered.tar.gz
-rw-rw-r-- 1 mac_user mac_user 475640 Jul 30  2025 /Users/mac_user/Temp/workdir/output/HRMA_ra246.96696_dec-24.68080_en1.5_flux0.0001_dithered.tar.gz

6. Stop ChaRT container

Simply hitting "Ctrl-C" will not stop the ChaRT container. The container has to be stopped by issuing the stop command. The stop command can be issued via the Desktop GUI or from a second terminal window

$ podman stop chart

Note: we can use the abbreviated name chart that we assigned the container when it was started.

After the container is stopped, it can be restarted again (starting at step 4 above).

/ ciao / PSFs / chart2 / vm.html