---
title: "Installation and Authentication"
author: "Mark Edmondson"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Installation and Authentication}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

# Setup

Google Compute Engine (GCE) lets you create and run virtual machines on Google infrastructure.  See the [general Google documentation here](https://cloud.google.com/compute/docs/).

Before you begin, you will need to set up a Cloud Platform project, and enable billing by adding a credit card.  

A quickstart guide to using GCE is [available here](https://cloud.google.com/compute/docs/quickstart-linux) for making your first VM via the web interface, if you are not familiar with GCE then its best to start there.

Pricing is [available here](https://cloud.google.com/compute/pricing).

For `googleComputeEngineR` you will need:

* Your project ID e.g. `my-project-name` (NOT your project name)
* Your preferred geographical zone to launch VMs e.g. `europe-west1-a`
* [Recommended] A `Service account key` json file, downloaded from the API Manager > Credentials > Create credentials > Service account key > Key type = JSON

## Setup video guide

A video guide to setup and launching an RStudio server has been kindly created by Donal Phipps and is [available at this link](https://www.youtube.com/watch?v=1oM0NZbRhSI).

```{r, echo=FALSE}
knitr::include_url("https://www.youtube.com/embed/1oM0NZbRhSI?rel=0")
```


# Authentication

## Auto-authentication via .Renviron

Authentication requires you to set environment arguments with your setup details.

These can be set in an `.Renviron` file located on your computer home directory - R will look in this file upon startup.  Read more via `?Startup`

The easiest way to find the right home directory is within RStudio, to click on the `Home` button in RStudio's file explorer.  Create a file via `File > New file > Text File`, save and call it `.Renviron`

My `.Renviron` file looks a bit like this:

```
GCE_AUTH_FILE="/Users/mark/xxxxx/auth.json"
GCE_DEFAULT_PROJECT_ID="mark-xxxxxxx"
GCE_DEFAULT_ZONE="europe-west1-a"
```

The `GCE_AUTH_FILE` points to the file location of the [service account JSON file](https://developers.google.com/identity/protocols/OAuth2ServiceAccount) taken from your Google Project.  The other arguments set the default project and zone.  

This file will then used for authentication when you load the library:

```r
## GCE_AUTH_FILE set so auto-authentication
> library(googleComputeEngineR)
Successfully authenticated via /Users/mark/auth.json
Set default project name to 'mark-xxxxx'
Set default zone to 'europe-west1-a'

> gce_get_project()
$kind
[1] "compute#project"

$id
[1] "43534234234324324"

$creationTimestamp
[1] "2015-05-08T15:22:38.416-07:00"

$name
[1] "mark-xxxxx"

...etc.... 
```


## Other authentication methods

If you can't use an `.Renviron` you can set environment files within the script via `Sys.setenv`:

```r
Sys.setenv("GCE_AUTH_FILE" = "/fullpath/to/auth.json")
```