Shiny Server Development Template
This repo is intended to be forked and used as a development repo for R applications that use Shiny 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 here.
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
server.R files as you wish.
To keep the shiny app as lightweight as possible, don't put anything extra or unnecesary into the
There are several steps you must complete in order to begin:
1. Install Docker
Instructions for installing docker on your local OS are provided here.
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 provided here.
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 here. Or you can simply use the command line, instructions for which can be found here.
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.
libproj-dev for the
rgdal package, or
libxml2-dev for the
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):
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
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):
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.
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:
docker build command will run with the
--no-cache flag. You might also want to first delete
Dockerfile.local to ensure everything runs smoothly.