Skip to contents

Deploying shinyplanr

Source: vignettes/ad-deployment.qmd

This chapter explains how to deploy shinyplanr for a new region using the Deployment Project model introduced in shinyplanr v2.0. The key design principle is that deployers never need to fork or modify the shinyplanr package source — they create a small, self-contained R project that holds only their region-specific data and configuration.

Note

This chapter is for deployers — practitioners who want to run shinyplanr for a new region. If you are looking for user instructions (how to use a running app), see the Using shinyplanr vignette. If you are setting up data for the first time, see the Setting Up vignette.

Overview

The deployment workflow has three phases:

Phase Where What happens
1. Setup Your computer Create deployment project, prepare data, generate config
2. Test Your computer Run the app locally in RStudio or VSCode
3. Deploy Posit Connect Push the app to Posit Connect Cloud

The deployment project you create is a separate R project — not a fork of shinyplanr. It contains:

MyRegion/                        ← Your deployment project root
├── app.R                        ← Entry point (auto-generated, do not edit)
├── deploy.R                     ← Deployment script (auto-generated)
├── MyRegion.Rproj               ← RStudio project file
├── config/
│   └── shinyplanr_config.rds    ← Generated by setup-app.R
├── www/
│   ├── logo.png                 ← Your region logo
│   ├── logo_funder.png          ← Your funder logo
│   └── uq-logo-white.png        ← UQ logo (optional)
├── data-raw/
│   └── MyRegion/
│       ├── setup-data.R         ← Spatial data preparation
│       ├── setup-app.R          ← App configuration
│       ├── Dict_Feature.csv     ← Feature dictionary
│       ├── data/                ← Your raw spatial data files
│       ├── logos/               ← Your logo files
│       └── markdown/            ← Your help text (markdown)
├── renv.lock                    ← Package version lock (if using renv)
└── .Rprofile                    ← renv activation (if using renv)

Step 1: Create the Deployment Project

From within an R session (not necessarily inside the shinyplanr package), call create_shinyplanr_template():

library(shinyplanr)

create_shinyplanr_template(
  country    = "MyRegion",
  crs        = "+proj=cea +lon_0=160 +lat_ts=-20 +datum=WGS84 +units=m +no_defs",
  oceandatr  = TRUE,
  output_dir = "../MyRegion"   # creates a sibling directory
)

This will:

  • Create the full directory structure shown above
  • Generate setup-data.R, setup-app.R, and Dict_Feature.csv as starting-point templates
  • Copy markdown help-text templates from the package
  • Generate app.R, deploy.R, and MyRegion.Rproj
  • Initialise renv (bare mode) if use_renv = TRUE (the default)

Key parameters

Parameter Default Notes
country (required) Used for folder names, titles, and file names
crs "ESRI:54009" Use an equal-area projection for your region — see Projection Wizard
oceandatr TRUE Include automatic data download from the oceandatr package
resolution 20000 Planning unit size in metres
include_climate TRUE Include climate-smart planning scaffolding
include_cost TRUE Include cost layer setup
include_mpas TRUE Include MPA locked-in area setup
output_dir "../country" Where to create the project (default: sibling of working dir)
use_renv TRUE Initialise renv for reproducible deployment
create_rproj TRUE Create an RStudio .Rproj file

Step 2: Open the Deployment Project

Open the newly created project in RStudio or VSCode:

code ../MyRegion

Important

All subsequent steps should be run from inside the deployment project, not from the shinyplanr package directory.

Step 3: Prepare Spatial Data

Edit and run data-raw/MyRegion/setup-data.R. This script:

  1. Downloads or loads your spatial data
  2. Creates a hexagonal planning unit grid
  3. Calculates feature values for each planning unit
  4. Saves everything to data-raw/MyRegion/MyRegion_RawData.rda

The script is pre-populated with code appropriate for your oceandatr setting. At minimum, you will need to:

  • Confirm the country name matches the Marine Regions database (for oceandatr = TRUE), or load your own boundary file
  • Adjust the resolution if needed
  • Add any region-specific features not covered by oceandatr
# Run from inside the deployment project:
source("data-raw/MyRegion/setup-data.R")

Step 4: Configure the App

Edit and run setup/setup-app.R. This script:

  1. Defines all app options (titles, colours, module switches, CRS)
  2. Copies logo files from setup/logos/ to www/
  3. Loads the spatial data and feature dictionary
  4. Reads content files from setup/content/
  5. Saves everything to config/shinyplanr_config.rds

Key sections to customise in setup/setup-app.R:

App options 

setup_dir <- "setup"
data_path <- file.path(setup_dir, "data")

options <- list(
  app_title  = "MyRegion: shinyplanr",
  nav_title  = "MyRegion Spatial Planning",
  funder_url = "https://my-funder.org",

  # Logo files (relative to setup/logos/)
  file_logo        = file.path(setup_dir, "logos", "logo.png"),
  file_logo_funder = file.path(setup_dir, "logos", "logo_funder.png"),

  # Show or hide the UQ logo in the welcome footer
  show_uq_logo = TRUE,   # Set FALSE to hide the UQ logo

  # Module switches
  mod_1welcome  = TRUE,
  mod_2scenario = TRUE,
  mod_3compare  = TRUE,
  mod_4features = TRUE,
  mod_5coverage = TRUE,
  mod_6help     = TRUE,

  # Planning settings
  obj_func = "min_shortfall",  # or "min_set"
  cCRS     = "EPSG:32757"
)

