Read the R Templates blog post and watch this useR!2021 video for a quick intro!
The /template
folder contains the following OpenFaaS templates:
Template | Base image | Watchdog | Server framework |
---|---|---|---|
rstats-base | rocker/r-base | classic | None (STDIO) |
rstats-ubuntu | rocker/r-ubuntu | classic | None (STDIO) |
rstats-minimal | rhub/r-minimal | classic | None (STDIO) |
rstats-base-plumber | rocker/r-base | of-watchdog | plumber |
rstats-ubuntu-plumber | rocker/r-ubuntu | of-watchdog | plumber |
rstats-minimal-plumber | rhub/r-minimal | of-watchdog | plumber |
rstats-base-httpuv | rocker/r-base | of-watchdog | httpuv |
rstats-ubuntu-httpuv | rocker/r-ubuntu | of-watchdog | httpuv |
rstats-minimal-httpuv | rhub/r-minimal | of-watchdog | httpuv |
rstats-base-beakr | rocker/r-base | of-watchdog | beakr |
rstats-ubuntu-beakr | rocker/r-ubuntu | of-watchdog | beakr |
rstats-minimal-beakr | rhub/r-minimal | of-watchdog | beakr |
rstats-base-fiery | rocker/r-base | of-watchdog | fiery |
rstats-ubuntu-fiery | rocker/r-ubuntu | of-watchdog | fiery |
rstats-minimal-fiery | rhub/r-minimal | of-watchdog | fiery |
rstats-base-ambiorix | rocker/r-base | of-watchdog | ambiorix |
rstats-ubuntu-ambiorix | rocker/r-ubuntu | of-watchdog | ambiorix |
rstats-minimal-ambiorix | rhub/r-minimal | of-watchdog | ambiorix |
The templates differ with respect to:
rocker/r-base
Docker image from the rocker project for bleeding edge,rocker/r-ubuntu
Docker image from the rocker project for long term support (uses RSPM binaries),rhub/r-minimal
Docker image from the r-hub project for smallest image sizes.See the Rocker and the Rockerverse papers in the R Journal about the current state of the art regarding the use of container technology in R.
The of-watchdog http mode loads the handler as a small background web server. The classic watchdog's forking mode would instead load this file for every invocation creating additional latency when loading packages, saved data, or trained models.
Frameworks are listed in the order of their dependence relationships:
More server frameworks are being explored, such as the Rserve based RestRserve, or the httpuv based opencpu. See ROADMAP for details. PRs are welcome!
It is recommended to read the OpenFaaS docs first and set up a local or remote Kubernetes cluster or faasd with OpenFaaS deployed. To get going quickly, follow the official OpenFaaS workshop, or enroll into the free Introduction to Serverless on Kubernetes course.
If you are looking for the smallest footprint (single node), the book Serverless For Everyone Else by Alex Ellis is highly recommended.
See recommended setup steps for the R template examples.
Use the faas-cli
and pull R templates:
faas-cli template pull https://github.com/analythium/openfaas-rstats-templates
Now faas-cli new --list
should give you a list with the available rstats-*
templates.
Create a new function called hello-rstats
:
export OPENFAAS_PREFIX="" # Populate with your Docker Hub username
faas-cli new --lang rstats-base hello-rstats --prefix=$OPENFAAS_PREFIX
the OPENFAAS_PREFIX
means a user or organization on e.g. Docker Hub where
you have push privileges; don't forget to log in to your registry using docker login
.
Your folder now should contain the following:
hello-rstats/handler.R
hello-rstats/DESCRIPTION
hello-rstats.yml
The hello-rstats/handler.R
file does the heavy lifting by executing the desired
functionality. hello-rstats/DESCRIPTION
lists the dependencies for the handler.
The hello-rstats.yml
is the stack file used to configure functions
(read more here).
You can build, push, and deploy the hello-rstats
function using:
faas-cli up -f hello-rstats.yml
faas-cli up
is a shorthand
for automating faas-cli build
, faas-cli push
, and faas-cli deploy
.
Once the function is deployed, you can test it in the UI
(e.g. at OPENFAAS_URL/ui/
) or using curl:
curl $OPENFAAS_URL/function/hello-rstats -d '["World"]'
Both should give the JSON output "Hello World!"
.
You can now edit hello-rstats/handler.R
to your liking.
Don't forget to add dependencies to the hello-rstats/DESCRIPTION
file.
See worked examples for different use cases.
Read more about the structure of the templates if advanced tuning is required, e.g. by editing the Dockerfile
, etc.
The template installs dependencies specified in the DESCRIPTION
file
in this order:
SystemRequirements:
list OS specific system requirements here, comma separated, these are then installed by the OS's package manager,Depends:
, Imports:
, LinkingTo:
fields are installed by remotes::install_deps()
,Remotes:
fields are installed according to remotes specifications, make sure to list the package in Imports:
as well, the location specified in Remotes:
will be used to get the package from,VersionedPackages:
this field can be used to pin package versions using remotes::install_version()
, do not list these packages in other fields (spaces after operators and after commas inside parentheses are important, e.g. devtools (1.11.0), mypackage (>= 1.12.0, < 1.14)
).You can also modify the Dockerfile
in the template if specific
R version or further customization is needed. The R parent image is defined as a Docker ARG
called R_IMAGE
that you can override. I.e. use the versioned Rocker Debian image using custom build arguments:
faas-cli new --lang rstats-base-plumber hello-rstats-2 --prefix=$OPENFAAS_PREFIX
faas-cli build -f hello-rstats-2.yml --build-arg R_IMAGE=rocker/r-base:4.0.0
You can also edit the stack YAML file:
...
functions:
hello-rstats-2:
lang: rstats-base-plumber
...
build_args:
R_IMAGE: rocker/r-base:4.0.0
System requirements for the same package might be different across Linux distributions. This is a grey area of the R package ecosystem, see these links for help:
Please read the code of conduct.
DCO is required,
sign commits that are submitted as PR (git commit -s -m "Commit message"
).
Copyright (c) 2020, Peter Solymos, Analythium Solutions Inc. MIT