Deployment

Configuring the assessment database

When the riskassessment::run_app() function is ran, the code base will check if an assessment sqlite file exists by the name you give it (default is database.sqlite) and if it doesn’t, several tables will be initiated to create this database just before the app launches. Note that the user has the authority to name the database file to whatever they like using the inst/db-config.yml file. There, you can include a file path preceding the file name if you wish to move the location of the database away from the root directory. For example, the following code would create a database called “database.sqlite” in the dev/ folder:

default:
  assessment_db: ./dev/database.sqlite

At the time this vignette was authored, the database will initialize the following tables with all NULL values:

• comments: stores user comments, including user names associated with each comment entry, comment type, and timestamp
• community_usage_metrics: stores CRAN package downloads per month
• metric: stores metric info, including the riskmetric name, label, short description, type, and weight
• package_metrics: stores all package-specific rismetric metrics
• package: Contains all package information, like name, version, maintainer, etc. It also contains a the riskmetric score, the weighted score, decision, and timestamp.

Note: if any changes/ updates occur in these tables with a new release of riskassessment, you may need to delete the database file before re-running the app. Any such changes should be announced as ‘breaking changes’ in the app. If so, remember to save a copy of your current database file in another directory for backup purposes.

Database log file config

As mentioned previously, the loggit.json file is initiated to track general actions performed in the application, especially those that would reflect a change in the assessment db (database.sqlite file). At the time this vignette was authored, here’s a summary of actions logged:

• App start up
• User log-ins
• Enabling/ Disabling or changing automated decision rules
• Decisions initiated by users or the decision automation rules, including
• When pkgs are added or removed from the database, or when there are issues with this process, like when there is an absence of data to that support certain metrics
• Re-weighting pkg metrics
• Any database issues or conflicts that may arise

Each loggit “transaction” recorded contains a lot of info, but most notably, it will contain a time stamp, record type (“info”, “warn”, or “error”), and a message. For database transactions, the message will usually include the query that was executed. All log entries are always printed out in the R console for your convenience. For example:

riskassessment::run_app()
> [1] "Log file set to loggit.json"
> Listening on http://127.0.0.1:4097
> {"timestamp": "2023-03-20T11:46:23-0400", "log_lvl": "INFO", "log_msg": "User admin signed on as admin"}
> {"timestamp": "2023-03-20T11:46:33-0400", "log_lvl": "INFO", "log_msg": "The following decision rules were implemented by admin (admin): Medium = (0.33__COMMA__ 0.66]; Low = (0__COMMA__ 0.33]; High = (0.66__COMMA__ 1]."}

Feel free to use this information as you see fit! Similar to the assessment_db parameter in inst/db-config, you can name the file whatever you like, and save it in an any directory you’d like. Below, we save it in the dev/ folder and name it “loggit.json”:

default:
  assessment_db: ./dev/database.sqlite
  loggit_json: ./dev/loggit.json

Credentials configuration

Similar to the assessment database, when the riskassessment::run_app() function executes, the code base will check if an credentials sqlite file exists by the name you give it (default is credentials.sqlite) and if it doesn’t, riskassessment will initiate this new database before the app launches. Note that the user has the authority to name the database sqlite file whatever they desire using inst/db-config.yml. There, you can include a file path preceding the file name if you wish to move the location of the database away from the root directory. For example, the following code would create a database called “credentials.sqlite” in the dev/ folder:

default:
  assessment_db: ./dev/database.sqlite
  loggit_json: ./dev/loggit.json
  credential_db: ./dev/credentials.sqlite

Right after the credentials_db element is used, the credentials element (with two sub-elements: roles and privileges) must be populated. As a guide, below is a snippet of the default values for these elements, but we encourage you to design the configuration that works for you (or your organization).

credentials:
  roles:
    - admin
    - lead
    - reviewer
  privileges:
    admin: [admin, weight_adjust, auto_decision_adjust, final_decision, revert_decision, add_package, delete_package]
    lead: [weight_adjust, auto_decision_adjust, final_decision, revert_decision, add_package, delete_package]
    reviewer: add_package

