cpsievert/simple-r-shiny

Shiny Server Development Template

NOTE TO SELF: This repo was used to build a docker image which is hosted https://hub.docker.com/r/cpsievert/simple-r-shiny. Also, this image is linked to openshift -- <[***]>

Introduction

This repo is intended to be forked and used as a development repo for R applications that use http://shiny.rstudio.com/ as a visualization server. The code is designed to run locally in development using Docker, and can be productionized using your github repo through OpenShift.

Where do I put my code?

All of your code goes into the app directory. Data goes into the app/data directory and web resources such as css and images go into app/www directory. If you need to write data to the server, ensure that the data gets written to the output folder as shown https://github.com/bcgov/simple-R-shiny/blob/master/app/app.R#L52. If you have a README for your project, please also put it here. Your Shiny code can go into one file (app.R) as per the example, or you can split it into seperate ui.R and server.R files as you wish.

To keep the shiny app as lightweight as possible, don't put anything extra or unnecesary into the app directory.

Getting Started

There are several steps you must complete in order to begin:

1. Install Docker

Instructions for installing docker on your local OS are https://docs.docker.com/engine/installation/ "Yeah! Install Docker".

2. Fork this repo

This repo is already set up to work with Docker and Openshift, so it is simplest to fork this repo into your own, and thereby take advatage of any future changes to the tools provided. Instructions for forking into your own github repo are https://help.github.com/articles/fork-a-repo/ "Fork Repo in Github".

3. Clone to your machine

You now need to clone the new repo onto your local machine so that you can start entering your code and developing. There are many graphical tools available that can help manage this, some of which can be found https://git-scm.com/download/gui/linux "Github GUI". Or you can simply use the command line, instructions for which can be found https://git-scm.com/book/en/v2/Git-Basics-Getting-a-Git-Repository "git command line".

4. Edit the packages.txt file

The packages.txt file contains an array of strings that indicate the packages you will be using in your R program. This list is used when building your local Dockerfile so that the build process runs as fast as possible. If you are familiar with Docker you know that you can also set environment variables that import this information, however this prevents the build process from using the cached layer for this step. Therefore the packages.txt file is used to build an explicit local Dockerfile that ensures fast repeated builds.

The packages.txt file should look something like this (package names separated by a space, no quotation marks):

package1 package2 package3

with all packages on the same line.

Do not include 'shiny' or 'rmarkdown' in packages.txt as they are installed automatically.

5. Edit the system-libraries.txt file

If any of the R packages you need to install require special system libraries (to be installed with apt-get install; eg. libgdal-dev and libproj-dev for the https://cran.rstudio.com/web/packages/rgdal/ package, or libxml2-dev for the https://cran.rstudio.com/web/packages/xml2/ package), list them in this file. It works similarly to packages.txt to build an explicit local Dockerfile that ensures fast repeated builds.

The system-libraries.txt should look something like this (libraries separated by a space, no quotation marks):

lib1 lib2

6. GitHub-hosted Packages

Many times you will build a Shiny App that requires R Packages (or versions) that are only available from GitHub. These are installed using devtools::install_github. List them in the gh-packages.txt file, as space-separated strings made up of the GitHub user/organization and repository name. It's also recommended to specify a the SHA of a specific commit or release tag.

The file should look something like this (separated by a space, no quotation marks):

ropensci/plotly@a1613b3e225 tidyverse/ggplot2@v2.2.1

7. Run / Develop

With all your packages listed in the packages.txt file, and your code in the app directory you should be able to run ./dev.sh at the command line (on Windows use the Docker Quickstart Terminal) in the root of your project to initiate Docker.

$ ./dev.sh

This command will build a local Dockerfile and run it for you. All of your code will be added to the container and run. Especially important is that new directories will appear in the root of your project under the '_mount' directory:

• _mount/bookmarks : This is where shiny will write its bookmarks
• _mount/logs : Pretty much what you might expect
• _mount/output : In your program, if you write to '/srv/shiny-server-output' it will show up here
• _mount/tmp : The /tmp directory if you need to debug the temporary files created by shiny

Note to Windows users: If you are on Windows and using Docker with VirtualBox, it unfortunately won't be able to mount the logs and bookmarks folders locally (i.e., _mount directory won't be created), but it will build and lanch the app.

The first time you run dev.sh you will see a lot of output where docker is building the container image for the first time and installing all the dependancies. On each successive run as you modify your code and run dev.sh, you will see that only your new code gets placed into the image and run. If you add new packages do not forget to update the packages.txt file or you will see the missing packages errors in your R program logs.

If you want to rebuild the image from scratch, you can run:

./dev.sh --no-cache

and the docker build command will run with the --no-cache flag. You might also want to first delete .packages.txt, .gh-packages.txt, .system-libraries.txt, and Dockerfile.local to ensure everything runs smoothly.