CAS Windows Sandbox
- Howard Gilbert
You need the CAS Sandbox Virtual Machine if you are testing clustering (where you need to create two VMs) or to test something in the Linux environment that is used in production.
However, most of the time you are testing changes to the Spring Beans or the Spring Webflow or the Spring LDAP, and that works the same in all environments. If your desktop native environment is Windows, then it is marginally simpler to do the pure Java and XML programming in native Windows instead of a VM. For that, we have created the Windows Sandbox.
The Windows Sandbox is a directory instead of a VM. It contains installed and configured versions of Java, JBoss, and Eclipse sufficient to develop and test CAS, Shibboleth, and potentially other applications. It is completely self contained, requiring nothing to be Installed in Windows or configured in the Registry. You simply copy the directory to your machine and start using it. Of course you could us the normal version of Eclipse you already have on Windows, but then you will probably spend days getting the optional plugins installed and configured correctly.
Because all the tools are based on Java, they run on any operating system. To simplify the configuration and to make things portable from the Windows Sandbox to the VM Sandbox, all the tools are installed in Windows in the same place they are in the VM. This is a trick.
In the VM Sandbox, every tool is installed either where the vanilla installation process puts it or in the same path where it exists on the production system. Windows has an entirely different layout of its system disk (C:) but in Windows every disk letter creates its own root file system. So the trick is to take one unused disk letter (we use R: because it is unlikely to be already used on your computer) and create a sparse subset of the Linux file layout. Because Java generally regards "/" and "\" as interchangeable for file paths, if R: is the Windows "current disk" then the same path expression can be used on both Windows and Linux:
- /home/casdev/workspace (R:\home\casdev\workspace) is the Eclipse workspace
- /usr/local/shibboleth-idp (R:\usr\local\shibboleth-idp) is the Shibboleth code directory
- /var/log/jbossas/standalone (R:\var\log\jbossas\standalone) is the log file directory
And so on for the other directories. Now Java and JBoss are installed in the same locations (/usr/java and /opt/jboss) on both the Windows and VM Sandboxes, but they are not in the same path where you would find them in DEV/TEST/PROD. That is simply a restriction on the way that one can easily configure a Centos Desktop Linux compared to the way that Chef configures the production Linux VMs under Red Hat Enterprise Linux.
You may have your own version of Java and Eclipse installed on your existing Windows desktop, but the Sandbox uses its own embedded copies of Java and Eclipse instead. Java has a specific "cacerts" file for the Yale certificates, and a kerberos configuration, and the required policy files for encryption. Eclipse points to that version of Java, and a version of Maven, and that JBoss. Each specific customization has been discovered by trial and error, and it would take days to recreate them with another configuration.
The Windows Sandbox is completely driven from the included Eclipse application. Create a shortcut that points to that Eclipse and double click it to run. Eclipse runs Maven, starts and stops JBoss, commits changes to Subversion, and so on. Eclipse has global and per-project Preferences that define all the versions of Java available (1.6, 1.7, etc.), all the versions of Maven available, all the JBoss and Tomcat servers available, and so on. You can run a JBoss 5.0.1 under Java 1.6 or you can run JBoss EAP 6.2 under Java 1.7. You can run the Build job under Maven 3, but the Install job under Maven 2.2.1. You also configure available JDBC drivers and then connections using these drivers to various development databases. Having all this preconfigured in the Sandbox saves more hours of work.
Workspace Portability
Inside Eclipse you configure a number of external directories. The most important is the location of one or more Java Runtime environment (JDK or JRE directories). Eclipse itself runs under the default system Java Runtime, unless this is overridden by configuring a specific Runtime directory in the eclipse.ini file in the Eclipse directory. However, when Eclipse launches an application, or a JBoss, or Maven, you can select a specific version of Java from the list of configured Runtimes. Of course, you can also configure an external directory that contains a particular version of Maven, or of JBoss.
Many of these configurations go in the Workspace. Unfortunately, in Windows Eclipse normally embeds the full path including the disk letter of any configured directory. This means that a sandbox Workspace can be directly copied from one Windows Sandbox to another, but if you copy a Windows Sandbox Eclipse workspace to the Linux VM Sandbox, then you will have to find each configured R:\... directory and remove the disk letter. This usually takes 10 minutes and if you do it enough times you get better at it, but it is typically easier to check changes and projects into Subversion and then check them out in Linux rather than trying to copy the entire workspace.
The Maven Local Repository
Maven creates a "local repository" of JAR files that it downloads to use during the software development process. The default location is the .m2 subdirectory of your Home directory (in C:\Users\netid), so it is already different for every user of the same computer, but you can change its location by editing the Maven settings.xml file.
This directory is large and is used by all Maven projects run by the user, so it should not be a subdirectory of the Sandbox. Every time you check out a Maven project from Subversion into your Eclipse workspace and every time you run Maven any dependency JAR files required by the project are downloaded (typically from the Yale Artifactory server) to your local Maven repository directory.
This means that the JAR files representing Maven dependencies downloaded to the local Repository are outside the Eclipse and the workspace directories. As with all other external dependencies, Eclipse then generates a fully qualified path reference to these JAR files and stores it in the workspace project configuration. However, when one programmer shares a workspace with another programmer, these fully qualified references to C:\Users\fred\.m2 are now wrong, and besides the JAR files may not be downloaded yet on the other programmers machine. So after copying a workspace with Maven projects from one Windows user to another, it is necessary to update the projects by telling the Eclipse Maven plugin to rescan the project (as if the POM changed) to update dependencies. Select the entire list of Maven projects in the Eclipse left window (Project Explorer), right click on any of the selected projects, and then choose Maven - Update Project from the menu (or if you prefer, update the projects one at a time). Downloading JAR files can take a while, so give Eclipse time to do everything it needs to do in the background.
SUBST and VHD
Of course, you could buy a disk and make it your R: drive. You could reorganize your existing hard drive and create a new partition. There are two much simpler solutions.
The best solution, although it is a bit cumbersome, is the VHD (Virtual Hard Disk). Microsoft created it for their VM system, but in Windows 7 and 8 it can also be used as a virtual disk volume on the native Windows system. If you like the command line, you can use the diskpart command subcommands create, attach, and remove ("diskpart" and then "help" and "help create" etc.). For the purpose of the Sandbox, create an expandable VHD file with a maximum size of about 8G. These are administrator programs, so to use a VHD you have to be an administrator of your computer (which may not be true for many users of Yale "managed workstations").
A VHD is a file on disk (*.vhd) but it also appears as a very small hard disk. It simulates a real disk, so at first it is uninitialized and you have to put an MBR on it and then create a partition and then format it with a filesystem just as you would a physical HD you bought from Newegg.
While it is mounted, the VHD looks like a disk. After you dismount it, the *.vhd file is just a single file you can copy to a server or to a USB thumb drive to backup or share the entire collection of files it contains. While mounted you can do with it all the things you can do with a real disk, including symbolic links, access control, or sharing the disk on the network. Like a USB drive it can be ejected, and if you try to eject it while it is in use the system will warn you that other users or running programs will be affected.
If you want a solution that doesn't require admin privilege, that has always worked from a command prompt, and that is easy to dismount and switch, the "SUBST" command does what you want. SUBST was introduced 30 years ago on the DOS operating system for the IBM PC XT and AT computers. It assigns a disk letter to a subdirectory somewhere on another disk. The new disk letter is only visible to you, but within your Windows login it looks like a real disk letter to all programs and utilities. It goes away when you logoff, although you can delete or change it with another SUBST command.
Assume that you have copied or unzipped the Sandbox directory tree to your hard drive as D:\CasWindowsSandbox. If you open a command prompt window and type "subst R: D:\CasWindowsSandbox", then the subdirectories and file in that directory appear to be your R: disk.
SUBST is too simple. It creates a very weak or casual relationship between the disk letter and the directory, like a temporary symbolic link. When a program opens a file with a path that begins "R:\", it redirects the request to the directory mapped by SUBST. Because the open was simply redirected to the real file, Windows doesn't track programs that are using the R: drive. There isn't a real R: drive to track. So if you delete the SUBST mapping, or change it to point to a different directory, then Windows will not warn you that there is a running version of Eclipse that was previously using its Workspace directory through the mapping you just deleted.
Eclipse or any other program will continue to correctly use files that are already open. However, the Eclipse Workspace is a directory with hundreds of files that Eclipse opens and closes all the time. Change the disk letter mapping and in the middle of a session Eclipse suddenly loses its workspace or (worse) gets pointed to an entirely different workspace.
Because the SUBST disk letter is not associated with a disk letter, you cannot share it on the network, although you can share the original D:\CasWindowsSandbox directory on which it was based. (Yes, there is a third option. You can share the directory on the network, then do a "net use R: \\computer\sharename". However, this will really use the network and is much slower than the other options.)
Generally we recommend the VHD solution if you are an administrator of your own computer and suggest SUBST only if you cannot get admin privilege.
Installation
The Windows Sandbox will be on a network share or a USB drive. It can be a zip file or a plain directory. You copy it or unzip it.
To use the VHD, first create, initialize, partition, and format the VHD. Then copy or unzip the files to your new R: drive.
To use SUBST, create an empty directory on disk, use SUBST to associate the R: letter with that directory, and then copy or unzip the files to the mapped R:\ drive.
Generally the Sandbox will not be distributed as a *.vhd file. However, if there are exotic requirements for a special project (where you must have symbolic links or oddly named files) then that is an available packaging option and then SUBST is precluded.
Find the R:\opt\eclipse\eclipse.exe file and create a shortcut on your desktop or task bar. Generally speaking, you will only interact with the Sandbox using Eclipse.
Do a Maven - Update project to load all the JAR files into your local Maven repository. It might also be a good idea to do a Project Clean.
Because the source will probably be out of date, for each project to a Team - Update or a Team - Synchronize to get the latest files from SVN.
Long File Names
For some reason Eclipse likes to create files with names that are as long as the file system will allow. It appears to start with a really, really long string, then asks the file system "what is the longest file name I can use" and then it truncates the name to be exactly the maximum number of characters.
Unfortunately, in Windows the file system will hold files whose cumulative fully qualified path name is longer than the maximum file name allowed to programs or commands. You run into this problem when you use SUBST, because after "subst R: D:\CasWindowsSandbox" the same directory has two names. If you create R:\areallyreallylongfilename then as long as you access it through the R: letter you may be OK, However, if you try to access the same file using the base directory name D:\CasWindowsSandbox\areallyreallylongfilename then the path name has grown by 17 characters (the length of "CasWindowsSandbox") and a file name that was acceptable when accessed through the R: letter may not work when the same file is accessed through the native D: letter. If you have this problem, remap the directory with SUBST and do any copy or delete operations though R: