Hall A & C Analysis Workshop June 25-26, 2018
Virtual Machine Image
=====================

Update 22-June-2018: This is the final version of the VM image

Installation
~~~~~~~~~~~~
1) You will need a 64-bit computer with at least 4 GB of memory.
   Minimum OS requirements are Windows 7, Mac OSX 10.9, or a recent Linux.
   Linux specifics vary, but Fedora 25+, Ubuntu 14.04+ and RHEL5+
   will most likely work. 30 GB of free disk space are needed.

2) Set up VirtualBox on your system.

   Please install VirtualBox 5.2 or higher form https://www.virtualbox.org.
   Version 4.x will definitely not work, 5.0 is untested, and 5.1
   has at least a few cosmetic glitches and will force a kernel module rebuild.
   On Linux, you may be able to install through your distribution's
   package manager, but be careful to check the version that your distribution
   provides. Those versions are often old. In that case, do not
   install from the repository, but download a matching package from
   the VirtualBox web site instead. Be sure to get the 64-bit version!

3) Download the archive file CentOS_7_VM_2018.tar.xz (3.3 GB) from here
   as well as the .sha1 checksum file. (Get the .asc signature file
   too if you are paranoid. Exercise: verify the signature ;) )

4) Verify the integrity of the archive
   sha1sum -c CentOS_7_VM_2018.tar.xz.sha1
   This should report "OK"

5) Unpack the archive in a convenient location, such as the VirtualBox
   default directory. You'll need about 30 GB of space.

   On Linux, just type
   tar xvf CentOS_7_VM_2018.tar.xz

   On Mac, you might need to install "xz" from Homebrew or otherwise
   before using the tar command above.

   On Windows, you can use 7-zip or WinRAR (free trial), for example.

6) (Double-)Click on the .vbox file in your file manager, or add
   this machine to VirtualBox via the GUI (Machine->Add...)

Configuration
~~~~~~~~~~~~~

The configuration should be adequate for many host systems. However:

IMPORTANT: The downloaded image is configured to use 4 GB of RAM and
four CPUs. Depending on your host machine, these settings may be
too aggressive. If you only have 4 GB of RAM, please reduce the RAM
available to the guest OS to about 50-60% of your total RAM. Also,
reduce the number of virtual CPUs to at most the number of cores
you actually have.

In the VirtualBox GUI, got to Settings->System->Motherboard
Move the slider next to "Base Memory" to the desired amount
which needs to be in the green range.
Similarly, for the number of CPUs, go to Settings->System->Processor
and move the slider into the green range.

The minimum requirements to run the examples are about 2 GB of RAM
and a single CPU.

Running
~~~~~~~

1) Click the green "Start" button in the GUI. The guest OS should start up.

2) You'll be greeted with a login screen for "Workshop Participant".
   The account name is "wrkshp" and the password, "hallac".
   You can sudo from this account if necessary, for example to install
   additional packages.

Toubleshooting
~~~~~~~~~~~~~~
- If you get a message about "VT-x disabled" or similar, you need to enable
  the "Virtualization Extensions" in your computer's BIOS. This is
  harmless, but changing BIOS settings can be somewhat risky unless you know
  what you are doing. The only change you should make is to enable
  "VT-x" and "VT-d" (if available). These setting might have various
  other, similar names, depending on your computer's BIOS.

- On Linux, odd errors about "kernel modules" usually mean that your
  VirtualBox installation is damaged or incorrect. Try cleaning everything
  out, then reinstall.

- When first started up on a new system, the machine sometimes seems to
  stop booting (black screen). If this happens, try typing Alt-D, which
  will switch to verbose boot messages. If Alt-D fails to work, or if
  the messages suggest that booting is frozen, try restarting the system
  (Machine->Reset). Do not reset, however, if the system is rebuilding
  the vboxadd kernel module; in that case, wait for the build to finish
  at which point the boot proces should continue normally.

Please contact me with any questions.

Ole Hansen
ole@jlab.org