CircosHeatmap-aardio/dist/lib/r-library/RInno/doc/cont-installation.Rmd

---
title: "Continuous Installation"
author: "Jonathan M. Hill"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Continuous Installation}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

RInno supports continuous installation of shiny apps through APIs to public/private BitBucket and GitHub repos. If you follow the directions in this vignette, RInno apps will call your repository each time a user clicks their icon. If there have been any hotfixes or releases since installation, the app automatically updates, letting its user know through a windows progress bar, and then opens normally. 

This feature requires:

1. A URL to the app's repo, `app_repo_url`. This should be the full URL like, https://github.com/Dripdrop12/RInnoApp.
2. A release tag on GitHub, or a version on BitBucket. If you forget to create a release, your app will error when it calls `get_remote_version` and `parsed_response`'s subscript will be "out of bounds."
3. An R package structure that can be installed via `remotes::install_github` or `remotes::install_bitbucket`. I recommend testing this before compiling your RInno .exe.

The release tag or version is compared with the package DESCRIPTION file, i.e. `0.0.0.9000`, to determine if the app should call `remotes::install_github` or `remotes::install_bitbucket` respectively. So update the app's version in both places (2 & 3 above) with each new version, otherwise the app will re-install every time its icon is clicked.


## R Package Structure

To connect a shiny app to a remote repository, the app must be on Github or Bitbucket, and it must be in the `inst/app` directory of an R package. The easiest way to do this is by creating a new project in RStudio and selecting R Package.  See Dean Attali's [Blog](http://deanattali.com/2015/04/21/r-package-shiny-app/) for a detailed tutorial on including shiny apps in an R package.

| package/ |      |         |
|------:   |:-----|:--------|
|          |inst/app/ |     |
|          |      |ui.R     |
|          |      |server.R |
|          |R     |         |
|          |...   |         |
|          |DESCRIPTION|    |
|          |...   |         |

The package should be called `app_name`, and within the DESCRIPTION file, `Package: app_name`. Make sure your app can be installed as a package by typing `ctrl`+`shift`+`B`.


## Bitbucket

On Bitbucket, enable issue tracking in the repo's settings. This will add Versions to the Issues section and make it accessible via BitBucket's API. Add `0.0.0.9000` to Versions and within the package's DESCRIPTION file, `Version: 0.0.0.9000`.

Then create an RInno installer:

```{r, eval=FALSE}
create_app(
  app_name     = "myapp",
  app_repo_url = "https://bitbucket.org/fi_consulting/myapp",
  pkgs         = c("magrittr", "httr", "shiny", "myapp"),
  auth_user    = "<read_only_username>",
  auth_pw      = "<password>")

compile_iss()
```

Or for custom installers, directly through `create_config`:

```{r, eval=FALSE}
create_config(
  app_name     = "myapp", 
  R_version    = "3.3.2", 
  app_dir      = "app",
  pkgs         = c("magrittr", "httr", "shiny", "myapp"),
  app_repo_url = "https://bitbucket.org/fi_consulting/myapp",
  auth_user    = "<read_only_username>", 
  auth_pw      = "<password>")

# -------------------------------------------------- Many steps later
compile_iss()
```

Shiny apps compiled/installed this way will call the BitBucket API on start up, and re-install every time there is an update to the BitBucket repo's version. For public repos, you do not need to provide `auth_user` and `auth_pw`.


## GitHub

On GitHub, create a release for the app. The release(s) tab is located on the repo's homepage next to branch(es) just before contributor(s). Add `0.0.0.9000` to the release tag and within the package's DESCRIPTION file, `Version: 0.0.0.9000`. This will make the release tag accessible via GitHub's API. For private repos, you will need to create an app [token](https://github.com/settings/tokens). 

Then create an RInno installer:

```{r, eval=FALSE}
create_app(
  app_name     = "myapp", 
  app_repo_url = "https://github.com/fi_consulting/myapp",
  pkgs         = c("magrittr", "httr", "shiny", "myapp"),
  auth_token   = "<app_token>")

compile_iss()
```

Or for custom installers, directly through `create_config`:

```{r, eval=FALSE}
create_config(
  app_name     = "myapp", 
  R_version    = "3.3.2", 
  app_dir      = "app", 
  app_repo_url = "https://github.com/fi_consulting/myapp",
  pkgs         = c("magrittr", "httr", "shiny", "myapp"),
  auth_token   = "<app_token>")

# -------------------------------------------------- Many steps later
compile_iss()
```

Shiny apps compiled/installed this way will call the GitHub API on start up, and re-install every time there is an update to the GitHub repo's most recent release tag. For public repos, you do not need to provide `auth_token`.


### A Note on Versions
A released version number consists of three numbers, `major.minor.patch`. [Semantic Versioning 2.0.0](http://semver.org/) is a good specification to follow because `numeric_version` will interpret it correctly:

```{r}
numeric_version("0.1.0") == numeric_version("0.1")
```

```{r}
# First release!
numeric_version("0.0.1") > numeric_version("0.0.0.9000")
```

This is important because RInno determines the `local_version` of the app via `installed.packages()`. If R cannot parse the version correctly, the continuous installation will be... nonstop. Users will love you.