9 VM configuration and maintenance

9.1 Updating the VM

The PEcAn VM is distributed with specific versions of PEcAn compiled. However, you do not need to constantly download the VM in order to update your code and version of BETY. To update and maintain your code you can follow the steps found in the Developer section in Updating PecAn and Code and BETY Database. However, if you are using the latest version of the PEcAn VM (>=1.7) you have the Dockerized version of PEcAn and need to follow the instructions under the DOCKER section to update your PEcAn and BETY containers.

9.2 Connecting to the VM via SSH

Once the VM is running anywhere on your machine, you can connect to it from a separate terminal via SSH as follows:

You will be prompted for a password. Like everywhere else in PEcAn, the username is carya and the password is illinois. The same password is used for any system maintenance you wish to do on the VM via sudo.

As a shortcut, you can add the following to your ~/.ssh/config file (or create one if it does not exist).

Host pecan-vm
    Hostname localhost
    Port 6422
    user carya
    ForwardX11Trusted yes

This will allow you to SSH into the VM with the simplified command, ssh pecan-vm.

9.3 Connecting to bety on the VM via SSh

Sometimes, you may want to develop code locally but connect to an instance of Bety on the VM. To do this, first open a new terminal and connect to the VM while enabling port forwarding (with the -L flag) and setting XXXX to any available port (more or less any 4 digit number – a reasonable choice is 3333).

ssh -L XXXX:localhost:5432 carya@localhost:6422

This makes port XXXX on the local machine match port 5432 on the VM. This means that connecting to localhost:XXXX will give you access to Bety on the VM.

To test this on the command line, try the following command, which, if successful, will drop you into the psql console.

psql -d bety -U bety -h localhost -p XXXX

To test this in R, open a Postgres using the analogous parameters:

library(RPostgres)
con <- dbConnect(
  Postgres(),
  user = "bety",
  password = "bety",
  dbname = "bety",
  host = "localhost",
  port = XXXX
  )
dbListTables(con)   # This should return a vector of bety tables

Note that the same general approach will work on any Bety server where port forwarding is enabled.

9.3.1 Using Amazon Web Services for a VM (AWS)

Login to Amazon Web Services (AWS) and select the EC2 Dashboard. If this is your first time using AWS you will need to set up an account before you are able to access the EC2 Dashboard. Important: You will need a credit card number and access to a phone to be able to verify AWS account registration. AWS is free for one year.

  1. Choose AMI
  • On the top right next to your name, make sure the location setting is on U.S. East (N. Virginia), not U.S. West (Oregon)
  • On the left click, click on EC2 (Virtual servers), then click on “AMIs”, also on the left
  • In the search window toggle to change “Owned by me” to “Public images”
  • Type “pecan” into the search window
  • Click on the toggle button on the left next to PEcAn1.4.6
  • Click on the “Launch” button at the top
  1. Choose an Instance Type
  • Select what type of machine you want to run. For this demo the default, t2.micro, will be adequate. Be aware that different machine types incur very different costs, from 1.3 cents/hour to over $5/hr https://aws.amazon.com/ec2/pricing/
  • Select t2.micro, then click “Next: Configure Instance Details”
  1. Configure Instance Details
  • The defaults are OK. Click “Next: Add Storage”
  1. Add Storage
  • The defaults are OK. Click “Next: Tag Instance”
  1. Tag Instance
  • You can name your instance if you want. Click “Next: Configure Security Group”
  1. Configure Security Group
  • You will need to add two new rules:
  • Click “Add Rule” then select “HTTP” from the pull down menu. This rule allows you to access the webserver on PEcAn.
  • Click “Add Rule”, leave the pull down on “Custom TCP Rule”, and then change the Port Range from 0 to 8787. Set “Source” to Anywhere. This rule allows you to access RStudio Server on PEcAn.
  • Click “Review and Launch” . You will then see this pop-up:

Select the default drive volume type and click Next

  1. Review and Launch
  • Review the settings and then click “Launch”, which will pop up a select/create Key Pair window.
  1. Key Pair
  • Select “Create a new key pair” and give it a name. You won’t actually need this key unless you need to SSH into your PEcAn server, but AWS requires you to create one. Click on “Download Key Pair” then on “Launch Instances”. Next click on “View Instances” at the bottom of the following page.

  1. Instances
  • You will see the status of your PEcAn VM, which will take a minute to boot up. Wait until the Instance State reads “running”. The most important piece of information here is the Public IP, which is the URL you will need in order to access your PEcAn instance from within your web browser (see Demo 1 below).
  • Be aware that it often takes ~1 hr for AWS instances to become fully operational, so if you get an error when you put the Public IP in you web browser, most of the time you just need to wait a bit longer. Congratulations! You just started a PEcAn server in the “cloud”!
  1. When you are done using PEcAn, you will want to return to the “Instances” menu to turn off your VM.
  • To STOP the instance (which will turn the machine off but keep your work), select your PEcAn instance and click Actions > Instance state > Stop. Be aware that a stopped instance will still accrue a small storage cost on AWS. To restart this instance at any point in the future you do not want to repeat all the steps above, but instead you just need to select your instance and then click Actions > Instance state > Start
  • To TERMINATE the instance (which will DELETE your PEcAn machine), select your instance and click Actions > Instance state > Terminate. Terminated instances will not incur costs. In most cases you will also want to go to the Volumes menu and delete the storage associated with your PEcAn VM.Remember, AWS is free for one year, but will automatically charge a fee in second year if account is not cancelled.

9.3.2 Creating a Virtual Machine

First create virtual machine

# ----------------------------------------------------------------------
# CREATE VM USING FOLLOWING:
# - VM NAME  = PEcAn
# - CPU      = 2
# - MEMORY   = 2GB 
# - DISK     = 100GB
# - HOSTNAME = pecan
# - FULLNAME = PEcAn Demo User
# - USERNAME = xxxxxxx
# - PASSWORD = yyyyyyy
# - PACKAGE  = openssh
# ----------------------------------------------------------------------

To enable tunnels run the following on the host machine:

Make sure machine is up to date.

UBUNTU

CENTOS/REDHAT

Install compiler and other packages needed and install the tools.

UBUNTU

CENTOS/REDHAT

Install Virtual Box additions for better integration

Finishing up the machine

Add a message to the login:

Finishing up

Script to clean the VM and remove as much as possible history cleanvm.sh

Make sure machine has SSH keys rc.local

Change the resolution of the console

Once all done, stop the virtual machine

9.3.3 VM Desktop Conversion

For a more refined desktop environment, try

  • replace xubuntu- with ubuntu-, lubuntu-, or other preferred desktop enviornment
  • the --no-install-recommends eliminates additional applications, removing it will add a word processor, a browser, and lots of other applications included in the default operating system.

Reinstall Virtual Box additions for better integration adding X/mouse support