Inside a Docker container
JAMScript can be compiled and run without a local installation. This is the simplest way to try out JAMScript. You need a local installation only if you want to debug or develop JAMScript itself! The following are the preparatory steps to get Docker JAM tools working in your system.
- Download JAMTools into a local directory called
git clone https://github.com/citelab/JAMTools tools.
- Add the
toolsdirectory to your execution path. This way
jamtools are available for you.
- Test that you actually completed Step 3 successfully. Use a command like
docker psand see whether it runs.
- Pull the docker container with JAMScript. Use
djam pull mahes25/jamscript.
Everything should be setup at this point. Type
jam and you should see a menu of sub commands available under each of them.
To compile a JAMScript program, do the following.
- Write or get a JAMScript program. The easiest is to download the JAMSamples. Run
git clone https://github.com/citelab/JAMSamples samplesto download many example programs into a
- Change to a folder containing a valid JAMScript program.
cd samples/JData/String_Logwill change to the folder containing the string logging example.
- To compile this program:
djam compile stringlog.*.
- After a successful compile, you should see
stringlog.jxein the folder. If not, the compilation did not succeed. You should have seen some error messages in the console to that effect.
- Once you have compiled the sample program, you can run the program in different ways: in a device, fog, or cloud. When you run in a device, you can specify different number of C nodes as well. By default, the
djam runsub command creates a single C node.
To run a device using the
stringlog.jxe with 2 C nodes under the app name
q5 in background, use the following command.
djam run stringlog.jxe --num=2 --app=q5 --bg
To see the status of the docker JAMScript execution, run the following command.
You should see something like the following.
ID NAME PROGRAM HOST D-STORE TYPE C-NODES TMUX-ID q5 q5 stringlog ec0cd9fa0887 docker:6379 cloud -- u-501-cloud-5-cloud q5 q5 stringlog ad38d5fb718a docker:6379 device 2 u-501-device-13-dev q5 q5 stringlog 4e0c4d9a7732 docker:6379 device 1 u-501-device-17-dev q5 q5 stringlog 443981d1dbbd docker:6379 device 1 u-501-device-19-dev q5 q5 stringlog 7059b7d955a6 docker:6379 device 1 u-501-device-21-dev q5 q5 stringlog cf46d982d28b docker:6379 device 1 u-501-device-25-dev q5 q5 stringlog e8d1605639d9 docker:6379 device 1 u-501-device-27-dev q5 q5 stringlog 79a02ca4934d docker:6379 device 1 u-501-device-29-dev q5 q5 stringlog f011f39a80d8 docker:6379 device 1 u-501-device-31-dev q5 q5 stringlog e9fe93e89c71 docker:6379 device 1 u-501-device-33-dev q5 q5 stringlog c3cf5c274ab9 docker:6379 device 1 u-501-device-35-dev q5 q5 stringlog 45c292e451de docker:6379 fog -- u-501-fog-7-fog
The second line corresponds to the device created by the previously issued command. It is created under the
q5. Also, the
NAME is same as the
HOST gives the docker
ID for the container running the device. The
D-STORE shows the URL for the data depot used by the device. By default the
djam puts a data depot inside each container at the default port. The
TMUX-ID shows the
tmux terminal that runs the program. To connect to the terminal issue the
jam term u-501-device-13-dev
To detach from the terminal, press Ctrl-B and d. Some
djam subcommands and interchangeable with the
jam subcommands (e.g.,
djam term are the same).
You can start a whole topology using a script like the following.
djam init --zones=3 --indelay=3:1 --outdelay=5:3 --cldelay=30:5 djam run stringlog.jxe --cloud --app=q5 --bg for i in `seq 1 3`; do djam run stringlog.jxe --fog --app=q5 --bg done for i in `seq 1 12`; do djam run stringlog.jxe --app=q5 --bg done
The above script, is setting up a network with three zones. The
--indelay in the first line is specifying the delay within a zone.
--outdelay is specifying the delay across two different zones. The
--cldelay parameter specifies the delay between the cloud and
a machine (fog or device) in a zone.
You will notice that all machines (cloud, fogs, and devices) are started with the same application name (i.e.,
q5). This is necessary for
the nodes to create a single topology. You can delete all nodes in the topology, using the following command.
djam kill q5
If you want to see how the delay is setup among the nodes, use the
djam test command. It should create a test topology of bare nodes (i.e.,
no JAMScript program is running in them). You can see them running by issuing the
docker ps command, they should have
-test in their names.
Log in to a device, fog, and cloud test node and run a ping to a corresponding test node. You can see the network delay. To obtain the
IP address of a node, run
hostname -I while in the node.
On the local machine
You can run JAMScript programs natively in Linux (Ubuntu), MacOS, or Rasberry Pi (Raspbian Linux). To run natively, you need to install JAMScript on the local machine following the instructions under Install. After that, follow the steps below to get JAMScript programs running on yoru machine.
To be completed.