Background
The TIER Grouper Virtual Machine software release is a Docker container-based virtual machine distribution that includes the ability both build the appropriate set of Docker containers and run the containers to provide a Grouper service. The operating environment includes appropriately configured Grouper and MariaDB containers networked together to build the Grouper service. The current distribution is based on Oracle VirtualBox. Other VM environments will be made available in the future.
A few words on VirtualBox
- If you are not familiar with VirtualBox, you can read the documentation and download the software from Oracle's web site.
- Once VirtualBox is installed and running, import the .ova distribution image using the File / Import Appliance function.
- The default network connection for the packaged Grouper Virtual Machine is Bridged. With a bridged network connection, the VM will use dhcp to obtain its IP address from your local network. If you have a network registration process in place on your campus network, you may need to register the MAC address of your VM before it is able to obtain an IP address. You can change the VirtualBox network configuration to NAT mode to look at the VM and its components this way but it is not recommended for general testing or production use. Remember, if you are on a public network, the VM will be exposed to the world and we publish the password on this web site. Note that Virtual Box bridge mode can not work with many wireless network adapters since the don't support promiscuous mode. A wired network connection is generally better for use with Bridged mode.
Setup Process
When you complete the process itemized below, you'll be able to see and login to the Grouper management page.
Once you have started the VM, login to the account grouper with a password of grouper. You can then use the Linux ip addr command to determine the IP address that has been assigned to your virtual machine. You will need this address (or its matching DNS name, if any) later in the process. We also recommend that you use a ssh client to login to the vm instead of using the terminal emulator provided by VirtualBox. The VirtualBox terminal emulator is very limiting.
Issue the following commands to configure Grouper:
cd work ./setup.sh
The setup.sh script generates a new key-pair, a certificate signing request, and a self-signed certificate. The script installs the self-signed certificate into /home/grouper/build/grouper/certs where it will later be built into the Docker container. For a production environment, you must take the certificate signing request from /home/grouper/work/crypto/server.csr, have it signed by a commercial CA, and place the resulting certificate in /home/grouper/build/grouper/certs before moving on to the next step.
Notewell: Virtual machines start will little to no entropy for the random number generator. If your build is for a production environment, be sure to run the VM for a while, moving data, etc., before running the setup.sh script.
Issue the following commands to build the containers:
cd /home/grouper/build/grouper bin/build.sh
Issue the following commands to run the containers:
cd /home/grouper/run/ bin/run.sh
Verification Process
The first step is to be patient and wait. The first-time startup of Grouper can take a couple of minutes. Wait two minutes before starting on the next step.
- Browse to: https://YOUR-IP-OR-DNS/grouper/
- Note: your first connection to this URL will be very slow (minutes are not unusual)
- If your browser times our, just retry the connection,
- Login as the Grouper Administrator
- Login Name: GrouperSystem
- Password: XXXXXXXXXX
If you are not familiar with Grouper, please review the on-line Grouper Training and other documentation.