Note the “User Roles and Privileges” guide is entirely dedicated to this config. For full details, please visit & read that article!

Decisions configuration

The decisions element contains up to three sub-elements: categories (mandatory), rules, and colors. Here is an example configuration we’ll walk through together:

decisions:
  categories:
      - Insignificant Risk
      - Minor Risk
      - Needs Review
      - Moderate Risk
      - Major Risk
      - Severe Risk
    rules:
      rule_1:
        metric: bugs_status
        condition: ~ metric_score(.x) <= .25
        decision: Severe Risk
      rule_2:
        metric: dependencies
        condition: ~ length(.x) >= 30
        decision: Major Risk
      rule_3:
        metric: has_vignettes
        condition: ~ .x == 0
        decision: Moderate Risk
      Severe Risk:
        - .7
        - 1
      Insignificant Risk:
        - 0
        - .1
      rule_else:
        decision: Needs Review
  colors:
    Moderate Risk: !expr grDevices::rgb(52, 235, 229, maxColorValue = 255)

Metric weights configuration

The metric_weights element contains the named list of weights. If a weight is not supplied, it will default to 1. The current list of weights that can be included are the following: has_vignettes, has_news, news_current, has_bug_reports_url, has_website, has_maintainer, has_source_control, export_help, bugs_status, license, covr_coverage, downloads_1yr. As seen above, the default configuration sets the weight for covr_coverage to 0. If you want to ignore a certain metric because it has little value to our organization, you could give it a value of zero.

When metrics are not explicitly given here, the app uses the default weight of 1 for each, unless of course there already exists a assessment database previously initialized where those metric weights were manually changed. If you wanted to toggle all current metrics, there is no harm in stating each metric and weight, so you could set up the config file to look like this, for example:

metric_weights:
  has_vignettes: 2
  has_news: 0.5
  news_current: 2
  has_bug_reports_url: 1
  has_website: 1
  has_maintainer: 1
  has_source_control: 1
  export_help: 2
  bugs_status: 5
  license: 1
  downloads_1yr.: 3
  covr_coverage: 0

{riskmetric} will use these weights to score your package according to our org’s needs!

shinyapps.io

Beware: shinyapps.io does not offer persistent storage of riskassessment’s SQLite database or logs. Thus, it is not likely a viable deployment option for your organization or group. For example, our demo application (hosted on shinyapps.io) contains a pre-prepared database of packages that can’t be permanently altered. It CAN be altered within a session, but any changes will not persist outside the session.

Posit Connect & Shiny Server

On a server, if you want to save files on disk, you’ll need to set write permissions accordingly on the folder you want to save the database, logs, and auto-decision json file.

On Posit Connect, you need to use an absolute path to specify the directory where to save the files. You can find more information here: Persistent Storage on Posit Connect.

Beyond that, it’s important to note that we strongly encourage those deploying the app to take advantage of the renv.lock file used to maintain package version dependencies. For more information on how to use renv.lock and our general dev philosophy as it pertains to package management, please read the “Using renv” article. Highly related, we encourage the use of git-backed deployment when possible. So, immediately after you update/sync your package dependencies using renv, you may want to run rsconnect::writeManifest() before deploying from a dedicated branch. For convenience, we maintain a current manifest.json that should follow the renv.lock file in our GitHub repo. So, if you’ve forked the application, you should be able to deploy the latest version of the app as-is, directly from our master branch. For more information on git-backed deployment & manifest files, please read the Posit article on git-backed content.

ShinyProxy

With ShinyProxy, you can use a Docker volume to write files outside of the application container. In application.yml, you use can something like this in the specs describing the application:

container-volumes: [ “/var/log/shinylogs:/root/logs” ]

/var/log/shinylogs is a directory on the server where you deploy your applications with ShinyProxy. /root/logs is a directory inside your Docker image.