-
Notifications
You must be signed in to change notification settings - Fork 112
/
13-deploy.Rmd
156 lines (98 loc) · 10.8 KB
/
13-deploy.Rmd
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
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
# (PART) Step 5: Deploy {.unnumbered}
# Deploy Your Application {#deploy}
> Your deploys should be as boring, straightforward, and stress-free as possible.
>
> _How to Deploy Software - Zach Holman_ (<https://zachholman.com/posts/deploying-software>)
Once your app is built, you are ready to deploy it!
In other words, your software is now ready to be used by other users.
There are two main ways to share your application and make it available to others: by creating a package and making it installable, or by sending it to a remote server.
We will see in this part how you can do that using `{golem}` [@R-golem].
## Before deployment checklist
Here is a quick checklist of things to think about once your application is ready, and before sending it to production:
- [ ] `devtools::check()`, run from the command line, returns 0 errors, 0 warnings, and 0 notes.
- [ ] The current version number is valid, i.e. if the current app is an update, the version number has been bumped.
- [ ] Everything is fully documented.
- [ ] Test coverage is good, i.e. you cover a sufficient amount of the codebase, and these tests cover the core/strategic algorithms
- [ ] Everyone in the project knows the person to call if something goes wrong.
- [ ] The following things are clear to everyone involved in the project: the debugging process, how to communicate bugs to the developer team, and how long it will take to get changes implemented.
- [ ] (If relevant) The server it is deployed on has all the necessary software installed (Docker, Connect, `Shiny Server`, etc.) to make the application run.
- [ ] The server has all the system requirements needed (i.e. the system libraries), and if not, they are installed with the application (if it's dockerized).
- [ ] The application, if deployed on a server, will be deployed on a port which will be accessible by the users.
- [ ] (If relevant) The environment variables from the production server are managed inside the application.
- [ ] (If relevant) The app is launched on the correct port, or at least this port can be configured via an environment variable.
- [ ] (If relevant) The server where the app is deployed has access to the data sources (database, API, etc.).
- [ ] If the app records data, there are backups for these data.
## Sharing your app as a package
### Install on your machine
A `{shiny}` application built with `{golem}` [@R-golem] is **by definition** an R package.
This `{shiny}` app as a package is also helpful when it comes to deploying your application: packages are designed to be shareable pieces of R code.
Before sending it to a remote server or sharing it with the world, **the first step is testing if the package can be installed on your own computer**.
To do that, when you are in the project corresponding to the golem you built, you can call `remotes::install_local()` to install the application on your computer.
Of course, if you are somewhere else on your machine, you can call `remotes::install_local("path/to/app")`.
If you are using the RStudio IDE, you can also click on the `Build` tab, then click on the `Install and Restart` button.
This should restart your R session, and call `library(yourpackagename)`.
Then, try the `run_app()` function to check that the app can be launched.
### Share as a built package
#### A. Local build {.unnumbered}
Building an app as a package also means that this app can be bundled into an archive, and then shared, either as is or using a package repository like the CRAN.
To do that, you first need an bundled version of your app, which can be created using the `build()` function from `{pkgbuild}` [@R-pkgbuild] in the same working directory as your application.
Calling this function will create a .tar.gz file that is called `mygolem_0.0.1.tar.gz` (of course with the name of your package).
Once you have this `tar.gz`, you can send it to your favorite package repository.
You can also share the file as is with others.
If you do so, they will have to install the app with `remotes::install_local("path/to/tar.gz")`, that will take care of doing a full installation of the app, including installing the required dependencies.
Then, they can do `library(yourpackagename)` and `run_app()` on their machine.
#### B. Send to a package repository {.unnumbered}
The upside of building the application `{golem}`, i.e. as a package, is that you can share your application on a remote package manager, the more widely used, for example, on the CRAN like `{dccvalidator}` [@R-dccvalidator], or on BioConductor like `{spatialLIBD}` [@R-spatialLIBD].
But any other package manager will work: for example, if the company uses RStudio Package Manager, your application can be installed here in the same way as any other package.
If your application is open source, the package structure also allows you to install from GitHub, by using the `remotes::install_github()` function.[^deploy-with-golem-1]
For example, this is what you can do with `{hexmake}` or `{tidytuesday}`: as they are open-source packages, they can be installed from GitHub.
Then, once your application is installed as a package on the users' machines, they can do `library(yourpackagename)` and `run_app()`.
[^deploy-with-golem-1]: This is also true for other version control systems.
The advantage of this solution is that R users are familiar with package installation, so it makes using your application easier for them.
Also, and we will see it in the next section, making your application available as a standard R package makes it easier to deploy it: for example, if your RStudio Connect is coupled with your RStudio Package Manager, the deployment file just has to contain one line launching the application.
Note that releasing to CRAN or BioConductor requires extra effort: you have to comply with a series of rules.
But good news: as you have been following the best practices from this book, you should not have to put in that much extra effort!
Know more about releasing on CRAN:
- [Checklist for CRAN submissions](https://cran.r-project.org/web/packages/submission_checklist.html)
- [CRAN Repository Policy](https://cran.r-project.org/web/packages/policies.html)
- [R packages - Chapter 18, Releasing a package](https://r-pkgs.org/release.html)
- [Getting your R package on CRAN](https://kbroman.org/pkg_primer/pages/cran.html)
- [prepare-for-cran - A collaborative list of things to know before submitting to CRAN](https://github.com/ThinkR-open/prepare-for-cran)
## Deploying apps with `{golem}`
The other way to make your application available to others is by sending it to a remote server that can serve `{shiny}` applications.
In other words, instead of having to install the application on their machines, **they can crack open a web browser and navigate to the URL where the application is deployed**.
Deploying to a server is the solution of choice when you want to make your application available to a wide public: on a server, visitors do not have to have R installed on their computer, they do not have to install a package or launch it; they can just browse the application like any other web application.
This solution is also a common choice in companies that have strict security requirements: the IT team might not be willing to let everyone install software on their machine, and sharing an application on a server allows them more control over who can access the application.
For example, deploying on a server allows you to use a proxy, and to filter by IP: then, only a subset of people can have access to the application.
When using `{golem}`, you can open the `dev/03_deploy.R` and find the functions for server deployment.
At the time of writing this book, there are two main ways to deploy a shiny app on a server:
- RStudio's solutions
- A Docker-based solution
### RStudio environments
RStudio proposes three services to deploy `{shiny}` application:
- `shinyapps.io`, an on-premises solution, can serve `{shiny}` application (freemium).
- `Shiny Server` is a software you have to install on your own server, and can be used to deploy multiple applications (you can find either an open source or a professional edition).
- `RStudio Connect` is a server-based solution that can deploy `{shiny}` applications and `Markdown` documents (and other kinds of content), and serves them as ordinary websites.
Each of these platforms has its own function to create an `app.R` file that is to be used as a launch script of each platform.
- `golem::add_rstudioconnect_file()`
- `golem::add_shinyappsio_file()`
- `golem::add_shinyserver_file()`
These `app.R` files call a `pkgload::load_all()` function, that will mimic the launch of your package, and then call the `run_app()` function from your packaged app.
Note that if you need to configure the way your app is launched on these platforms (for example, if you need to pass arguments to the `run_app()` function), you will have to edit this file.
Note that when using these functions, you will be able to use the "One click deploy" for these platforms: on the top right of these `app.R`, use the Blue Button to deploy to a server.
Another way to deploy your `{golem}`-based app to `{shiny}` server and to Connect is to link these two software to a local repository (for example, an RStudio Package Manager), and then to only use `mypackage::run_app()` to the `app.R`.
### Docker
Docker is an open source software used to build and deploy applications in containers.
Docker has become a core solution in the DevOps world and a lot of server solutions are based on it.
See Part 5, "Strengthen", for a more complete introduction to Docker.
You will find the function for creating a `Dockerfile` for your `{golem}` app inside the `03_deploy.R` file, which contains a series of 3 functions:
- `golem::add_dockerfile()`
- `golem::add_dockerfile_shinyproxy()`
- `golem::add_dockerfile_heroku()`
The first function creates a "generic" `Dockerfile`, in the sense that it is not specific to any platform, and would work out of the box for your local machine.
The second one is meant for [`{shiny}`Proxy](https://www.shinyproxy.io/), an open source solution for deploying containerized `{shiny}` applications, and the third is for [Heroku](https://www.heroku.com/), an online service that can serve containerized applications (not specific to `{shiny}`).
Other platforms can run Docker containers, notably AWS and Google Cloud Engine.
At the time of writing these lines, `{golem}` does not provide support for these environments, but that is on the to-do list!
Note that the `Dockerfile` creation in `{golem}` tries to replicate your local environment as precisely as possible, notably by matching your R version, and the version of the packages you have installed on your machine.
System requirements are also added when they are found on [the sysreqs service from r-hub](https://sysreqs.r-hub.io/).
Otherwise you might have to add them manually.