Logos

Replace the placeholder files in setup/logos/ with your own:

File Purpose
logo.png Primary logo (shown in navbar)
logo2.png Secondary logo (shown in navbar)
logo3.png Tertiary logo (shown in navbar)
logo_funder.png Funder logo (shown in welcome footer)

Content files

Edit the files in setup/content/ to customise the text shown in each panel of the app. The templates contain placeholder text with instructions. You can also add PDFs, images, or other reference material to this folder.

File Where it appears
shinyplanr_1welcome1.md – 5.md Welcome page tabs
shinyplanr_1footer.md Welcome page footer
shinyplanr_2solution.md Solution panel help
shinyplanr_2targets.md Targets panel help
shinyplanr_2cost.md Cost panel help
shinyplanr_2climate.md Climate panel help
shinyplanr_2ecosystemServices.md ESS panel help
shinyplanr_6faq.md FAQ tab
shinyplanr_6technical.md Technical notes tab
shinyplanr_6changelog.md Changelog tab

Feature dictionary

Edit setup/Dict_Feature.csv to define which features appear in the app, their display names, target ranges, and justification text. Key columns:

Column Description
nameCommon Display name shown in the app
nameVariable Exact column name in dat_sf
category Feature group (used for grouping sliders)
categoryID Short category code
type "Feature", "Cost", or "LockIn"
targetInitial Default conservation target (%)
targetMin / targetMax Slider range
includeApp TRUE to include in the app

After editing, run:

source("setup/setup-app.R")

Step 5: Test Locally

Run the app locally to check everything looks correct:

shiny::runApp()

This reads app.R in the project root, which calls:

shinyplanr::load_config("config/shinyplanr_config.rds")
shinyplanr::run_app()

The app should open in your browser. Check that:

  • All features appear in the feature list
  • Logos display correctly
  • Help text renders properly
  • The optimisation runs without errors (click Run Analysis)

Tip

If you see errors about missing objects, check that setup-app.R completed without errors and that config/shinyplanr_config.rds exists and is not empty.

Step 6: Lock Package Versions with renv

Before deploying, lock the exact versions of all packages used (including shinyplanr) to ensure the deployed app is identical to your local test:

renv::snapshot()

This writes renv.lock. Commit this file to version control if you are using git.

Important

Why this matters: When you deploy to Posit Connect, it installs packages fresh from GitHub. Without renv.lock, it could install a newer version of shinyplanr that is incompatible with your config file. The lock file pins the exact GitHub commit SHA used during local testing.

Upgrading shinyplanr

When a new version of shinyplanr is released and you want to upgrade:

renv::update("shinyplanr")    # Install new version
source("setup/setup-app.R")  # Regenerate config
shiny::runApp()               # Test locally
renv::snapshot()              # Update lock file
source("deploy.R")            # Deploy

If the new version has an incompatible config schema, load_config() will print a clear error message explaining what changed.

Step 7: Set Up Posit Connect

You only need to do this once per Posit Connect account:

  1. Go to Posit Connect Cloud and sign in (or create an account)
  2. Create an API key: Account → API Keys → New API Key
  3. In R, run:
rsconnect::setAccountInfo(
  name   = "your-account-name",
  token  = "your-token",
  secret = "your-secret"
)

Step 8: Deploy to Posit Connect

Run the deployment script:

source("deploy.R")

This calls rsconnect::deployApp() with a curated list of files:

  • app.R and deploy.R
  • The entire config/ directory (containing shinyplanr_config.rds)
  • The entire www/ directory (containing your logos)
  • renv.lock, .Rprofile, and the renv/ directory (if present)

Data files are not uploaded — the spatial data is embedded inside shinyplanr_config.rds which is already uploaded via config/.

Note

The first deployment will take a few minutes as Posit Connect installs all required packages. Subsequent deployments are faster.

After deployment, Posit Connect will provide a URL for your app. Share this with your stakeholders.

Version Compatibility

shinyplanr uses a config schema version (separate from the package version) to detect incompatible config files. The schema version only increments when the structure of the config changes (keys added, removed, or renamed).

If you try to run an app with a mismatched config, load_config() will stop with a clear error:

Error: Config schema version mismatch.
  Config file schema version : 1
  Package schema version     : 2
  Config path: config/shinyplanr_config.rds
Re-run setup/setup-app.R to regenerate the config with the current schema.

The fix is always the same: re-run setup/setup-app.R to regenerate the config, then re-deploy.

Troubleshooting

App fails to start on Posit Connect

Check that:

  • config/shinyplanr_config.rds was included in the deployment (check deploy.R)
  • renv.lock is included and matches your local environment
  • The shinyplanr package version installed by Posit Connect matches your local version

“Config schema version mismatch” error

Re-run setup/setup-app.R in your deployment project to regenerate the config for the current package version.

Missing logos

Ensure setup/setup-app.R ran successfully (logo copy step). Check that logo files exist in setup/logos/ and that www/ was populated.

Local app works but deployed app fails

This almost always means a package version mismatch between local and Posit Connect. Run renv::snapshot() locally and re-deploy.

“value for ‘Dict’ not found” or similar

load_config() was not called, or failed silently. Check that app.R in the project root calls shinyplanr::load_config("config/shinyplanr_config.rds") before shinyplanr::run_app().