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 casdev as owner.
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 have 1.5 or 2 GB of memory if your laptop is constrained.
Install the latest VirtualBox Guest Additions by mounting the CD image and then telling the OS to run the software on the CD.
With a version of Guest Additions built for the kernel you are running that matches the version of VirtualBox you installed on your host laptop, there is a seamless integration between the Sandbox desktop and the host desktop. The VM is configured for bidirectional Clipboard and Drag and Drop, although generally Drag and Drop do not work.
VirtualBox provides a feature called Shared Directory. You can designate a host directory (D:\sandbox is configured by default) that appears to the VM to be a mountable disk/filesystem. When automount is selected, this Windows directory appears to be located at /media/sf_sandbox. While sf_sandbox is owned by root, casdev is in a group that has full access to its contents. 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
VirtualBox has several different ways to emulate the virtual network to which the VM is virtually connected.
If you have only one VM, then you can use NAT. However, if you have two VMs then they cannot talk to each other.
You can bridge the VM to the real Ethernet adapter. However, then they need IP addresses on what is typically the Yale network. More importantly, they then become visible to the outside world and hackers can try to login to them.
So the best solution is ask VirtualBox to create a virtual Ethernet LAN. This involves creating a virtual Ethernet adapter on the host (Windows?) system that appears to be connected to an Ethernet contain the VMs. VirtualBox calls this a "Host-only Adapter". Your host computer looks like it has two Ethernet adapters to two different networks. The real adapter connects to the real Yale network and the internet, while the VirtualBox adapter connects to one or two VMs.
Following standard practice, the private virtual network is assigned a 192.168.*.* IPv4 address range. Windows likes 192.168.137.* for reasons that will become clear below. The host is assigned address 192.168.137.1 and the VMs are 192.168.137.10 (and 11 and so on). The VMs believe that the host 192.168.137.1 is the IPv4 gateway address connecting them to the Internet.
Which then means that you have to turn the host computer into a gateway, and since it has only its one real IP address and the rest of the world does not know about the private virtual network, it has to do NAT. Generally speaking, this is accomplished by Internet Connection Sharing (ICS) which is a formal name in Windows and a description of the configuration option on the Mac.
On Windows, go to Control Panel - Network and Internet - Network Connections. Right click the real Ethernet adapter (not the VirtualBox Host-Only adapter). Select Properties from the menu. At the top of the dialog there is a Sharing tab. Click the first check box "Allow other users to connect ..." and unclick the second checkbox. Click OK. There will be a large popup warning you (not very clearly) that this is going to change the IPv4 address of the other adapter (the VirtualBox adapter) to 192.168.137.1 and you should only enable sharing if this is OK. Since 192.168.137 is built into Windows, this explains why that particular address was selected for VirtualBox.
Now let us summarize the result of this configuration:
- The Virtual Machines appear to be real computers connected to a real network that they share with a LAN adapter on the host computer. This network is private with 192.168.137.* addresses and generally the outside world cannot see it or the two VMs connected to it.
- On the host computer, you can see the two VMs as if they were real machines. Since it is frequently more convenient to access these machines by name, at this point you should probably edit your "hosts" file (C:\Windows\system32\drivers\etc\hosts on windows, /etc/hosts on other machines) to include the IP addresses and fully qualified names and nicknames for the machines. Generally speaking, the VMs will have the same /etc/hosts configuration. Then everyone knows how to get to machine "vm-ssoboxapp-01.web.yale.internal" (a name just like the DEV, TEST, and PROD VMs in the Yale machine room). You can access them with a browser, or SSH, or any other tool just like they were real machines.
- However, the two VMs are invisible to anyone who is not on the host computer. No other machine can logon to them, or access their Web pages, or hack them.
- Because the host computer is serving as a NAT router, the VMs can access the Yale network and Internet as clients. They can access the SVN server to commit changes or update source. They can download software updates from vendor sites
- The network configuration is essentially the same on every developer desktop, yet nothing that one developer is doing is visible to or interferes with another developer even though everyone is using the same "IP addresses" for their private virtual network. It also works if you take your development laptop home, or use it outside of Yale, just as long as you don't try to connect it to a network whose native addresses are 192.168.137.*, in which case you are hosed. However, since Yale CAS requires AD or some other LDAP server to validate passwords, you need to be connected to Yale AD from the host computer or else install an appropriate LDAP server on your host computer, or temporarily reconfigure CAS to use a different password authentication source.
If you use a Mac or Linux as your native laptop OS, you are going to have to set up NAT routing yourself, although you might Google for "mac nat router" and start at http://www.cyberciti.biz/faq/howto-configure-macosx-as-nat-router/.
For typical development you can use a single VM. To test clustering and failover, you can clone the first VM. All you have to do on the cloned VM is (before starting the machine) change the MAC Address on the Ethernet adapter from 08:00:27:A9:84:AD to one more (change the AD at the end to AE). Then when the machine starts up, issue the command
sudo hostnamectl set-hostname vm-ssoboxapp-02.web.yale.internal
The VM is configured to support both MAC addresses, both hostnames, and both IP addresses (10 and 11).
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.
CAS Development
There will generally be a cas-server project in the Eclipse workspace, although it may not have current source code. Synchronize it to the SVN directory. However, if you are starting work on a whole new release of CAS, then delete the old project and check out and create a new project using the instructions provided in J2EE Development with Maven and Eclipse.
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.