Skip to contents

Get Started

Source: vignettes/01_get-started.Rmd
01_get-started.Rmd

Overview

This repository contains server and client codes for a Water Accounting+ visualization dashboard. All codes and assets are provided as a standard R package. The dashboard application itself is written in R and uses the open-source R/Shiny framework.

The dashboard uses output from IWMI WA+ hydrological models, with the main code routine documented at WAPORWA (WaPOR-based Water Accounting).

Two hydrological basin are provided in the initial release, the lower Niger River in Mali and Mara River in Kenya. There are differences between the two use cases, in terms of data availability and temporal scope (e.g. in Mali only a subset of the entire WAPORWA model was obtained), meaning the level of details available through the dashboard will vary according to each river basin.

Usage

The easiest to get started is to install this package from the development version on GitHub at an R console:

if (!require("remotes")) install.packages("remotes")
remotes::install_github("mbacou/WADashboard")

And then preview the dashboard in your browser with:

if (!require("shiny")) install.packages("shiny")
shiny::shinyAppDir(system.file("app", package="WADashboard"))

If you choose to clone this repo instead, the application can be previewed at an R console with:

shiny::runApp()

Repository Structure

The repo is structured as a standard R package, in particular:

  • /data-raw: configuration files
  • /inst: client and server scripts and web assets for the Shiny application
  • /R: all custom R functions (see Reference)
  • /docs: rendered HTML documentation (this website)

The application can be previewed in a browser with source("app.R").

Shell scripts are provided to automate common tasks:

  • ./build.sh: rebuild and install the package
  • ./pkgdown.sh: rebuild HTML package documentation (uses pkgdown framework)
  • ./deploy.sh <tag>: commit tagged release to Github, rebuild Docker image, and deploy image to AWS ECR (you need AWS cli and a valid AWS access key to deploy to AWS cloud at the command line)

Configuration

  1. (optional) Edit local environment variables in file .Renviron as needed:
    • WA_DATA pointing to the root location of your WA+ model output (collection of CSV and NetCDF files). Any local or cloud-based storage type may be implemented (incl. Amazon S3).
    • WA_ROOT pointing to Shiny server root location (default to /srv/shiny-server/WADashboard but you might want to deploy to a different location).
    • WA_LIB pointing to the location of a local R library (default to Linux shared library /usr/local/lib/R/site-library)
  2. Edit 2 configuration files:
  3. Whenever you change the configuration files, you will need to rebuild the R package and reinstall by executing ./build.sh.

If you append a new river basin, make sure you can successfully ETL its data with datat_etl("new_basin_code") before rebuilding the package (else it will fail to build explicitly).

Application Deployment

A Docker image file is provided for deployment to AWS ECS (Fargate). This image includes Shiny Server Community Edition and (for development only) RStudio Server Preview.

You can build and test this image locally with:

# replace {pwd} with a chosen password for the default rstudio user
docker build -t wadashboard .
docker run --name wadashboard PASSWORD={pwd} -p 80:3838 -p 8787:8787 wadashboard

Once you’ve established that this container runs locally, it can be deployed to AWS ECS (see ./deploy.sh for an automated deployment script):

# Authenticate your local Docker client
aws ecr get-login-password --region {region} | docker login --username AWS --password-stdin {aws_account_id}.dkr.ecr.{region}.amazonaws.com
# Tag your image with your Amazon ECR registry
docker tag wadashboard {aws_account_id}.dkr.ecr.{region}.amazonaws.com/wadashboard
# Push the image to your AWS ECR registry
docker push {aws_account_id}.dkr.ecr.{region}.amazonaws.com/wadashboard

The dashboard application is served on the host at http://localhost/WADashboard/. RStudio IDE is reachable at http://localhost:8787/ (replace localhost with your container’s public IP or domain name).