Virtual machine for Bodylight.js toolchain

This repository contains scripts and configuration to create development environment for Bodylight tool chain. Base box is minimal CENTOS 9 stream (RHEL derivative) and Vagrant scripts prepare the rest of virtual machine with recent Bodylight.js, OpenModelica (nightly 1.20 build), Python 3.x, Jupyter, Anaconda, http server. See web apps after installation at http://localhost:8080.

A binary snapshots are sometimes created usually in yearly (or less) bases.

All the tools are provided as is - usually in best effort or beta version quality. If it works, than it works, if something is wrong, see logs, console logs, submit issue.

Motivation

Vagrant tool automates configuration (port forwarding, secure ssh keys, shared folders) and provisioning of virtual machine and creates exemplar configuration. Thus preventing excuses: works on my machine.

Requirements

Requirement:

• HW: minimum 1 CPU, 4 GB RAM, min 5GB disk space.
• OS: Any OS supported by VirtualBox and Vagrant tool (succesfully tested on Windows 7,Windows 10, Ubuntu 16.04, ...)
• SW: Install VirtualBox, succesfully tested with version Virtualbox 6.1.38 (( Note we experienced issue VERR_NEM_VM_CREATE_FAILED - need to disable Windows features (V-Host) and see howto setup Windows 10 at https://forums.virtualbox.org/viewtopic.php?f=6&t=93712))
• SW: Install Vagrant tested version 2.2.6 and 2.2.9
• SW: GIT (EITHER Install GIT any version OR you may download master.zip and unzip instead of git clone from the URLs bellow)

Some OS has their own distribution of vagrant, virtualbox and git, so you may try to use it: yum install vagrant virtualbox git OR apt install vagrant virtualbox git.

Pre installation step (OPTIONAL)

This is not required step, it adds demo Jupyter notebooks and Physiolibrary-models next to the Bodylight-VirtualMachine on host machine. They will appear as /vagrant_data in virtual machine and will be available for jupyter notebook after installation.

In command-line (Linux xterm, bash etc. for Windows Start-> type 'cmd' -> choos 'Command Prompt') do:

git clone https://github.com/creative-connections/Bodylight-notebooks.git
git clone https://github.com/creative-connections/Physiolibrary-models.git

Installation

Choose either installation from sources or binary VM installation.

From binary image

• replace Vagrantfile with Vagrantfile.preinstalled where scripts are modified to download prepared image and configure the machine only. In linux BASH:

git clone https://github.com/creative-connections/Bodylight-VirtualMachine.git
cd Bodylight-VirtualMachine
cp Vagrantfile.preinstalled Vagrantfile

or in windows command

git clone https://github.com/creative-connections/Bodylight-VirtualMachine.git
cd Bodylight-VirtualMachine
copy /Y Vagrantfile.preinstalled Vagrantfile

• start "vagrant up" by

vagrant up 

From sources - default

Clone repository with Virtual machine scripts and run vagrant up (In command-line (Linux xterm, bash etc. for Windows Start-> type 'cmd' -> choos 'Command Prompt') do)

git clone https://github.com/creative-connections/Bodylight-VirtualMachine.git
cd Bodylight-VirtualMachine
vagrant up

If you do not have git then you may download and unzip manually the https://github.com/creative-connections/Bodylight-VirtualMachine/archive/master.zip and do vagrant up in the unzipped directory.

The first vagrant up takes 15-45 mins (or more depending on network speed) and The bootstrap scripts downloads, installs and configures all required software, ~500 MB of Anaconda (distribution of Python and Jupyter), ~700 MB OpenModelica, ~100 MB Julia and other packages. You may disable some bootstrap script by commenting them in Vagrantfile. You should see success:

    ...
    default:     [yLpj] (webpack)/buildin/global.js 472 bytes {0} [built]
    default: + exit 0

1.5 GB of depended packages (OpenModelica, Anaconda, Julia) are downloaded and persisted in host /cache subdirectory during installation.

After installation

After several minutes the VM is installed and configured. Port forwarding is done from guest VM 80 to host 8080 by default, refer Vagrantfile for exact port number. Refer default page at http://localhost:8080

The default installation contains these applications, some available from web interface:

• Jupyter notebook with Modelica kernel, link http://localhost:8080/jupyter/ [1]
• OpenModelica (v 1.14) - use e.g. OMEdit [2]
• Python v3 - including full Anaconda environment
• Bodylight.js-components - HTML web components - documentation and usage at http://localhost:8080/components/
• Bodylight.js-FMU-Compiler refer http://localhost:8080/compiler/
• Bodylight.js-Composer - refer http://localhost:8080/composer/
• Bodylight-Scenarios - Scenarios written in MD using web components http://localhost:8080/scenarios/
• Bodylight-VirtualBody - Virtualbody using WebGL http://localhost:8080/virtualbody/
• Visual Studio Code - Lightweight IDE for Linux - just type code within terminal window [7]

You may access virtual desktop using VirtualBox capabilities or you may access using vagrant ssh.

If you don't need VM, you can halt it using Virtualbox UI or using

vagrant halt

If you need VM, you can boot it again using:

vagrant up

To restart VM

vagrant reload

The second and other vagrant upis rapid and should take couple of seconds, because time consuming provisioning (bootstrap scripts) is already done.

Update VM

If you have previously installed VM and would like to update or reinstall from scratch, do:

1. Save any documents/data from VM to shared folder /vagrant folder. These are available and preserved in host. Other files and data will be erased.
2. Consider to delete /cache directory in host machine. It contains some installation packages, if it is not too old you may preserve it and go to next step.
3. Then do following:

vagrant destroy
vagrant box update
git pull
# if you made some local changes to Vagrantfile - git pull may fail, 
# try: git stash;git pull;git stash apply
vagrant up

This will clean VM,check and update the base box and install the software again - if /cache is present from previous installation it will use most packages from it rather to download again from Internet repositories.

Bootstrap scripts

Installation scripts are preserved in /scripts directory, they are launched only when vagrant upis made first or when provisioning is explicitly requested by vagrant up --provision.

Halt VM

To stop VM.

vagrant halt

To start VM again - it wil start quickly as bootstrap is not needed

vagrant up

To restart VM

vagrant reload

Clean, Uninstall

To destroy VM and remove all VM files do the following. The files stored in shared folders /vagrant and /vagrant_data are preserved.

vagrant destroy

There are preserved installation binaries in /cache directory. Delete cache if you don't need it anymore

rm -rf cache

References:

• [1] https://github.com/OpenModelica/jupyter-openmodelica
• [2] https://openmodelica.org/
• [3] vagrant https://vagrantup.com
• [4] virtualbox https://www.virtualbox.com
• [5] Anaconda https://anaconda.org/
• [6] GIT https://git-scm.com
• [7] Visual Studio Code https://code.visualstudio.com/