-
Notifications
You must be signed in to change notification settings - Fork 0
/
boxr.qmd
96 lines (70 loc) · 4.52 KB
/
boxr.qmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
---
title: Programmatic access to Box
author: "Eric R. Scott"
---
UA accounts have 50GB of free storage on Box and it is a [UA-recommended](https://data.library.arizona.edu/data-management/best-practices/storage-back-ups-security) storage location.
We can also access Box programmatically through the `boxr` package in R to read and write files.
This is useful for automating data wrangling pipelines, for example, especially since data on Box is versioned by default.
::: callout-note
If you *only* need to access Box from R from a local computer (and don't need to be able to run things in Posit Connect or another unsupervised service), you can follow the instructions for an [interactive Box app](https://r-box.github.io/boxr/articles/boxr-app-interactive.html).
For Posit Connect or similar capabilities, read on.
:::
## Authentication
If you intend to use `boxr` as part of an automated script, use a service app to authenticate.
::: callout-note
These instructions are adapted from the `boxr` [documentation](https://r-box.github.io/boxr/articles/boxr-app-service.html) with some additional UA and Posit Connect specific tips.
:::
To authenticate to Box, you need to create an "App" at <https://app.box.com/developers/console>.
Click "Create New App" and choose a Custom App.
There are two useful options for the authentication method.
If you intend to use `boxr` as part of an automated pipeline or in a Shiny app, choose "Server Authentication (with JWT)".
You may need to wait for your app to be approved.
If for some reason this is taking longer than a few days, email [Garrett Flora](mailto:gflora@arizona.edu) to ask about this.
Once the app is approved, find the app in the [Box developer console](https://arizona.app.box.com/developers/console), click on the "Configuration" tab, and scroll to "Add and Manage Public Keys" section.
Click "Generate a Public/Private Keypair" to download a JSON token.
::: callout-important
This is where this tutorial diverges from the `boxr` documentation which has you put this file in a locked directory `~/.boxr-auth/`.
While that is probably more secure, it is not useful for apps deployed to GitHub actions or Posit Connect, as far as I know.
:::
Copy the entire contents of that file into a project-level .Renviron file like so:
``` bash
BOX_TOKEN_TEXT='<entire contents of token.json>'
```
::: callout-important
The single quotes around the file contents are important!
:::
::: callout-caution
Treat this token like a password and make sure this .Renviron file is NOT pushed to GitHub!
Put .Renviron in your .gitignore!
:::
Now restart R to load the .Renviron file and try authenticating with
``` r
box_auth_service(token_text = Sys.getenv("BOX_TOKEN_TEXT"))
```
## Working with a service app on Box
You may need to create a folder that can be accessed by the service account associated with this token by using `box_dir_create()`.
To allow your user account to see and access that directory, you need to use `box_collab_create()`, which requires a `user_id`.
You can find your `user_id` in the "General Settings" tab of the service app on the Box dev console at the very top.
I recommend inviting yourself to collaborate on a folder your service app created using `role = "co-owner"` so that you can manage access for others by just going to the folder on arizona.box.com.
More about collaborative workflows [here](https://r-box.github.io/boxr/articles/boxr-app-service.html#collaboration-workflows).
## With Posit Connect
If you deploy a Shiny app or scheduled .Rmd document on viz.datascience.arizona.edu that needs to use `boxr` to access Box, you'll need to set a `BOX_TOKEN_TEXT` secret environment variable.
Find your app or document on Posit Connect and click on the "Vars" tab of the control sidebar.
Paste the contents of the token.json file in as the value and give it the name BOX_TOKEN_TEXT.
Be sure the code you're running includes `box_auth_service(token_text = Sys.getenv("BOX_TOKEN_TEXT"))` to authorize as the service app.
::: callout-important
Unlike the .Renviron file, do NOT wrap the token text in single quotes on Posit Connect.
:::
## With GitHub Actions
Similarly to Posit Connect, you need to add BOX_TOKEN_TEXT as a github secret.
In the YAML file for your github action, you'll want to include something like the following to make that secret accessible to your R script as an environment variable:
``` yaml
jobs:
write-to-box:
runs-on: ubuntu-latest
env:
BOX_TOKEN_TEXT: ${{ secrets.BOX_TOKEN_TEXT }}
```
::: callout-note
I haven't tested `boxr` with GitHub Actions, so this is just theoretical!
:::