Package 'plumberDeploy'

Add HTTPS to a plumber Droplet

Description

Adds TLS/SSL (HTTPS) to a droplet created using do_provision().

Usage

do_configure_https(
  droplet,
  domain,
  email,
  termsOfService = FALSE,
  force = FALSE,
  ...
)

Arguments

droplet	The droplet on which to act. See analogsea::droplet().
domain	The domain name associated with this instance. Used to obtain a TLS/SSL certificate.
email	Your email address; given only to letsencrypt when requesting a certificate to enable them to contact you about issues with renewal or security.
termsOfService	Set to TRUE to agree to the letsencrypt subscriber agreement. At the time of writing, the current version is available here. Must be set to true to obtain a certificate through letsencrypt.
force	If FALSE, will abort if it believes that the given domain name is not yet pointing at the appropriate IP address for this droplet. If TRUE, will ignore this check and attempt to proceed regardless.
...	additional arguments to pass to analogsea::droplet_ssh()

Details

In order to get a TLS/SSL certificate, you need to point a domain name to the IP address associated with your droplet. If you don't already have a domain name, you can register one here. Point a (sub)domain to the IP address associated with your plumber droplet before calling this function. These changes may take a few minutes or hours to propagate around the Internet, but once complete you can then execute this function with the given domain to be granted a TLS/SSL certificate for that domain.

Obtains a free TLS/SSL certificate from letsencrypt and installs it in nginx. It also configures nginx to route all unencrypted HTTP traffic (port 80) to HTTPS. Your TLS certificate will be automatically renewed and deployed. It also opens port 443 in the firewall to allow incoming HTTPS traffic.

Historically, HTTPS certificates required payment in advance. If you appreciate this service, consider donating to the letsencrypt project.

Value

The DigitalOcean droplet

---

Deploy or Update an API

Description

Deploys an API from your local machine to make it available on the remote plumber server.

Usage

do_deploy_api(
  droplet,
  path,
  localPath,
  port,
  forward = FALSE,
  docs = FALSE,
  preflight,
  overwrite = FALSE,
  ...
)

Arguments

droplet	The droplet on which to act. It's expected that this droplet was provisioned using do_provision(). See analogsea::droplet() to obtain a reference to a running droplet.
path	The remote path/name of the application
localPath	The local path to the API that you want to deploy. The entire directory referenced will be deployed, and the plumber.R file inside of that directory will be used as the root plumber file. The directory MUST contain a plumber.R file.
port	The internal port on which this service should run. This will not be user visible, but must be unique and point to a port that is available on your server. If unsure, try a number around 8000.
forward	If TRUE, will setup requests targeting the root URL on the server to point to this application. See the do_forward() function for more details.
docs	If TRUE, will enable the documentation interface for the remotely deployed API. By default, the interface is disabled.
preflight	R commands to run after plumb()ing the plumber.R file, but before run()ing the plumber service. This is an opportunity to e.g. add new filters. If you need to specify multiple commands, they should be semi-colon-delimited.
overwrite	if an application is already running for this path name, and overwrite = TRUE, then do_remove_api will be run.
...	additional arguments to pass to analogsea::droplet_ssh() or analogsea::droplet_upload(), such as keyfile. Cannot contain remote, local as named arguments.

Value

The DigitalOcean droplet, but called for side effects

---

Forward Root Requests to an API

Description

Forward Root Requests to an API

Usage

do_forward(droplet, path, ...)

Arguments

droplet	The droplet on which to act. It's expected that this droplet was provisioned using do_provision().
path	The path to which root requests should be forwarded
...	additional arguments to pass to analogsea::droplet_upload()

Value

The DigitalOcean droplet

---

Provision a DigitalOcean plumber server

Description

Create (if required), install the necessary prerequisites, and deploy a sample plumber application on a DigitalOcean virtual machine. You may sign up for a Digital Ocean account here. You should configure an account ssh key with analogsea::key_create() prior to using this method. This command is idempotent, so feel free to run it on a single server multiple times.

Usage

do_provision(droplet, unstable = FALSE, example = TRUE, ...)

do_install_plumber(droplet, unstable, ...)

do_ip(droplet, path)

Arguments

droplet	The DigitalOcean droplet that you want to provision (see analogsea::droplet()).
unstable	If FALSE, will install plumber from CRAN. If TRUE, will install the unstable version of plumber from GitHub.
example	If TRUE, will deploy an example API named hello to the server on port 8000.
...	Arguments passed into the analogsea::droplet_create() function.
path	path to attach to the IP address before browsing. Should likely start with a / or : (as in ⁠:8080⁠), otherwise / will be added.

Details

Provisions a Ubuntu 20.04-x64 droplet with the following customizations:

• A recent version of R installed

• plumber installed globally in the system library

• An example plumber API deployed at ⁠/var/plumber⁠

• A systemd definition for the above plumber API which will ensure that the plumber API is started on machine boot and respawned if the R process ever crashes. On the server you can use commands like ⁠systemctl restart plumber⁠ to manage your API, or ⁠journalctl -u plumber⁠ to see the logs associated with your plumber process.

• The 'nginx“ web server installed to route web traffic from port 80 (HTTP) to your plumber process.

• ufw installed as a firewall to restrict access on the server. By default it only allows incoming traffic on port 22 (SSH) and port 80 (HTTP).

• A 4GB swap file is created to ensure that machines with little RAM (the default) are able to get through the necessary R package compilations.

Value

The DigitalOcean droplet

The URL to be browsed

Note

Please see https://github.com/sckott/analogsea/issues/205 in case of an error by default do_provision and an error of "Error: Size is not available in this region.".

Examples

## Not run: 
  auth = try(analogsea::do_oauth())
  if (!inherits(auth, "try-error") &&
      inherits(auth, "request")) {
    analogsea::droplets()
    droplet = do_provision(region = "sfo3", example = FALSE)
    analogsea::droplets()
    analogsea::install_r_package(droplet, c("readr", "remotes"))
    do_deploy_api(droplet, "hello",
                  system.file("plumber", "10-welcome", package = "plumber"),
                  port=8000, forward=TRUE)
    if (interactive()) {
        utils::browseURL(do_ip(droplet, "/hello"))
    }
    analogsea::droplet_delete(droplet)
  }

## End(Not run)

---

Remove an API from the server

Description

Removes all services and routing rules associated with a particular service. Optionally purges the associated API directory from disk.

Usage

do_remove_api(droplet, path, delete = FALSE, ...)

Arguments

droplet	The droplet on which to act. It's expected that this droplet was provisioned using do_provision(). See analogsea::droplet() to obtain a reference to a running droplet.
path	The path/name of the plumber service
delete	If TRUE, will also delete the associated directory (⁠/var/plumber/whatever⁠) from the server.
...	additional arguments to pass to analogsea::droplet_ssh() or analogsea::droplet_upload(), such as keyfile. Cannot contain remote, local as named arguments.

Value

The DigitalOcean droplet, but called for side effects

---

Remove the forwarding rule

Description

Removes the forwarding rule from the root path on the server. The server will no longer forward requests for / to an application.

Usage

do_remove_forward(droplet, ...)

Arguments

droplet	The droplet on which to act. It's expected that this droplet was provisioned using do_provision(). See analogsea::droplet() to obtain a reference to a running droplet.
...	additional arguments to pass to analogsea::droplet_ssh()

Value

The DigitalOcean droplet, but called for side effects

---