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. Yale machine room servers do not have a interactive graphic environment, and they run everything in the background as a service. Developers need to compile, build, and debug. They need things to run interactively so they can start and stop JBoss. So the Sandbox has all the same elements as production, but they are installed in different directories and run under different userids than production. This does not affect code or configuration, and any minor details can be worked out when you get to DEV where the production environment is exactly duplicated.
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.2, and Eclipse Luna 4.4.1. 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)A Sandbox provides a pre-configured development environment that you can run on your laptop computer. The VM version provides a Linux system on which to test the software you are developing in an environment close to what is used in production. Although the Sandbox was originally created for CAS, it can also be used for Shibboleth, Netid, or any other Java Web application.
The Sandbox incorporates a number of steps that a new developer would have to discover by trial and error. Does your Java have the unlimited cryptography files and does it have the Yale Certificate Authority files installed? Do you have both a current Maven and the old Maven 2.2.1 that Jenkins runs? There are a few changes required to the standalone.xml configuration file in JBoss, and you need the database drivers installed. Have all of the servers, drivers, JREs, and versions of Maven been configured to Eclipse?
Its not that you cannot solve each of these problems in a new environment. It just takes days or weeks. The Sandbox makes it all just work.
That's Not the Way We Do It
Any single configuration requires making choices. A practical problem is that nearly everyone else has a different view about how things should be done. A single inflexible configuration won't be used by people who are sure they have a better way to do things. So the Sandbox is flexible.
You need an operating system. You can use Red Hat (the Fedora flavor if you want newest, or the CentOS version if you want to match production), or you can use Ubuntu. For that matter, you can probably use Windows.
The Sandbox permits this because Java is system independent, all the tools run the same way on all systems, and nothing has to be installed in a specific place by a standard installer. JBoss doesn't have to be in /opt, or /usr/local, or C:\Program Files. Eclipse can be unzipped anywhere you want to put it. Nothing prevents you from installing Java on your system with an RPM or apt-get or a Setup program, but that is not the version of Java the Sandbox is going to use. It will provide its own Java, Eclipse, and JBoss that will be perfectly happy coexisting with any other Java, Eclipse, or JBoss you may have already installed elsewhere. The only limit is that only one server can use port 8080, so when you run multiple servers you have to configure different port numbers.
The first attempt at a sandbox was driven by advice provided by the system administrators who create the production systems. They strongly urged us to adopt a version of the same VM they use in production. While that VM was able to run the program, it had no development tools to edit or debug. We could have used that VM just to run and remotely debug the code, but then we needed a different platform to run Eclipse. Alternately, you could upgrade the provided VM to have a full desktop environment, but now it was a substantially different environment. There may be some use for a copy of the production VM as a kind of PRE-DEV environment, but for most development the system independence of Java means you do not have to exactly duplicate OS. It is, however, important to exactly match the version of Java and JBoss or Tomcat on the target runtime.
Although we tend to use Eclipse, it is possible to use IntelliJ if you prefer. The OpenJDK version of Java is not recommended at this time, so the Oracle Java is provided.
The Sandbox is, by definition, not a production environment, and business applications do not have exotic VM host requirements for USB pass-through or emulation of particular motherboard hardware. Nor will you ever simply push a button and migrate the Sandbox image up into the cloud. So pretty much any VM host will work. We use and recommend Oracle Virtualbox because it is free, open source, and fairly comprehensive. We will not fight anyone who insists on VMWare Player or Windows 10 Hyper-V.
Of course the simplest thing to do is to accept the defaults and all our design decisions and treat the Sandbox VM as a utility device. You pick it up, you use it, and you don't confuse working to change the Sandbox with actually getting real work done. If that isn't good enough, then try to understand the design so you leave behind something others can pick up and use.
Two "Disks"
Originally the Sandbox was a single VM image on a single disk. That package binds the decisions that are important to the application under development (Java 1.7, JBoss EAP 6.2) with decisions that only matter to the user (Eclipse 4.4 or 4.5) and with choices of system (Fedora, CentOS, Ubuntu, or even Windows 10) that generate far more heated discussion than is helpful.
The solution was to create two separate virtual hard disks. One disk holds the system you have chosen to use (which mostly doesn't matter). The other holds some Java runtimes, Eclipse, some Mavens, some JDBC drivers, some JBoss or Tomcat instances, and some starter Eclipse Workspaces.
Ideally the two would be independent. However, there are a few executables that are different in Windows and Linux, so the Java Runtime, Eclipse, and JBoss are either Linux or Windows and there have to be separate versions of the development disk for the two platforms. The format of these two disks is identical (same directories, same contents, just different executables).
In Windows the second disk is mounted as the R: disk. In Linux it is mounted in the same way that Linux likes to mount portable disks or thumb drives (as /media/SandboxData).
There is almost no specialized configuration on any operating system. This paper will provide suggestions for configuring the virtual network that are useful guidelines for development, simple debugging, and complex debugging. However, you can use almost any version of any operating system as long as machines that run the IDE (Eclipse) have a GUI and desktop.
This also means that you can customize your OS to be exactly what you want, then use it with different SandboxData disks to do development on different applications (or you can put all the applications on the same SandboxData disk and run them all together).
Sandbox systems tend to be kept more up to date than production systems. If you really want to try something new out while working, it is not unreasonable to work with a stable Beta of the next release of the OS. Having the latest features at hand can be useful.
The SandboxData disks, however, tend to lag behind because they have to match an environment that is already in production. So you will find Java 7 instead of 8, or JBoss EAP 6.2 instead of Wildfly 9.
The Sandbox allows you to edit and debug source. You can change existing files and create new files. You can work with Java source or configuration files. After you are done with basic testing, the changes you make are committed back to the Yale Subversion server. Then they are then used by the Jenkins jobs to build the DEV, TEST, or PROD environment.
So the result of Sandbox development is reflected in changes to SVN. After code goes into production, you can keep your copy of the Sandbox around for further development, or you can discard it and start over again with a fresh new Sandbox in any future project. If you have strong feelings about Linux or Eclipse, you may choose to customize your Sandbox VM to your preferences, and then it makes sense to save it and use it for other development, even for other software projects.
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 desktop or laptop computer which becomes the "host". VirtualBox is an open source project, but Oracle also creates some proprietary extensions that you are prompted to install immediately after you install the base software.
...
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 so you know what the configuration means.
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.
The password for user casdev is not particularly secure, since it can only be used by the developer on the host machine. However, it will not be published here. Ask someone for it.
Where
Oracle Java comes in a standard Red Hat distribution format called an "RPM" that contains both the files and instructions where to put them. Oracle puts a JVM in /usr/local/java. Red Hat official RPMs for JBoss are not available without a subscription, and RPMs for Eclipse are typically several releases behind the current verison. 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.
...
There are a few things that have to go in the same place in the Sandbox and production. For example, the log files should be written to /var/log/jbossas on the Sandbox because that is where they go in production and that specific path has to go into log4j.xml. The JBoss Server configuration in Eclipse is modified to add -Djboss.server.log.dir=... onto the end of the JBoss start command.
The VM
The VM is a standard Virtualbox 64 bit Linux configuration. With JBoss running the used memory only gos up to 1.3 GB, so the amount of virtual RAM for the VM could be reduced to 1.5 or 2 GB if you need to run two VMs on an 8G laptop.
...
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.
...
Centos 7 has a Firewall service (firewalld) that, like the Windows firewall service, provides some protection to a desktop or server machine. It is not used in production machines behind the corporate firewall, and similarly it is not useful on VMs that are hidden on the Host-Only private virtual network, so that service is disabled in the Sandbox. It you want to turn it back on, you have to configure it for JBoss and the clustering.
Clone
The Sandbox VM can be cloned to produce a second CAS VM for testing cluster failover.
...
There are two steps that you must perform after you create the Clone to distinguish it on the network from the original VM. Before you start the Clone VM, edit the Settings - Network - Advanced - MAC address changing the last byte of the address by adding 1 (change the "AD" at the end to "AE"). Then after the clone starts up for the first time, issue the command "sudo hostnamectl set-hostname vm-ssoboxapp-02.web.yale.internal" to change the hostname. After you do this a few times it will become routine and deleting the old Clone, creating a new one, updating the MAC address, and changing the hostname will take only a few minutes and is much simpler and faster than copying files from one machine to the other.
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.
...
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.
...