NCEAS’ Server

Overview

Working on NCEAS’ Server is similar to working on an entirely separate computer from the laptop or desktop computer on which you typically work. This means that you need to go through the steps of connecting GitHub to your “RStudio” again for the instance of RStudio accessed through Aurora. GitHub’s Personal Access Token is referred to as “token” hereafter for simplicity.

Getting Started on the Server

Necessary Software

The only software that you will need on your personal computer to get set up on NCEAS’ server is RStudio!

You likely have worked in the “Console” tab of RStudio (where run lines and outputs appear; see below) but RStudio has another tab to the right of the “Console” called “Terminal” which offers RStudio users access to the command line (a.k.a. the shell). If you are a veteran command line user you may prefer to use the standalone Terminal app on MacOS or PuTTY on Windows but for the sake of keeping your tool kit streamlined, we’ll walk through getting set up on NCEAS’ server using only RStudio’s Terminal tab.

The Terminal does not accept R syntax (and the Console doesn’t accept Terminal syntax) so you may notice that some of the code we’ll walk you through below is formatted differently than you would write an R script.

Get your Invite Ready!

After your group RSVP’d for this workshop, our team contacted NCEAS’ IT team to get you an invite email to create an account on the server. An example of what that email may look like is included below but there are two key pieces of information:

  1. Your username
  2. Your temporary password (covered by a red bar in the screenshot).

If you have not received that email, check your Spam folder for emails from Thomas Hetmank (hetmank@nceas.ucsb.edu) or Nick Outin (outin@nceas.ucsb.edu). If you have not received the email and it is not in your Spam, reach out to our team and we will work to get an invite sent to you.

Signing into the Server

In the following instructions, all words that look like this should be typed into the Terminal tab and run by pressing return or enter. Note that typing these commands into an R script or R Markdown will not work because it will attempt to run in the Console. All words that look [like this] (i.e., bracketed) should also be typed into the Terminal tab but the specific text should be replaced in a user-specific way that is clarified in the nearby text.

  1. In the Terminal pane of RStudio, you will “ssh” into the server by running the following code: ssh [your username]@aurora.nceas.ucsb.edu. It is @aurora because the name of the server is Aurora.

  2. If this is the first time you’ve accessed the server you will need to enter yes to accept the server’s SSH key.

  3. You will then be prompted to enter your [temporary password] (see the above email example). Note that the cursor will not advance as you type but it is registering your entries! There will be no indication that you are typing (such as: “•••••••••”) This throws off many users so hopefully the above note helps set your mind at ease.

  4. You will then be prompted to change your “expired” password. We consider your temporary password to be expired as soon as you use it because sharing passwords via email is not secure and this “expiration” lets you set the password to something that only you know at the outset of your time in the server. Note again that the cursor will not advance as you type but it is working! To update your password, enter your [temporary password], then [your strong new password] and finally re-type [your strong new password] to confirm it. Note that your new password should not be “your strong new password” :)

  5. You are ready to go! Run exit to log out of the server in the Terminal tab.

  6. Now that you have set a new password, use your favorite web browser (e.g., Firefox, Chrome, etc.) to access Aurora and click “Login to RStudio Server”

  7. In the resulting page, you can sign in with the same username and password you just signed in on the Terminal tab with.

  8. You should now be in something that looks very much like RStudio but is housed in a tab on your browser! We will work together from here on out so once you have reached this point, let our team know and we can gather the group before continuing.

If the above steps have not resulted in successfully accessing Aurora, consult NCEAS’ instructions on first login and/or SSH-specific instructions for Mac vs. Windows and/or email us!

Working on the Server

Step 1: Connect Server RStudio with GitHub

To begin, load the usethis package (install if needed).

# install.packages("usethis")
library(usethis)

Next, configure your name and the email address you use for your GitHub account.

usethis::use_git_config(user.name = "Jane Doe",
                        user.email = "jane@example.org")

If you would like to check that this worked, you can go to the “Terminal” tab (next to the “Console” tab) and run git config --global --list.

Step 2: Create GitHub Token

You may use your token that you already generated for your local RStudio if that is easiest, but you can also create a new token specifically for your Server identity.

To create a token, you can again use the usethis package to send you to the relevant part of the GitHub website.

usethis::create_github_token()

Once you have walked through that process and created a new token COPY the long string of letters and numbers. It is often a good move to take a screenshot of the token and store it on your computer for a rainy day.

Step 3: Store GitHub Token

To store the token in your server identity, run the following line of code:

gitcreds::gitcreds_set()

In the “Console” tab you will be prompted to follow a short set of questions (answered via entering numbers in the Console) including the Console requesting your GitHub token.

PASTE the long string you copied in the previous step into the supplied field and continue. Note that if you did not copy the token (or copied something else between then and now thus losing the token from your clipboard) you can refer to the screenshot we recommended you take upon first generating the token.

Step 4: Preserve GitHub Token

You will also need to tell the server to remember your token so that you don’t need to re-do the “Store GitHub Token” section every time you start a new R session.

Unfortunately, there are two limitations to this step:

  1. Storage can only be done in the “Terminal” pane with the command line (don’t worry, it’s only one line!)

  2. Storage must be for a finite amount of time (though it can be a long time!)

To make the system remember your token, in the “Terminal” pane of RStudio type the following:

git config --global credential.helper 'cache --timeout=10000000'

This will cache your “credentials” (i.e., your token) for a long time so that you need not worry about this for the time being.

Not running the above line will make your personal access token expire immediately in the system, even though GitHub considers its expiration date (that you set earlier) separately.

Optional Other Steps

You may want to configure additional settings, such as:

  • The default branch name (for new repositories)
usethis::git_default_branch_configure(name = "main")