shinyhero

• Documentation
• Using this template
• Setup
  • Install
  • Build
• Testing
  • Test your Shiny Application locally
  • Test your Docker container locally
  • Test your Heroku deployment
• Automate
  • Heroku
  • Travis CI
• Sources and Links

Documentation

We've included a docs folder with a template Tech Spec and Best Practices document, though using Github's Wiki capabilities is also a good idea. This will get you started with documenting your project. Other documents and relevant information that has no other place can live in the docs folder. Replace this paragraph with a brief breakdown of what you've included in your docs folder.

Using this template

• You want more flexibility than shinyapps.io allows
• You don't know much about CI/CD, PaaS, and other devOps tools
• You want a clear path from building your tool to sharing it with the world without compromises

Setup

Install

• Git
• Docker
  • Docker is straightforward to use and install on Linux, OS X, & Windows 10 Pro
  • Please see the docs folder for additional instructions on installing and running Docker on Windows 10 Home
• Heroku CLI
• R
• RStudio
  • Optional
• renv

Build

• Click the "Use this Template" button to set up a Github repo for your project
• Copy the link to your new Github repo
• Clone your repo to your machine:

git clone https://github.com/<yourGithubAccount>/<yourProjectName>.git

• Change the name of shinyhero.Rproj to <yourProjectName>.Rproj
• You should now have the following file structure:

<yourProjectName>
│   .dockerignore
│   .gitignore
|   .Rprofile
|   .travis.yml
|   Dockerfile
|   LICENSE
|   README.md
|   renv.lock
|   <yourProjectName>.Rproj
|
|───.github
|     |   ...
│
└───app
|    │   global.R
|    │   ui.R
|    |   run.R
|    │   server.R
|
|───docs
     |   ...
|
|───renv
     |   ...

• Open your project's RStudio Project file
• You will have no packages installed or accessible from your project
• Run in the R console to install packages from renv.lock:

renv::restore()

• If you have issues installing any packages, run to re-build renv.lock:

renv::init()

• You should now have all R packages needed to locally run the basic example application in app/

Testing

Test your Shiny Application locally

It is a good idea to test the application provided before building anything more complicated:

shiny::RunApp('app/')

Test your Docker container locally

Go to your terminal

• Make sure Docker is set up correctly on your machine:

docker ps

• Move to your application's directory
• Build your Docker image locally:

docker build -t <yourProjectName> .

• Run a docker container from your image:

docker run --rm <yourProjectName>

• Point your browser to http://localhost:3838
  • More complicated if running on Windows 10 Home, see docs

Test your Heroku deployment

• Make sure you're logged into Heroku:

heroku login

• Login to the Heroku container registry:

heroku container:login

• Create a Heroku application in your project directory:

heroku create <yourProjectName>

• Build a Docker image to the container registry:

heroku container:push web -a <yourProjectName>

• Release your app to production:

heroku container:release web -a <yourProjectName>

Automate

You should now have:

• A functioning app that you can run locally
• The same app deployed to Heroku through the Heroku container registry
• You could keep iterating manually by building locally and deploying through the CLI
• An automated CI/CD pipeline is a more robust solution

Heroku

• To automate the build pipeline you will need to generate a Heroku API Key
• Run in your local machine's terminal:

heroku:auth token

• This should reveal your API key. If not, go to your Heroku account settings and copy your key after revealing there

Travis CI

• Set up Travis CI by connecting your Github account at travis-ci.com
• Having a Github repo with a .travis.yml file should automatically enable Travis to run on each push
• .travis.yml will not need to be changed, but you will need to provide environment variables to build successfully
• Go to the settings of your project's repo on travis-ci.com and scroll down to Environment Variables
• You will need two variables to build successfully: HEROKU_API_KEY and HEROKU_APP_NAME
• Paste the Heroku key copied earlier into an environment variable named HEROKU_API_KEY
  • NOTE: Make sure "Display Value in Build Log" is unchecked so you do not expose your key
• Create a second environment variable named HEROKU_APP_NAME which is the name of your app on Heroku, likely <yourProjectName>
  • This value can be displayed in the log as it is not a secure credential
• You should now have an end-to-end development pipeline from locally building to hosting on the Heroku PaaS

Sources and Links

If referencing any third party service, code, etc, cite it here.