November 21, 2023
Steps to Creating a ShinyApp:
Before accessing the Partners Shiny App server, you should first design, develop, and test fully within your own local Rstudio or on the Partners Rstudio server environment. To push an app to the Shiny server you first need an account. If you do not already have one, request one by filling the form.
Setting Up the App Directories
Start by creating directories and subdirectories with short, easily understood names. These will eventually become part of the URL for your ShinyApp. You need to create a directory called ShinyApps which contains subdirectories or all the code.
Example:
For three different apps: App1, FancyApp, and BigApp. If you were to look at the URL for FancyApp it would appear as:
https://shiny.partners.org/users/<yourusername>/FancyApp/
And should appear as the following:
Make sure your folder names do not contain spaces or separations. This will make it difficult to edit, move, or interact with your directory later. For example, if you want to name a folder “My Test Folder”. Instead, use MyTestFolder or My_Test_Folder as similarly understood options.
Note: The folder containing your apps must be named ShinyApps! Otherwise the server will not be able to recognize that those are your apps.
Developing New App Contents
After setting up your environment with properly named folders, open your user version on the RStudio server, and create multiple R script files: a file named server.R and a file named ui.R. When you first save these files make sure they are in your app folder. You can see the path of your files in RStudio as well.
If you are planning on incorporating outside data that is utilized by your app adding a Global file, which is used to clean and organize data in data frames, matrices, etc., would most likely be helpful. These files need to be in the same folder. If they are separated, RStudio will not be able to properly build your app.
Adding Packages to Your Environment
Add any packages or libraries that you know you will be using for your app. In order to have a shiny app you must include the “shiny” package. Another useful package that often collaborated with shiny is the “shinydashboard” package.
Make sure to keep your scripts organized by putting all libraries and libraries required for that file at the top of the page, as demonstrated below:
Packages and libraries can be added or removed in your project at any time before adding your app to the server. If you do not know how to install packages or add them to your projects, jump to those instructions by clicking here:
The User-Interface
To create a shiny app interface that yourself and other users will interact with, first take a look at the ui.R file. Underneath the packages placed at the top of the file, you will create a shinyUI and a dashboard. This is done by typing out shinyUI( ), then nest the dashboardPage() function within the UI. A dashboard page usually consists of three aspects: a header, a sidebar, and a body. After adding all of these aspects to your ui.R you should have similar results to the following:
Note: Any of the three internal aspects can be removed at any time and still create a functioning app. The dashboardPage is the only aspect of this that must be present to have a shiny app.
Interactive App Elements
Taking a look at the created ui.R file or the user interface file for your ShinyApp. Here, you add and create various interactive elements from plots, calendars, slider bars, and graphs. Basically, it is used to control how users will view your App and its layout. The various elements available to be added to your user interface can be found here:
https://shiny.rstudio.com/gallery/
CSS & HTML App Elements
To further amplify your display, you can add extra details and features using CSS and HTML. To do this, within your app create a folder called www. R automatically recognizes this folder as a source folder to grab images or import design aspects of your app/project. Within the www folder, create a file called custom.css. You can learn how to write a custom css file and all of the capabilities of these design options at the following links:
https://www.w3schools.com/css/css_examples.asp
The App's Server
Move to your server.R file. Here is where you will be defining the logic necessary to build all elements of your Shiny App. For example, if your app has a data plot, you will be defining what the actual content of the plot is within the server file.
If you are using a Global.R file after adding the packages at the top of the script, if you have not done so yet, add the following line of code:
source('Global.R', local = TRUE)
When using large amounts of data through the Global.R file that you created earlier, this will make your app run more efficiently.
Next, insert the shinyServer() into the server.R script. The basic server.R file for a functioning shiny app should look like the following:
Building Your App
Build your app using the provided links or the many resources that are available online, import your data, and test your app. Once your app appears as you desire and has been thoroughly tested, prepare to move to the server.
Other sample apps are available here:
Testing ShinyApps on Your Scientific Computing (SciC) Linux Clusters Home Folder
To fully test your App, you should make sure it works not only in your local environment but also in the remote partners development environment. By also testing in this environment, you are ensuring that your App will work when put into production.
This development environment can be accessed by opening your terminal and ssh-ing into SciC Linux Clusters
$ ssh <yourusername>@erisone.partners.org
Once you have accessed your home folder in SciC Linux Clusters, execute the following commands to set up your apps in the remote environment:
$ mkdir ShinyApps
$ cd ShinyApps
Next, you are going to need to enter your Gitlab where the project for your app is held. If you do not have a Gitlab set up or do not know how to establish one for your project, jump to the instructions below. Once you have accessed your project in the top right hand corner of the project page, click clone, and copy the link labeled "clone with HTTPS".
Return to the terminal where your ssh session in SciC Linux Clusters is still open and run the following commands
$ git clone <pastethelinkyoucopiedhere>
Seeing your app has appeared in the remote server, you can now test its functionality by opening a browser and visiting the following link:
https://shiny.partners.org/users/<username>/
This should result in an index of all of the apps you have in your ShinyApps folder. Select the app you would like to test and wait for it to load. If, instead of your app, you receive a notification stating that there has been an error in opening your app, you can find the problem by taking a look at the log folder in the server.
This can be done from your terminal by cd-ing into the following:
$ cd ~/ShinyApps/log
This folder will keep all the logs of the apps you are testing under your ShinyApps folder.
Getting Your App on the Server for Production
Make a request to add your app to the partners shiny server. This can be done here:
Before going to submit a request for access to the partners shiny server, make sure you have a list of all the packages that you use in your app as they will need to be included to fully complete your request.
Once your app has been copied from your user account to the server, run the app to ensure that there are still no errors and that all packages required to run your app are present and functioning.
Gitlab and Backing up to Multiple Locations
If you do not already have a Gitlab established through Partners for your project, or do not know how, follow the steps below:
1.) Login to your GitLab at gitlab.partners.org
If you do not already have a Gitlab through Partners, request one here:
2.) Follow the steps here for setting up a new project in Gitlab:
You will most likely be following the steps of Push to Create a New Project as your project already exists in your local setup.
3.) Once your Gitlab Project is successfully set up, you can push to Gitlab to backup your work as well as update your app on the server. This can be done by using the following commands
$ git status
$ git add <the names of the files that you have updated and want to add to the Gitlab>
$ git commit
$ git push
Or you can follow the instructions below:
All of these commands can also be executed on the server side of your App as well. Make sure not to make changes in multiple locations (server and local) as it will confuse the Gitlab's ability to track changes.
Helpful Tips
- If you wish to have your app name displayed on the tab of the browser when other users use your app, in your ui.R file add within the dashboardHeader() a line of code stating title = “Your Title Here”.