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).
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
Setting up the virtual network for the Sandbox is the most complicated configuration option. There are several possibilities, each with advantages and disadvantages.
First, we need to understand some basic Internet network terms. A private network connects some computers or virtual machines to each other, but not to the Internet or the outside world. If you connect computers at home to each other with an Ethernet switch but do not connect a router or a connection to an ISP, then you have a private network. To connect this private network to the outside world you add a cable or DSL modem and a "router" box, but these home routers use a protocol called "NAT". Your home has only one network address assigned to it by the cable or phone company, and all your browsers and mail clients on all your computers have to share it. NAT converts outbound requests from client programs in your home to server programs outside your home so that they all appear to the outside world to be coming from the one IP address managed by the router box. The NAT router connects to the outside service on behalf of the internal client program and it forwards traffic back and forth between the private network and the Internet.
VirtualBox can configure a VM to have a simulated Eithernet adapter that is backed by a NAT service on the host computer. This is a direct connection between the VM on the one end and the host computer on the other end. More than one VM can have a virtual Ethernet adapter that uses the NAT service, but the VMs cannot talk to each other. For that matter, they do not really talk to programs on the host computer either. They simply pass through requests from clients on the VM to servers somewhere on the Yale network or the Internet. From the VMs point of view (if you display network configuration with Linux administration tools) it sees a network with the VM at one end and a NAT router at the other end and nothing else on the network. Of course, the NAT router is connected to the outside world of real computers, but that is outside the router.
VirtualBox can also configure a VM to have a LAN adapter that is "bridged" to the real network of the host computer. The host, after all, has a wired or wireless LAN that connects it to the Yale network and through Yale to the Internet. Every real computer on the Yale network has to be assigned an IP address by Network operations. With a "bridged" LAN adapter, the VM acts like a real computer that shares the real network connection of the host computer. The downside is that the Yale network treats it as a second machine, which means it has to be registered with Network Operations and it has to be assigned its own IP address. This is typically more bureaucracy than anyone needs, although it is a good solution if you are running a Server operating system in your VM and you want other computers to be able to connect to it and use its services. CAS is a server of sorts, but developers generally do not need and in fact do not want other machines to connect to the CAS they are developing.
The VirtualBox "Host-only Adapter" creates a virtual private LAN. First, VirtualBox creates a dummy LAN connector on the host computer. In Windows you get a system dialog asking if you want to install a new device. It looks just like a real LAN adapter, only there is no hardware. Then VMs that are configured to use "Host-Only adapters" each get their own simulated LAN adapter hardware. VirtualBox connects the host computer and the VMs to each other as if all these simulated LAN adapters were plugged into a simulated Ethernet switch. The VMs can talk to the host and to each other, but VirtualBox does not create a NAT function.
There is a "NAT Network" that allows VMs to talk to each other and the outside world, but it does not allow the host computer to talk directly to the VMs.
Each solution has a problem. The simple NAT adapter does not allow the VMs to talk to each other and makes it hard for programs on the host to talk to programs on the VM. The bridged solution allows everyone to talk to everyone, but it exposes your VMs to the outside world and requires registering the VMs as if they were real machines. The private network allows VMs to talk to each other and to the host, but not to the outside world. The NAT Network allows the VMs to talk to each other and to the outside world, but not to programs on the host.
You can use the private network solution and then install a non-Virtualbox NAT service on the host OS. It works, but it is a fairly complicated configuration option. So eventually it became clear that the simplest solution was to configure two LAN adapters on each VM. One is connected to a private virtual network connecting the host computer and the VMs to each other. This allows CAS to replicate tickets between VMs and it allows a browser on the host computer to connect to CAS on a VM. The other virtual LAN adapter on each VM is connected through a NAT service to the Yale network and Internet. It allows the VM to communicate with the Yale SVN server or the Centos software update servers.
On the virtual private network, the host computer has IP address 192.168.137.1 and the Sandbox VMs have addresses starting at 192.168.137.10.
The Sanbox VM image is designed to be Cloned (a VirtualBox operation) to create a second VM for a CAS cluster. There are two hostnames (vm-ssoboxapp-01 and -02) with two IP addresses (192.168.137.10 and 11) on two Ethernet adapters (MAC address 08:00:27:A9:84:AD and AE). The distributed VM uses the first hostname, IP address, and MAC address. After cloning it, and before you start the cloned VM, change its MAC address so the last byte changes from AD to AE. When the cloned VM first comes up, issue the following command once:
sudo hostnamectl set-hostname vm-ssoboxapp-02.web.yale.internal
to change the hostname permanently.
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.