---
title: "Using config with Posit Connect"
output:
  rmarkdown::html_vignette:
    css:
    - !expr system.file("rmarkdown/templates/html_vignette/resources/vignette.css", package = "rmarkdown")
    - ../man/fragments/codeblock.css
vignette: >
  %\VignetteIndexEntry{Using config with Posit Connect}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

```{r child="../man/fragments/knitr_with_config_hooks.Rmd", include = FALSE}
```

The purpose of the `config` package is to respond to environment variables that could be set to different values on different machines. Specifically, config reacts to the value of `R_CONFIG_ACTIVE`, and this allows you to set configurations for different machines, e.g. in dev or production.

If you deploy your code to a Posit Connect instance, then you can use the fact that Connect sets the value of `R_CONFIG_ACTIVE` to `rsconnect`.

This means you can create a configuration file using the value `rsconnect`, for example:


```{yaml}
default:
  trials: 5
  dataset: "data-sampled.csv"
  
rsconnect:
  trials: 30
  dataset: "data.csv"
```

Note: this value can be configured by your system administrator, so check your own system configuration!  See <https://docs.posit.co/connect/admin/appendix/configuration/#R.ConfigActive> for detail.

## Using config for staging and prod on multiple servers

Many customers of Posit Connect will have separate Connect instances for the purposes of separating staging and production.

In this case, the system administrator needs to configure the `R_CONFIG_ACTIVE` environment variable to have different values on each machine. For example:

- On the staging server: `rsconnect-staging`
- On the production server: `rsconnect-prod`

Using these example values, you could configure the `config.yml` file to look like this:


```{yaml output.var="config_yaml"}
default:
  trials: 5
  dataset: "data-sampled.csv"

rsconnect:
  trials: 30
  
rsconnect-staging:
  inherits: rsconnect
  dataset: "data-staging.csv"
  
rsconnect-prod:
  inherits: rsconnect
  dataset: "data.csv"
```

Note that this configuration uses the inheritance of `config` yaml files, by having a common configuration for `rsconnect` and staging and prod configurations that inherit from the `rsconnect` configuration.




## Using config for staging and prod on a single server

You may have the use case that you use the same Connect instance to host two instances of your app, for staging (test) and production.

In this use case you will soon run into the problem that an individual user can not change the the environment variable `R_CONFIG_ACTIVE`, since this is configured system-wide by the administrator.

But you can still use `config` to set different values for staging and prod, by changing the environment variable that `config::get()` looks at.


Specifically, you must specify a different `config` argument to `config::get()`.  For example, you can create a new environment variable for your Connect app, called `R_CONFIG_ACTIVE_APP`, and then use `config::get()` like this:

```{r, with_config=TRUE, config_yml="config_yaml"}
config::get("trials", config = Sys.getenv("R_CONFIG_ACTIVE_APP"))
```

Again, this example utilizes the inheritance of `config` yaml files, by having a common configuration for `rsconnect` and staging and prod configurations that inherit from the `rsconnect` configuration.

In such a case, you may have a `config.yml` file like this:



```{yaml output.var="config_yaml"}
default:
  trials: 5
  dataset: "data-sampled.csv"

rsconnect:
  trials: 30
  
staging:
  inherits: rsconnect
  dataset: "data-staging.csv"
  
prod:
  inherits: rsconnect
  dataset: "data.csv"
```


If you configure the environment variable correctly, you should get the appropriate `dataset` values for staging (`data-staging.csv`) and prod (`data.csv`):

```{r, with_config=TRUE, config_yml="config_yaml"}
config::get("dataset", config = "staging")
config::get("dataset", config = "prod")
```

## A utility function that might be helpful

If you are in the situation where you wish to use a different environment variable, you can potentially save a few keystrokes by defining a utility function that wraps around `config::get()`.  Such a utility simply passes a different value for the `config` argument, like this:

```r
cfg_get_app <- function (
  value = NULL, 
  config = Sys.getenv("R_CONFIG_ACTIVE_APP", "default"), 
  ...
) {
  config::get(value = value, config = config, ...)
}
```

You can then call this function from your app:

``` R
cfg_get_app("value")
```
