The CAS Development Sandbox VM runs under Oracle Virtualbox (a Yale preferred free VM host) on your desktop or laptop Windows, Mac, or Linux machine. It provides the general setup for using Eclipse to develop an application that will run in JBoss on one or more datacenter VMs. However, it does not try to duplicate the exact setup of datacenter VMs. Production servers are not configured to be friendly for development. Any minor issues that depend on the specific directories into which JBoss is installed can be worked out when you deploy to the DEV environment. The Sandbox simplifies the edit, compile, deploy, and debug cycle.
Unlike production systems, which are frequently fixed at old maintenance levels, the Sandbox is typically kept up to date with the latest system, Java, Eclipse, and JBoss patches. At the time this is written, it is a Centos 7 64 bit operating system with Oracle Java 1.7 64 bit, JBoss EAP 6, and Eclipse Luna. Because Eclipse is not part of the production system, you can upgrade it at any time and install any additional features that aid in development. However, it is probably a bad idea to use Java 1.8 if the production system will be 1.7, and while it doesn't matter much if JBoss is 6.1 or 6.3, you should use the same major version of JBoss that you are using in production (EAP 6.x).
Installation
You need a current version of VirtualBox which you can get from Oracle (virtualbox.org). You can install it on a Windows or Mac machine. If you already have VMWare and prefer to use it, skip this step.
The Sandbox is distributed as a *.ova file. This is an open generic distribution format that can be processed by virtualbox or VMWare.
Certain features or options of the Sandbox VM depend on local directories or features that have to be configured in VirtualBox. The Shared Directory feature expects to use a preexisting directory (D:\sandbox) on the host computer or it has to be reconfigured or turned off. There are two LAN adapters on the VM, and one depends on a VirtualBox feature called a Host-Only adapter that has to be preconfigured (fortunately, it is the default behavior of VirtualBox to create during installation).
It is easy to go back and fix things, but do not rush to install the Sandbox image before you have read the rest of these instructions.
casdev
There is one user named "casdev" with admin (sudo) privileges. You login, run Eclipse, and do all your development as this user. The /home/casdev directory holds the Eclipse workspace and all the casual files. Because JBoss is started from Eclipse, it also runs as casdev. Therefore, the JBoss and Eclipse directories are owned by casdev even though they are installed elsewhere in the file system.
Where
The Oracle Java comes in a standard "RPM" distribution, so it goes into the directory it is preconfigured to use (/usr/local/java). Red Hat official RPMs for JBoss are not generally available, and the public distribution directory supplies a single zip file without further instructions. Eclipse can often be installed from package libraries, but it is also likely to be several releases behind. So JBoss comes from http://jbossas.jboss.org/downloads.html and Eclipse comes from http://www.eclipse.org/downloads/ and they are unzipped into subdirectories of /opt and then assigned to user casdev as their owner.
Eclipse and JBoss could have been put in the casdev HOME directory, but by putting them in /opt they could be shared with a second user if you created such an account. Assigning ownership to casdev makes it simpler to add options to Eclipse or to edit the standalone.xml configuration file of JBoss if you need to.
When JBoss is installed in DEV TEST PROD, production services has the licenses to use the RPMs, so different parts of JBoss are scattered into different parts of the system directory structure. For the most part, it doesn't matter if JBoss is completely unzipped into/opt/jboss/jboss-eap-6.2 or has pieces scattered around. It might be important if you want to start JBoss at boot time as a system service, but that is not how development is done. The one directory that matters is the jboss.server.log.dir (the directory into which JBoss puts log files). In production, this is /var/log/jbossas/standalone, but if you just unzip into a single directory it defaults to the log directory that you unzipped. This is changed by setting the parameter explicitly when JBoss is started in Eclipse.
The VM
The VM is a standard Virtualbox 64 bit Linux configuration. With JBoss running the virtual memory use gets up to 1.3 GB, so it could be reduced to 1.5 or 2 GB of virtual RAM if you need to run two VMs on an 8G laptop.
To use the VM, first install the latest version of VirtualBox from Oracle on your Windows, Mac, or Linux "host" system. Make sure to add the corresponding Oracle VM VirtualBox Extension Pack which contains Oracle code for extra host functions.
The VirtualBox Guest Additions are a set of drivers for the VM operating systems. These mouse, keyboard, video, and filesystem drivers support the integration of the VM interactive environment with the host system. For example, you can cut and paste text between your Windows host and your Centos VM thanks to these drivers. The Sandbox comes with a version of these drivers from when it was built, but if time has passed the version of VirtualBox you just installed will be newer and you should click the menu item Devices - Insert Guest Additions CD. Then autorun the software on the CD image to build the latest version of the drivers.
It is not generally possible to drag and drop files between the Linux and Windows systems. Of course, you can use network file sharing between the machines, but there is a simpler solution. VirtualBox provides a feature called "Shared Folder". In the settings for the VM, there is a section for Shared Folder. You can designate one or more directories on the host computer (D:\sandbox is configured initially for the Sandbox VM). This directory is then given a name ("sandbox" for D:\sandbox). The shared host folder appears to the VM to be a virtual disk or virtual shared disk that can be mounted in Linux or assigned a disk letter (if you have a Windows VM). For Linux VMs, the shared folder is automatically mounted (because of the check box in the VM settings) to the location /media/sf_[name] (that is, /media/sf_sandbox for the name "sandbox"). The casdev user has been added to a group that allows read/write access to the files in the shared folder. This allows easy transfer of files between the VM and the host (Windows?) operating system. Copy files to or from C:\sandbox on the one end, and to or from /media/sf_sandbox on the other end.
The Virtual Network
Each VM has a virtual LAN adapter. VirtualBox can be configured to support this virtual adapter in several different ways. This is the most complicated step in the Sandbox configuration and needs to be understood, at least in basic terms, so the developer knows how to interpret behavior.
First, we need to define a few network terms. Suppose you have several real computers that you are connecting together in a home network. If you wire them to each other through a switch but you do not connect them to any router, then you have a Private Network. The machines can talk to each other but not to the outside world. You can assign each machine a static IP address, and for home networks this is traditionally a 192.168.1.* number. Of course this is the most secure arrangement, but it is not very useful.
So you get a DSL connection from the phone company or a cable connection from you TV provider, and you connect it these days to a Wireless Router box. Home routers add two network functions: DHCP and NAT. DHCP assigns addresses (from the 192.168.1.* subnet) to machines that are not configured to use a specific private address. NAT allows the router to forward client requests from any computer on the private network to the internet, but it changes the IP address on each packet of data so that the outside world thinks the request came from the router itself. This is important because the phone or cable company only assigned one IP address to your home, and the router has to own and manage that address.
NAT works automatically when the home computer is a client and the server is out on the internet. To allow Internet machines to connect back to a computer in your home network, then you have to configure the "Port Mapping" feature of the router to direct all Internet requests for a particular port (example: 8080) to a particular home computer.
Your host computer may be a laptop connected to the Yale network, but the VMs that it runs under VirtualBox are typically unknown to Yale and you probably want them to be unavailable to other machines. So VirtualBox creates various virtual network solutions emulating different elements of the typical home network solution.
When you create a VM and give it a virtual LAN adapter, you can configure the connectivity of that adapter to use specific named options:
- NAT - One VM appears to be connected to its own network with a NAT router simulated on the host real machine. The VM can access the Yale network and internet, but the host computer cannot talk to it except through mapped ports. Unfortunately, if you expose a port to the Host computer you also expose it to the whole Yale network because it becomes a real port on the host computer.
- NAT Network - Several VMs are connected to a private network with a NAT router simulated on the host real machine. Like the previous configuration, except in this case the VMs can talk to each other as if they were real computers on a real network.
- Bridge - All the VMs appear to be directly connected to the real network to which the host computer is connected. At Yale, that means that every VM has to be assigned its own IP address from Data Network Operations. Since that address is real, no other developer can use the same set of addresses for his Sandbox machines. This also exposes the VMs to the outside world (at least the Yale network).
- Host-Only Adapter - First, this creates a virtual LAN adapter on the host computer (you get a dialog box on Windows asking you to install a new device). Then logically it connects this simulated LAN adapter to a Private Network to which all the VMs are connected. Typically you assign a static address like 192.168.137.1 to the host computer and then other static addresses like 192.168.137.10 to each VM. VirtualBox does not provide any DHCP or NAT router function, so if this is all you do then the VMs cannot talk to the Yale network or Internet.
The VMs have to be able to communicate with each other just like real machines, so they can test various clustering options. The VMs have to access servers in the Yale Network (SVN for example to update or commit source changes). You probably want to be able to communicate from the host computer to the VMs, to open a browser and test the application. However, you do not want computers other than the host to access the VMs and it is convenient if the VMs are always configured the same on all hosts.
No one configuration option on one LAN adapter handles all these requirements, but you can configure two LAN adapters with different options that provide everything you need and nothing you do not want.
One adapter uses a simple "NAT" connection to give the VM client only (no mapped ports) access to the Yale network (SVN) and to the Internet (the Centos software update sites). If you do not configure any Mapped Ports, then this LAN can only be used for client outbound connections from the VM.
The other adapter is a Host-Only Adapter that creates a simulated Private Network that connects the VMs to each other and to the Host computer. The host and VMs use 192.168.*.* addresses to talk to each other just like real computers connected to a regular network. The host can open a browser to talk to CAS, and two VMs can simulate data exchange for cluster fail over. The VMs cannot use this to access any other machine, and no other machine sees this network and any of its addresses.
NAT is an automatic service that is part of VirtualBox. However, a Host-Only network has to be set up before any VM can use it. In the VirtualBox management console (that lists the installed virtual machines). Click File - Preferences - Network. Select the Host-only Networks tab. If no network is listed, click the Add 
button to create one. It will be called VirtualBox Host-Only Ethernet Adapter and when you create it you have to let your real laptop operating system add a new device. If you double click the now listed adapter, you can set its IPv4 Address to 192.168.137.1 and the Network mask to 255.255.255.0.
The Sandbox VM comes configured with two LAN adapters.You can configure them when you import the VM from the original distribution file image, or you can reconfigure them in the VirtualBox management console before you start the VM. Select the Sandbox VM and click Settings - Network. Adapter 1 should be "Attached to" Host-only Adapter and Adapter 2 should be attached to NAT.
If you need to simulate a second VM, clone the Sandbox computer (as explained below) and then in the clone configuration you leave Adapter 1 attached to the same Host-only Adapter but now you expose the Advanced options and change the MAC Address to be one larger (change AD at the end to AE).
The Centos operating system in the Sandbox VM has two different configurations for two different LAN adapters with different MAC addresses. It selects which IP address it uses based on which MAC address the simulated LAN adapter exposes. The first VM (ending in AD) gets 192.168.137.10 and the second (AE) gets .11. However, it is not possible to automatically change the hostname based simply on the MAC address. You have to do that manually the first time you boot up the cloned second VM. Issue the following command once:
sudo hostnamectl set-hostname vm-ssoboxapp-02.web.yale.internal
to change the hostname permanently on that VM.
If you want more than two virtual machines, then you have to add a new Network adapter configuration in /etc/sysconfig/network-scripts and add a new line in all the hosts files.
Centos 7 like Windows has a built in Firewall that might be useful on a desktop machine. In a private virtual network it is useless, and it has been disabled by telling the OS to not start the firewall service ("systemctl disable firewalld"). If you reenable it, then you have to open port 40001 for Ehcache and other ports like 8080 for JBoss.
Clone
The Sandbox VM can be cloned to produce a second CAS VM for testing cluster failover.
Cloning is a VirtualBox operation performed on the VirtualBox control window. Select the machine and choose Clone from the Machine menu. There are two kinds of Clones:
A Full Clone makes a complete copy of the VM configuration and the hard disk. This is the simplest option, but it takes a few minutes to copy the hard drive.
A Linked Clone turns the existing hard disk image into a "snapshot" 13 gigabyte base file, then sets things up so that both the original VM and the clone use that snapshot as a starting point but maintain all changes made to the disk in a separate update file. Since the virtual disk file is not copied, this saves space on your hard disk and the clone is created in seconds instead of taking minutes. However, if you delete the clone and want to convert the original VM back to normal, you have to take a few seconds to delete the snapshot (which merges the changes since the snapshot file was created back into the file creating a single virtual disk file instead of the two files (snapshot and changes).
Once you create a clone, no matter which type you use, any changes that you make have to be duplicated on both systems. This is not a convenient way to do real development, so it is suggested that you create the clone only at the last minute (after you have run CAS Build and CAS Install and are ready to start JBoss) to test cluster configurations, and if you have to edit source and rebuild stuff then you delete the old clone and create a new one.
Every time you create the clone, before starting the clone VM you edit the LAN adapter to change the MAC address from one ending in AD to AE, and after starting the clone for the first time you issue the hostnamectl command as described above to change the hostname. The rest should take care of itself.
CAS Development
CAS development is the same whether you are working on a Windows host computer (with Eclipse and JBoss) or on the Sandbox VM. You edit in Eclipse, build with Maven, and run JBoss from the Eclipse toolbar. Generic CAS develpment is described elsewhere. This section just describes the Sandbox.
When you get a new copy of the Sanbox VM, the casdev user will have an Eclipse workspace in its home directory. This will have a project for the CAS source and for the CAS installer. However, the project may have old files. So the first step is to synchronize the workspace with the SVN server and update the files with whatever is current.
If you are starting work on a whole new release of CAS, then delete the old project and create a new project using the instructions provided in CAS Development Conventions at Yale.
There are two configured Maven "jobs" in the Eclipse Run - Run Configurations...
If you click the dropdown mark (V) behind the Run icon on the toolbar (a green circle with a right pointing triangle) then there is a CAS Build job (which runs the Maven POM in the CAS parent directory to compile everything and build the CAS WAR) and a CAS Install job (which copies the CAS WAR to the JBoss deploy directory and inserts parameters into the configuration files). Run the Build first, then the Install.
Elsewhere on the toolbar there are JBoss Run and Debug icons (a green arrow pointing right and a bug with an arrow under it). They can be used to start JBoss normally or with interactive debugging using Eclipse.
Changing the Sandbox
The Sandbox is separate from the contents of the projects in the workspace or the SVN. You could use the same Sanbox to develop with CAS 3.5.3 or CAS 4.0, and you could probably use it to develop any JBoss hosted application including Shibboleth.
Updating Centos 7 with newer versions of software or changing system configuration options is just standard Linux system administration.
Therefore, changing the Sandbox means installing a different version of Java, JBoss, or Eclipse.
You can install any version of Java using the Oracle RPMs. They go automatically into /usr/java. Generally you configure different versions of Java into Eclipse (Preferences - Java - Java Runtime) and then you select the verison of Java you want to target as a parameter of the Eclipse project, or as a parameter of the CAS Build and CAS Install Run configurations, or as a parameter of the JBoss Server runtime configuration. If you want to change the default version of Java that you get at the command prompt, Google for information on the Linux "alternatives" command.
There are separate instructions in this set of documentation for starting with a vanilla version of Eclipse and then adding the Subversive and JBoss Tools components, so they will not be repeated here.
To install a new version of JBoss, get it from jboss.org and unzip it into a new directory in /opt/jboss. JBoss Tools will configure it automatically if you ask. In Eclipse, go to Preferences - JBoss Tools, JBoss Runtime Detection. Click Search ... and have it search /opt/jboss. It will notice the new server and configure it. To change the default configuration, you need to display the Servers (Window - Show View - Servers). The Servers tab lists all the configured servers. Double click on the name of the server you want to configure. Click the "Open launch configuration" link for detailed startup configuration. In particular, you may want to allow browsers on other machines (actually only on the host computer) to access http://vm-ssoboxapp-01/cas by binding JBoss to the LAN adapter instead of just the local loopback. In the command parameters, change "-b localhost" to "-b 0.0.0.0". Also add a parameter to change the log directory "-Djboss.server.log.dir=/var/log/jbossas/standalone". If in doubt, compare this to the configuration of another JBoss server.
Disclaimer: configuring modern versions of JBoss AS 7, JBoss EAP 6.x, and Wildfly 8.x are all fairly similar. If you want to configure an older JBoss 5, that changes the entire directory structure and conventions and may require extra research.