- Table of content
- Description of the repository
- Preparation
- How to run the examples
- How to prepare and run your own case study apps
- Reference
- Software version info.
- Contact
This repository contains all source files for constructing the EDSS framework. The main folder structure and its description is given below:
├── README.md # The markdown file that renders this page
├── ShinyApp_Image # Folder that contains the Shiny application examples
├── ShinyBase_Image # Folder for building the "rshiny-base" image
├── ShinyProxy_Image # Folder for building the ShinyProxy image
├── config # Folder containing the configuration files
├── database # Folder containing external data files used by Shiny applications
├── log # Folder containing log files
├── run_examples.yml # The Docker compose file for running example
├── docker-compose.yml # The Docker compose file for deployment
The following two programs need to be installed on the machine in order to use the EDSS framework.
Windows and Mac users can install the desktop version which comes with Docker Compose. The installation file can be downloaded from here (Mac) or here (Windows). In addition, the directory to your app's working folder must be added in the resource list under FILE SHARING
in Docker (see figure below).
Figure. The
FILE SHARING
setting in Docker.
Linux users please refer to the office guide here for installation under different Linux distributions.
Run following commands:
sudo curl -L "https://github.com/docker/compose/releases/download/1.25.4/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose
Important: For users who want to run the system on their server, make sure the port 80 and 443 is open on your machine to allow the data traffic from outside.
First of all, please download the framework from here and extract it.
-
Open your command line tool, e.g.,
Terminal
(OSX or Unix),Powershell
(Windows); -
In the command line window, navigate the working directory to the EDSS folder by typing
cd path_to_EDSS_folder
. Replacepath_to_EDSS_folder
with the actual path name of the folder; -
Download all examples by typing:
docker pull cocomcie/test_ic docker pull cocomcie/test_2dmodel docker pull cocomcie/air_gr docker pull cocomcie/virtue
This step only needs to be done once.
-
Start the program by typing
docker-compose -f run_examples.yml up -d
. The program will download a few necessary packages (takes about 2-3 mins depending on Internet connection), and then it should be running in the background; -
On the browser, one can then access the database and the apps as below:
-
Shiny apps: visit
https://localhost:80
and login the app using a valid username and password. A list of legitimate users are given below:username password privilege admin edss123 can access all apps jack guest123 can access some apps david guest123 can access some apps -
MySQL database: visit
https://localhost:8080
with root for the username and example for the password;
-
-
To shutdown the system simply typing
docker-compose -f run_examples.yml down
;
First of all, please download the framework from here and extract it.
Assuming one has already developed the Shiny app, deploying the app requires following three steps
- Build the Docker image for the Shiny app;
- Adapt the configuration file for ShinyProxy;
- Deploy the system;
First of all, please refer to test_template
under ShinyApp_Image
folder as the template to create your own applications.
- Put your Shiny app files under the
app
folder; - In your command line window, navigate to the folder where your Dockerfile is located;
- Run the command
docker build -t image_name .
to build the image, where theimage_name
is an arbitrary name for the image in lower case letters without space. The sameimage_name
must be used in ShinyProxy configuration file (i.e.,application.yml
); - Test the image by running
docker run -p 3838:3838 -d image_name
. Then open the browser and visit pagehttps://localhost:3838
. If the image is successful, you should see your Shiny application's UI just as if it is run in R;
The following two files need to be adapted:
config/shinyproxy/application.yml
for configuring the Shiny apps;docker-compose.yml
for configuring the secured Internet access to your server;
The ShinyProxy use application.yml
to configure the program. The provided one in this repository provides a minimal working example.
It is mandatory to adapt application.yml
by adding your Shiny application so ShinyProxy knows where to find and manage it. To add it, go to line 18 specs:
section and add following fields
- id: 02_testApp # unique Id for your Shiny app
display-name: Crop Water Demand Calculator # name to be displayed on the main page of the ShinyProxy
description: Application which demonstrates the crop water model in a dashboard layout # description of the applicaiton
container-cmd: ["R", "-e", "shiny::runApp('/root/shinyapp', host='0.0.0.0', port=3838)"] # don't change it
container-image: cocomcie/test_ic # the image name of your Shiny app
container-network: "${proxy.docker.container-network}" # don't change
access-groups: [scientists, stakeholder] # define which group users can access this app
Users may also want to change authorization configuration, which can be found at users
section. Three fields shall be created for each designated user:
- name: admin # username
password: edss123 # password
groups: admins # the group it belongs to. Users can define different user groups to limit access to certain apps
Repeat such block as many times as the number of apps you want to add. Additional adaptation is optional and for the full configurable options please visit the ShinyProxy website here.
⚠️ Two users cannot use the same username to access the app, otherwise one will be disconnected.⚠️ Only include the Shiny apps whose images have been built.
Here we assume that you have a server connected to the Internet, and a resolvable domain name (e.g., www.example.com) that points to the IP address of your server. Otherwise you might consider to buy one from any cloud provider and domain seller.
For the server configuration, all you need to do is the following three steps:
- Replace the
subdomain.yourdomain.com
(line 24 and 25) with your own subdomain name; - Replace the
another_subdomain.yourdomain.com
(line 45 and 46) with another subdomain name your created, which is different from the one in Step 1; - Replace the
your_email_addr
(line 101) with your email address. This is used to receive notification for https certificate;
After completing all those steps, you are ready to proceed to server deployment.
- Start the program by typing
docker-compose up -d
; - Now the system should be running on background. Wait for a few minutes and then one should able to access your application on the Internet via the domain name you have;
- Use the username and password you defined in the
applicaiton.yml
file to access the Shiny apps; - To shutdown the system simply typing
docker-compose down
;
The log
folder containers the log files for debug. In specific,
log/container
folder holds logs for containers;log/nginx
folder holds logs for Nginx server;log/server
folder holds logs for Shiny applications;
- ShinyProxy
- Docker
- Shiny
- Nginx
- Letsencrypt
- AirGR: Coron, L., Thirel, G., Delaigue, O., Perrin, C. and Andréassian, V. (2017). The Suite of Lumped GR Hydrological Models in an R package. Environmental Modelling and Software, 94, 166-171. DOI: 10.1016/j.envsoft.2017.05.002.
- ViRTUE: Whateley, Sarah, Jeffrey D. Walker, and Casey Brown. "A web-based screening model for climate risk to water supply systems in the northeastern United States." Environmental Modelling & Software 73 (2015): 64-75.
Image name | version |
---|---|
nginx-proxy | latest |
nginx-proxy-letsencrypt-companion | latest |
shinyproxy | 1.0 |
MySQL | latest |
Package name | version |
---|---|
R | 3.6.1 |
shiny | 1.4.0 |
shinydashboard | 0.7.1 |
shinythemes | 1.1.2 |
shinyjs | 1.1 |
shinyWidgets | 0.5.0 |
shinycssloaders | 0.3 |
Author: Dr. Yu Li (📧)