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

## Troubleshooting

Some common start up issues are shown below, if you want anything added please make a request on [GitHub issues](https://github.com/cloudyr/googleComputeEngineR/issues).

### I can't use apt-get/sudo/etc. when I SSH into an instance

If you are using one of the templates (e.g. RStudio) then they are launched within Docker.  A guide on how it uses them are in [this article](articles/docker.html).

The base VM that launches the Docker container is a custom Google stripped down version that only runs Docker and not other common linux commands such as `apt-get`, since their intention is you use those commands within the Docker containers running.

This means if you want to install dependencies, you should either:

1. (preferred) Use your own custom `Dockerfile` to install the dependencies. 
2. Run your commands from within the Docker container.  In RStudio, this is easiest via RStudio's terminal window available in the menu
3. Alternatively, when you SSH into the VM running docker, issue `docker exec -it {container name} bash` to drop into bash running within the container.  For RStudio, this would be `docker exec -it rstudio bash`

### I can't use SSH commands

* Make sure SSH authentication has been performed.  By default the SSH looks within the location set up when using the `gcloud SDK` so a quick way to ensure this is to install the gcloud SDK and authenticate through there.
* Sometimes your local username is not suitable (say it has spaces) - set a more linux friendly username in your SSH setup settings. `gce_ssh(vm, username = "goodusername")`

### The docker_* commands do not work

* The `docker_*` commands such as `docker_cmd()` rely on SSH, so make sure SSH is working correctly (see above) and you can run `gce_ssh()` correctly.  

### My custom Docker image isn't used

A guide on using [build triggers is here](articles/docker.html), that may help.  Common issues include:

* The name of the custom image is not correct - check you can pull the image correctly
* Check to see if the `docker ps -a` command (or `docker_cmd(vm, "ps -a")`) returns your Docker image name.  If it doesn't it has not downloaded or found your image
* The authentication to pull the custom image isn't correct - make sure you either use the same Google project or add the service email you use for the VMs as a user to container registry

### I try to create an RStudio instance but I can't connect to the I.P.

* Make sure your username is not `rstudio` as that username is reserved
* Make sure you are running on version `0.2.0` or greater, that ensure ports 80/443 are open in your default network.  (port 8787 is not required)
* Check to see if the Docker container is running by SSH into the instance and running `docker ps`
* If it is not, try running `container_logs()` to see if there was an issue on start up.

### My project ID isn't recognised

* Make sure you are using project-id and not Project name or number
* A bug in `v0.2.0` is it doesn't allow project ids with numbers.  Either use a project Id without numbers or load the GitHub version that fixes the bug

### My changes aren't saved when I relaunch my RStudio instance

* This is a feature not a bug :)  The initial RStudio is based on a vanilla version of Docker, which will not save your changes by default.  Customise your Dockerfile and/or save it to container registry to customise your RStudio environment.  A workflow illustrating that is [here](https://cloudyr.github.io/googleComputeEngineR/articles/rstudio-team.html) which saves your running RStudio to container builder for you.  An alternative [here](https://cloudyr.github.io/googleComputeEngineR/articles/single-scheduler.html) shows how to create and build your RStudio Dockerfile.