This will create and run a local Shiny Server for R to enable viewing of the sample Shiny application and the creation of your own Shiny app. This is suitable for both local development and future deployment of a Shiny Server with your app.
Creating the server requires very few commands since the process is almost entirely automated by Fabric. The commands described below will create a virtual machine (VM) running Ubuntu Server 14.04 and install the necessary R and Shiny packages onto the VM, with R Markdown enabled (allowing the server to serve Markdown docs). Shiny app files will be editable using your host machine. The Shiny server will be accessed in your browser at localhost:7070. This should greatly simplify the process of creating a Shiny Server.
If you are using Windows the requirements and process should be similar, if not exactly the same. The installation of Python/Fabric is likely the only challenge, but both work on Windows if installed correctly. For ease, use Mac OS X or Linux.
System Requirements: 2GB RAM Min. and 3GB Free HD Space
Install the following:
- VirtualBox: https://www.virtualbox.org/wiki/Downloads
- Vagrant: https://www.vagrantup.com/downloads
- Fabric: http://www.fabfile.org/installing.html
It is likely that you already have Python, which Fabric requires. If you are
unsure, open Terminal and execute
The requirements above occupy ~200 megabytes of space (largely from VirtualBox and Vagrant). They can be removed once you are done with Shiny Server, but it is suggested that you do not uninstall them since they are common development tools that you might use in the future.
You also need to have an SSH key, since it will be used when setting up your
VM with Vagrant. See the GitHub instructions for checking for and creating
an SSH key. You do not need to go through Step 3 and 4 in their
instructions, and if you find a key named
id_rsa in Step 1 then you can
also skip Step 2.
Clone or download this repository onto your computer. Then open your Terminal
cd into the repository on your computer. Run
vagrant up to create
the virtual machine. Finally, run
fab vagrant setup_vagrant to install and
set up the Shiny Server and its dependencies. That's it! The last line in
your terminal should give you the status of your Shiny Server. Open your
web browser and using the address bar visit
localhost:7070 to view the sample app.
To shutdown the server execute
vagrant halt. This will stop the VM. To boot
the server again execute
vagrant up. You do not need to execute
fab vagrant setup_vagrant if the process completed successfully earlier.
If things do not run as expected see the Troubleshooting section below.
During the setup process, the Shiny Server on your VM was directed to look in a new shared folder called project that was created in your repository. When you view the sample Shiny app in your browser, the Shiny Server reads the files in this folder. Any modifications to files in this folder will be visible to the VM, so you can simply delete the sample app and develop your app in shiny/project/ on your host machine. (See the bottom of this Readme for a visual of the directory structure).
The setup sequence also created a folder called writeable-project in the
same location as project. In order to support certain apps' underlying R
functions, Shiny server sometimes requires write access to an app folder. Such
apps should be placed into (and developed in) shiny/writeable-project. In
project you will find a symlink named proj that points to the
app-writeable folder in order to give the Shiny server and your browser access
to apps in there. Try copying the sample-apps folder in project to the
writeable-project folder, then use your browser to visit
Notice that the name of the symlink is used
in the URL for apps in the writeable-project folder. You can rename the
symlink to adjust that portion of the URL. If you are developing an app in
project and you see
ERROR: Cannot open the connection in your
browser when trying to access the app, it probably needs write access.
If your app requires any additional R packages, SSH into the VM with
vagrant ssh (make sure you are in the shiny folder first) and install them. For
example, you can install the deSolve package with
vagrant ssh and then
sudo R -e "install.packages('deSolve', repos='http://cran.rstudio.com/')".
Note that some packages might have dependencies outside of R. For example, in
order to install the R package RCurl, you will first have to install
libcurl4-gnutls-dev on Ubuntu via
sudo apt-get install libcurl4-gnutls-dev.
Alternatively, if you're looking for something reproducible and you're familiar
with Python, you can add the installation of an R package to the
fab vagrant setup_vagrant sequence; check out the function
sub_install_additional_packages() in fabfile.py for instructions.
Since everything is installed into a VM, you can easily remove the VM to
uninstall the server and reclaim disk space. In your shiny folder,
vagrant destroy and then
vagrant box remove 'ubuntu/trusty64'.
For starters, know that you can destroy and reinitiate your VM and run
fab vagrant setup_vagrant as many times as you want. This is especially
useful if the setup process is interrupted. Some more specific problems and
solutions are below.
- If you see multiple
Connection timeout: Retrying....warnings after running
vagrant upand the process seems frozen, it is likely that you do not have an SSH key. See the link in the Requirements section for instructions on how to create one.
- If you had to install any of the requirements (VirtualBox, Vagrant, Fabric), try restarting your computer and beginning again. Make sure to destroy your VM before starting over.
- If you see an error regarding an installation of Paramiko when executing
fab vagrant setup_vagrant, remove Fabric and reinstall Paramiko: open Terminal and execute
sudo pip uninstall fabric, then
sudo pip install paramiko==1.10, then
sudo pip install fabric.
- If you do not see the project folder in your shiny folder (or
shiny-master if you downloaded a .zip of the repo) after you run
vagrant up, then Vagrant might be facing permissions issues when trying to create the folder. Delete your VM, create a blank folder called project in your repo, and start over. See below for the expected folder structure.
- If you see
ERROR: Cannot open the connectionin your browser when trying to access an app you are developing, the app probably needs write access. Try moving the app into the writeable-project folder.
- If you are running out of memory while trying to install a package you
can increase the amount of RAM available to the VM. Open up Vagrantfile,
which controls the settings for the VM, and edit the line that looks similar
["modifyvm", :id, "--memory", "2048"]. Change
2048MB (2.0GB), save the file, then execute
vagrant reloadto restart the VM with the new settings.
vagrant up completes, your directory structure should look like this:
fab vagrant setup_vagrant is done, you should have this:
| |-- index.html
| |-- proj
| |-- sample-apps/
| |-- hello/
| | |-- server.R
| | |-- ui.R
| |-- rmd/
| |-- index.Rmd
Any discrepancies in the above should give you some indication of where things went wrong.
- Grab the current stable version of Shiny from the site for always up-to-date installation
- Add a .Rproj so people can checkout from the repo directly in RStudio
- Add Fabric function to push to a production server on AWS
- Someone with a Windows machine please address PR #2