opencpu-server.Rnw

\documentclass{scrartcl}

\usepackage[colorlinks, urlcolor=blue]{hyperref}
\usepackage[toc,page]{appendix}
\usepackage{fullpage}
\usepackage{fancyvrb}
\usepackage{upquote}
\usepackage{xspace}

\newcommand{\R}{\texttt{R}\xspace}
\newcommand{\OpenCPU}{\texttt{OpenCPU}\xspace}
\newcommand{\HTTP}{\texttt{HTTP}\xspace}
\newcommand{\API}{\texttt{API}\xspace}
\newcommand{\GUI}{\texttt{GUI}\xspace}
\newcommand{\HTTPS}{\texttt{HTTPS}\xspace}
\newcommand{\RPC}{\texttt{RPC}\xspace}
\newcommand{\nginx}{\texttt{nginx}\xspace}
\newcommand{\apache}{\texttt{apache}\xspace}
\newcommand{\AppArmor}{\texttt{AppArmor}\xspace}
\newcommand{\Linux}{\texttt{Linux}\xspace}
\newcommand{\JSON}{\texttt{JSON}\xspace}
\newcommand{\GET}{\texttt{GET}\xspace}
\newcommand{\POST}{\texttt{POST}\xspace}
\newcommand{\CRAN}{\texttt{CRAN}\xspace}
\newcommand{\Github}{\texttt{Github}\xspace}

%use vspace instead of indentation for paragraphs
\usepackage{parskip}

\newenvironment{codeblock}{
  \VerbatimEnvironment
  %\begin{knitrout}
  \definecolor{shadecolor}{rgb}{0.95, 0.95, 0.95}\color{fgcolor}
  \color{black}
  \begin{kframe}
  \begin{alltt}
}{
  \end{alltt}%
  \end{kframe}
  %\end{knitrout}
}


\title{The OpenCPU Server PDF Manual}

\author{Version 2.2}
\date{}

\begin{document}

\maketitle

 The latest version of this document is available at \href{https://github.com/opencpu/server-manual}{https://github.com/opencpu/server-manual}. Typos, comments, suggestions about this manual go in the \href{https://github.com/opencpu/server-manual/issues}{issues page} for the repo. 

\tableofcontents

\section{What is OpenCPU}

%Internet access, public cloud computing, live and open data and scientific super computers are transforming the landscape of data analysis. Researchers increasingly collaborate by sharing data, code and results online. This is a powerful way to learn and teach statistical analysis and at the same time it improves transparency and accessibility of the underlying methods. Moreover, by centralizing computation we can address some scalability challenges and facilitate direct integration of analyses in systems and applications. We expect that producing reproducible materials and analysis tools, in addition to a written report or article, will soon become an integral part of the scientific publication process. The \OpenCPU framework is a first attempt at building the foundations to support such integrated, collaborative, reproducible analysis systems. 

\OpenCPU is a system for embedded scientific computing and reproducible research. The server exposes an \HTTP \API to develop and execute scripts, functions and reports. The system addresses many of the domain specific problems inherent to scientific computing, and abstracts away technicalities behind a well defined intuitive \HTTP interface. This provides a foundation for scalable applications with embedded statistical analysis, visualization and reporting.

\OpenCPU uses \R only for what it is good at: analysis and graphics. The system separates the statistical computing from other parts of your application. \OpenCPU runs on a remote server, interfaced only through the \HTTP \API. Clients need no knowledge of \R: the \OpenCPU \API defines a mapping between \HTTP requests and \R function calls which results in a natural \RPC protocol. Any software program that speaks \HTTP can call \R functions and scripts, without the need to understand, generate or parse \R code.

\begin{codeblock}
curl http://localhost/ocpu/library/stats/R/rnorm/json --data n=3
[
  3.05644,
  0.38511,
  1.11983
]
\end{codeblock}

From there it is up to the client on how to process or present the output. \OpenCPU deliberately does not include, suggest or enforce the use of any specific web development language, \GUI, etc. You are not restricted to a limited set of available widgets or panels that fits the \R paradigm. \OpenCPU manages incoming requests, security, resource allocation, data \texttt{I/O} and other technicalities. Nothing more, nothing less. This is the main difference with frameworks that include built-in templates to generate out-of-the-box widgets from \R code. Emphasis in the design of \OpenCPU is on interoperability, reliability and simplicity in order to develop scalable, production quality software. Because \OpenCPU layers on \HTTP, we can leverage existing technology (cache-control, \texttt{SSL}, load balancing, etc). Finally, the \API definition makes it possible to gracefully extend, re-implement or replace parts of the system in the future.

\subsection{Using OpenCPU in a team}

\OpenCPU decouples the roles of analyst and web developer. The analyst implements and documents \R functions or scripts, just as he is used to. The web developers can use their favorite language, tools and web frameworks to call such analyses over \texttt{HTTP}. \OpenCPU provides the bridge between these two systems, without imposing additional constraints on either side. There is no need for the web developer to learn \R, nor does the analyst have to worry about \GUI or web related technicalities. This separation is supposed to keep applications well organized and easy to maintain, while making collaboration within a team of statisticians and developers easier than when the two parts are tightly intertwined.

\subsection{Security model}

Rather than traditional user-role based access control, \OpenCPU uses mandatory access control (\texttt{MAC}) based security. On Debian/Ubuntu systems, this is implemented using \AppArmor: a security module in the \Linux kernel. Thereby we can define and enforce security policies on a by-process level. This protects against system abuse or excessive use of hardware resources without limiting the \R functionality that clients can use. The security policies are completely customizable, and section \ref{security} talks a bit more on security and \AppArmor. 

Because Redhat systems do not support \AppArmor, \OpenCPU runs without the advanced security policies on these platforms. Instead, it runs in the standard SElinux \texttt{httpd\_modules\_t} context. This is fine for internal use, but it is not recommended to expose your Fedora/EL OpenCPU server to the web without further configuring SELinux for your application.

The \texttt{MAC} based security profiles make it possible to open up an \OpenCPU server directly to the web. However it is also perfectly fine to employ \OpenCPU solely as a computational back-end inside some larger system or application, similar to e.g. your database server. In such a design, users do not interact directly with the \OpenCPU server, and can only use functionality exposed in your application layer.

\subsection{OpenCPU Apps}

\OpenCPU defines a standard way to build and share \emph{apps}. An \OpenCPU app is an \R package which, in addition to the regular contents, ships with some web page(s). These pages interact with the \R functions in this package through the \OpenCPU \API. By convention, these web pages (\texttt{html/css/js} files) are included in the \texttt{/inst/www/} directory of the \R source package. This way, \OpenCPU apps provide a convenient way to package and ship standalone \R web applications. 

Because \OpenCPU apps are simply \R packages, they are developed, distributed and installed the same way as any other \R package. Several example apps are available from the \texttt{rwebapps} github organization at \href{https://github.com/rwebapps}{https://github.com/rwebapps}. For example to run the \href{https://github.com/rwebapps/markdownapp}{markdownapp} app:

<<eval=FALSE>>=
library(opencpu)
ocpu_start_app("rwebapps/markdownapp")
@

If the application was installed on an \OpenCPU cloud server, the app is directly available. Point your browser to \href{http://your.server.com/ocpu/apps/rwebapps/markdownapp}{http://your.server.com/ocpu/apps/rwebapps/markdownapp}.

 To make development of \OpenCPU apps easier, a \texttt{JavaScript} client library is available called \href{https://github.com/opencpu/opencpu.js}{opencpu.js}. This library depends on \texttt{jQuery} and uses \texttt{\$.ajax} to provide \texttt{JavaScript} wrappers to the \OpenCPU \API. It is not required to use this \texttt{JavaScript} library but it provides a convenient basis for building \R web applications.

\subsection{The OpenCPU single-user server}

Two implementations of \OpenCPU are available: a single-user server that runs inside an interactive \R session, and a cloud server that builds on \apache and \nginx. The single-user server is intended for development and local use only. The latest version can easily be installed in \R from \CRAN:

<<eval=FALSE>>=
install.packages("opencpu")
@

Load the \OpenCPU package to start the local server:

<<eval=FALSE>>=
library(opencpu)
ocpu_start_server()
@


 Because \R is single-threaded, the single-user server does not support concurrent requests (but httpuv does a good job in queuing them). Also it does not enforce any security. The single-user server is great for developing apps, that can later be published on the \OpenCPU cloud server. When using the single-user server, we can easily load the apps for local use:


<<eval=FALSE>>=
ocpu_start_app("rwebapps/markdownapp")
@


 The \texttt{ocpu\_start\_app} function will automatically open the app in the default web browser.  


\section{Installing the OpenCPU cloud server}

The \OpenCPU cloud server version 2.2 runs on \textbf{Ubuntu 20.04 or 18.04}. The \OpenCPU system consists of a number of standard Ubuntu installation packages. These are:

\begin{itemize}
 \item \texttt{opencpu} -- Alias for \texttt{opencpu-server}.
 \item \texttt{opencpu-server} -- The main \OpenCPU \API server. Depends on \texttt{R} and \texttt{apache2}.
 \item \texttt{opencpu-full} -- Installs \texttt{opencpu}, \texttt{texlive}, \texttt{git}, \texttt{rstudio-server} and more.
 \item \texttt{opencpu-cache} -- Caching server. Not recommended for users. For internal use only.
\end{itemize}

\subsection{Getting an Ubuntu server}

The recommended installation of \OpenCPU 2.2 requires Ubuntu version 20.04. Any flavour of Ubuntu will do, e.g. Ubuntu Desktop, Ubuntu Server, Kubuntu, Edubuntu, etc. The preferred way of running \OpenCPU is on a clean Ubuntu Server edition. A copy of the Ubuntu Server installation disc ISO can be obtained from the Ubuntu download pages at \url{http://www.ubuntu.com/download/server}.

Another way to get started is by spinning up a pay-by-hour server instance on Amazon EC2. When using \OpenCPU on EC2, it is highly recommended to pick one of the \textbf{compute optimized} instance types, for example \texttt{c3.large}. The Ubuntu team provides very nice ready-to-go daily updated preinstalled Ubuntu-Server images for EC2 at \url{http://cloud-images.ubuntu.com/trusty/current/}.

Yet another possibility is to install Ubuntu Server on a virtual machine within another OS. On Linux we can use KVM, for Windows the free VMware Player or Oracle Virtualbox are available, and on OSX we can use Virtualbox or Parallels to run virtual machines. Regardless of the platform, it is good practice to run the \OpenCPU cloud server on a separate virtual machine rather than installing it directly in your application server. Isolating the \OpenCPU server within a virtual machine is nice from a security point of view and prevents \OpenCPU or \R from interfering with other software on your server. Furthermore hypervisors such as KVM provide nice control over hardware resources for guest machines. The \OpenCPU public demo servers run as virtual machines on a KVM hypervisor which has resulted in excellent performance, smooth upgrades and no major incidents for several years.

\subsection{Basic OpenCPU installation}

Before installing \OpenCPU, make sure the system is up to date:

\begin{codeblock}
sudo apt-get update
sudo apt-get upgrade
\end{codeblock}
To install \OpenCPU start by adding the repository to the system:

\begin{codeblock}
sudo add-apt-repository ppa:opencpu/opencpu-2.2 -y
sudo apt-get update
\end{codeblock}

We can now go ahead and install the server:

\begin{codeblock}
sudo apt-get install opencpu-server
\end{codeblock}

Installation on a clean server might take a while because \R and Latex both have many dependencies. After installation is done, we should be able to open a browser and point it to the \texttt{/ocpu} path at server address e.g: \href{http://your.server.com/ocpu}{http(s)://your.server.com/ocpu}. If the welcome page shows up, the installation has succeeded. 

Finally, to get install \OpenCPU together with a lot of other potentially useful things:

\begin{codeblock}
sudo apt-get install opencpu-full
\end{codeblock}

This package will install \texttt{opencpu-server}, \texttt{texlive}, \texttt{rstudio-server}, \texttt{git} and some more. Note that this takes is at least several GB of disk space on a fresh system.

\subsection{Uninstall OpenCPU}

To uninstall either of the \OpenCPU packages:

\begin{codeblock}
sudo apt-get purge opencpu-server
\end{codeblock}

Removing the \texttt{opencpu} \emph{repository} from the system is done by deleting the repository file from the \texttt{/etc/apt/sources.list.d/} directory.  
  
\section{Managing the OpenCPU cloud server}

To enable \OpenCPU in Apache2 on Ubuntu:

\begin{codeblock}
sudo a2ensite opencpu
sudo apachectl restart
\end{codeblock}

To disable \OpenCPU site in Apache2 on Ubuntu:

\begin{codeblock}
sudo a2dissite opencpu
sudo apachectl restart
\end{codeblock}

\subsection{Relevant log files}

When things are not working as expected, in most cases the problem is reported by \apache or \Linux. If the \OpenCPU server is not coming online at all, we might find out whats wrong from the web server error logs:

\begin{codeblock}
sudo tail /var/log/apache2/error.log
sudo tail /var/log/opencpu/apache_error.log
\end{codeblock}

If you are seeing permission denied errors, either in the \OpenCPU \API or in the \apache logs, this is likely a problem with the \AppArmor security profile. \AppArmor security violations are logged to \texttt{kern.log}:

\begin{codeblock}
sudo tail /var/log/kern.log
\end{codeblock}

Section \ref{security} has more information on customizing \OpenCPU security policies in the cloud server. 

\subsection{Installing R packages on the server}

In order for packages to be accessible through \texttt{/ocpu/library/}, they need to be installed in the global library. Note that \R needs to be started as root to install packages in the global library. To install a single source package:

\begin{codeblock}
wget http://cran.r-project.org/src/contrib/glmnet_1.9-5.tar.gz
sudo R CMD INSTALL glmnet_1.9-5.tar.gz --library=/usr/local/lib/R/site-library
\end{codeblock}

Alternatively we can use an interactive session to install packages from \CRAN or \Github:

\begin{codeblock}
sudo -i
R
\end{codeblock}

From here it is business as usual:
<<eval=FALSE>>=
install.packages("ggplot2")
install.packages("glmnet")

library(devtools)
install_github("dplyr", "hadley")
@

After restarting the \OpenCPU service, the packages are accessible through the \API:

\indent \url{http://your.server.com/ocpu/library/ggplot2} \\
\indent \url{http://your.server.com/ocpu/library/glmnet} \\
\indent \url{http://your.server.com/ocpu/library/dplyr} 

Alternatively, some precompiled \texttt{r-cran-xxx} packages are available from Ubuntu repositories:
 
\begin{codeblock}
sudo apt-get install r-cran-xml
\end{codeblock}

Appendix \ref{c2d4u} explains how to use third party repositories like \texttt{c2d4u} to install packages that are not included with Ubuntu by default. 

\subsection{Configuring the OpenCPU cloud server}

The \OpenCPU configuration file is written in \JSON and located at \texttt{/etc/opencpu/server.conf}. It has a hand full of server-wide settings and options to enable/disable or fine-tune certain parts of the system. A few important options are:

\begin{itemize}
 \item \textbf{httpcache.post} -- Value of \texttt{cache-control} header: time in seconds that \HTTP \POST requests are cached if cache server is installed. Defaults to 5 minutes.
 \item \textbf{preload} -- List of packages to be preloaded when the server starts. This can severely increase performance of frequently used packages.
 \item \textbf{timelimit.post} -- Time in seconds after which \HTTP \POST requests get terminated. Defaults to 90 seconds.
 \item \textbf{rlimit.as} -- Maximum memory that can be allocated by a single request. Default 2 GB.
 \item \textbf{rlimit.fsize} -- Maximum size of files that a request can create. Default 100 MB.
 \item \textbf{rlimit.nproc} -- Maximum number of concurrent processes that the server is allowed to use. Defaults to 50 processes.
\end{itemize}

To modify configurations, the administrator can edit this file or alternatively create a new file in the directory \texttt{server.conf.d}. Files in \texttt{/etc/opencpu/server.conf.d/} with a filename ending in \texttt{.conf} are automatically loaded by opencpu-server. These settings override settings in \texttt{/etc/opencpu/server.conf}. The server needs a restart for configurations to take effect:

\begin{codeblock}
sudo apachectl restart
\end{codeblock}

Make sure that all configuration files are formatted using valid \JSON at all times. Finally there is an additional optional configuration file that is only used for github authentication information at \texttt{/etc/opencpu/secret.conf}. This file is readable by the \OpenCPU system, but not by \OpenCPU users. It has three fields: \texttt{auth\_token}, \texttt{client\_id} and \texttt{client\_secret}. Setting a valid \Github ``application access token" makes it possible to use continuous integration for private \Github repositories. It also raises the hourly github \API limits from 100 to 5000 hits per hour. Currently this is only relevant for listing repositories through the \texttt{/ocpu/gist} and \texttt{/ocpu/github} \API.

\subsection{Setting up SSL certificates for HTTPS}

Installation of \OpenCPU will automatically enable \HTTPS in your web server. Hence you should be able to access \OpenCPU via \texttt{https://your.server.com/ocpu}. By default, the server uses self-signed ``snake-oil" \texttt{SSL} certificates that are included with Ubuntu. These are convenient for development, but don't provide real security and will trigger the ``untrusted host" warning in most modern browsers. Once you go in production, it is recommended to replace these certificates with your own \texttt{SSL} certificates, signed by a certificate authority. 

 To set up \HTTPS for \texttt{opencpu-server} the certificates need to be configured in \apache. This is done in \texttt{/etc/apache2/sites-available/default-ssl}. The file contains comments with further instructions. After configuring the certificates, restart \apache for things to take effect.

\subsection{Customizing the security profile}
\label{security}

The \OpenCPU cloud server uses \AppArmor profiles and the \texttt{RAppArmor} package to enforce security policies. The profiles used by \OpenCPU are stored in \texttt{/etc/apparmor.d/opencpu.d/}. For an introduction on the topic see the \href{https://github.com/jeroenooms/RAppArmor#readme}{RAppArmor Github page} and \href{http://arxiv.org/abs/1303.4808}{RAppArmor article in JSS}.

The default profiles included with \OpenCPU are quite liberal but prevent most types of malicious behavior. However, if you plan to use \OpenCPU in production, it is recommended to review these policies and revise them according to your needs. To keep your custom rules separated from the general profiles, add them to the \texttt{/etc/apparmor.d/opencpu.d/custom} file. After modifying a security profile restart \AppArmor:

\begin{codeblock}
sudo service apparmor restart
\end{codeblock}

One nice way to debug a security profile is by monitoring the \texttt{kern.log} file while using \OpenCPU:

\begin{codeblock}
sudo tail -f /var/log/kern.log | grep opencpu
\end{codeblock}

If any \R package or process called from \OpenCPU attempts to do something that is not allowed in the current security profile, a line containing \texttt{DENIED} is printed to \texttt{kern.log}.

\section{Testing the OpenCPU API}

A complete overview of the \OpenCPU \API is available on the website: \href{http://www.opencpu.org}{www.opencpu.org}. Below some examples that illustrate basic functionality and verify that things are working. Also note that \OpenCPU ships with a little testing page that can be used to do \HTTP requests. The testing page can be found at \url{http://your.server.com/ocpu/test}. 

\subsection{Using Curl to test}

Basic \HTTP \GET requests can be performed either by simply opening a URL in a web browser, or with a curl command:

\begin{codeblock}
curl -L http://your.server.com/ocpu/library/
\hlkwd{abc
abind
abn
...}
\end{codeblock}

The \texttt{-L} flag makes \texttt{curl} follow redirects which is sometimes needed. In addition, the \texttt{-v} flag prints more verbose output which includes \HTTP request/response headers:

\begin{codeblock}
curl -L -v http://your.server.com/ocpu/library/
\end{codeblock}

To perform a \HTTP \POST in curl, either use the \texttt{-X POST} or \texttt{-d [args]} flag. For example:

\begin{codeblock}
curl http://your.server.com/ocpu/library/utils/R/sessionInfo -X POST
curl http://your.server.com/ocpu/library/stats/R/rnorm -d "n=10&mean=100"
\end{codeblock}

\subsection{Reading package objects, manuals and files}

The following URLs are examples of resources in \OpenCPU which are retrieved using \HTTP \GET:

\indent \url{http://your.server.com/ocpu/test} \\
\indent \url{http://your.server.com/ocpu/library} \\
\indent \url{http://your.server.com/ocpu/library/stats/R} \\
\indent \url{http://your.server.com/ocpu/library/stats/R/rnorm} \\
\indent \url{http://your.server.com/ocpu/library/stats/man} \\
\indent \url{http://your.server.com/ocpu/library/stats/man/rnorm/text} \\
\indent \url{http://your.server.com/ocpu/library/stats/man/rnorm/html} \\
\indent \url{http://your.server.com/ocpu/library/stats/man/rnorm/pdf} \\
\indent \url{http://your.server.com/ocpu/library/MASS} \\
\indent \url{http://your.server.com/ocpu/library/MASS/data/Boston} \\
\indent \url{http://your.server.com/ocpu/library/MASS/data/Boston/json} \\
\indent \url{http://your.server.com/ocpu/library/MASS/data/Boston/csv} \\
\indent \url{http://your.server.com/ocpu/library/MASS/data/Boston/rda} 

Apart from \R objects and manuals, \OpenCPU also hosts any static files in package: 

\indent \url{http://your.server.com/ocpu/library/knitr/examples/} \\
\indent \url{http://your.server.com/ocpu/library/knitr/examples/knitr-minimal.Rnw} \\
\indent \url{http://your.server.com/ocpu/library/knitr/doc/knitr-intro.R} \\
\indent \url{http://your.server.com/ocpu/library/brew/example1.brew} \\
\indent \url{http://your.server.com/ocpu/library/devtools/NEWS} \\
\indent \url{http://your.server.com/ocpu/library/devtools/DESCRIPTION} 

\subsection{Calling a function}

Performing a \HTTP \POST on a function results in a function call where the \HTTP request arguments are mapped to the function call. In \OpenCPU, a successful \texttt{POST} requests usually returns a \texttt{HTTP 201} status, and the response body contains the locations of the output data:

\begin{codeblock}
curl http://your.server.com/ocpu/library/stats/R/rnorm -d "n=10&mean=100"
\hlkwd{/ocpu/tmp/x032a8fee/R/.val
/ocpu/tmp/x032a8fee/stdout
/ocpu/tmp/x032a8fee/source
/ocpu/tmp/x032a8fee/console
/ocpu/tmp/x032a8fee/info}
\end{codeblock}

The output can then be retrieved using \HTTP \GET. When calling an \R function, the output object is always called \texttt{.val}. However, calling scripts might result in other \R objects. In this case we could \GET:

\indent \url{http://your.server.com/ocpu/tmp/x032a8fee/R/.val} \\
\indent \url{http://your.server.com/ocpu/tmp/x032a8fee/R/.val/json} \\
\indent \url{http://your.server.com/ocpu/tmp/x032a8fee/R/.val/ascii} \\
\indent \url{http://your.server.com/ocpu/tmp/x032a8fee/R/.val/rda} \\
\indent \url{http://your.server.com/ocpu/tmp/x032a8fee/console} 

 In a very similar fashion we can produce a plot:

\begin{codeblock}
curl http://your.server.com/ocpu/library/ggplot2/R/qplot \verb|\|
  -d "x=[1,2,3,4,5]&y=[8,9,7,8,7]&geom='line'"
\hlkwd{/ocpu/tmp/x07a773be/R/.val
/ocpu/tmp/x07a773be/graphics/1
/ocpu/tmp/x07a773be/source
/ocpu/tmp/x07a773be/console
/ocpu/tmp/x07a773be/info}
\end{codeblock}

Which we can then retrieve in PNG, PDF or SVG format using \HTTP \GET:

\indent \url{http://server.com/ocpu/tmp/x07a773be/graphics/1/png?width=800&height=500} \\
\indent \url{http://server.com/ocpu/tmp/x07a773be/graphics/1/pdf?width=12&height=7} \\
\indent \url{http://server.com/ocpu/tmp/x07a773be/graphics/1/svg?width=12&height=7}

 There is one exception to this rule: in the common special case where the client is only interested in the \JSON representation of the object returned by the function, the \HTTP \POST request path can be post-fixed with \texttt{/json}:

\begin{codeblock}
curl http://your.server.com/ocpu/library/stats/R/rnorm/json -d "n=2"
[
  -1.2804,
  -0.75013
]
\end{codeblock}
In this case, a successful call will return 200 (instead of 201), and the response body contains the output from the function in \JSON; no need to do an additional \GET request. However in most cases, the two-step procedure is preferred.

 Finally It is also possible to specify \emph{input} arguments to a function call using \JSON:

\begin{codeblock}
curl http://your.server.com/ocpu/library/stats/R/rnorm \verb|\|
-H "Content-Type: application/json" -d '\{"n":10, "mean": 10, "sd":10\}'
\end{codeblock}


\subsection{Executing a script}

Besides calling a function, the \HTTP \POST method can also be used to execute a script. The script is interpreted according to it's file extension. Currently the following extensions are supported: \texttt{R} (Rscript), \texttt{Rnw}, \texttt{Rmd} (knitr), \texttt{brew} (brew), \texttt{tex} (latex), \texttt{md} (pandoc):

\begin{codeblock}
curl -X POST http://server.com/ocpu/library/knitr/examples/knitr-minimal.Rnw
curl -X POST http://server.com/ocpu/library/knitr/examples/knitr-minimal.Rmd
curl -X POST http://server.com/ocpu/library/knitr/doc/knitr-intro.R
curl -X POST http://server.com/ocpu/library/brew/example1.brew
\end{codeblock}

 In contrast to a function, a script has no formal arguments. Instead, the \HTTP \POST arguments can be passed to the script interpreter. For example, when calling a \texttt{brew} script, we can pass a value for the \href{https://www.rforge.net/doc/packages/brew/brew.html}{\texttt{output}} argument in brew (e.g. to send the output stream to a specific file), and \texttt{Rmd}/\texttt{md} files have a \href{https://www.rforge.net/doc/packages/knitr/pandoc.html}{\texttt{format}} argument to specify the pandoc output format:

\begin{codeblock}
curl server.com/ocpu/library/knitr/examples/knitr-minimal.Rmd -d format=docx
curl server.com/ocpu/library/knitr/examples/knitr-minimal.Rmd -d format=odt
curl server.com/ocpu/library/knitr/examples/knitr-minimal.Rmd -d format=html
curl server.com/ocpu/library/brew/example1.brew -d output=out.txt
\end{codeblock}


\subsection{Online package repositories}

 If the \OpenCPU cloud server has direct access to the internet, it can also provide access to packages and/or scripts from online repositories, such as \CRAN or \Github. This is convenient for development: package authors and users can test and use \OpenCPU apps without the need for an administrator to install packages on the server. However, note that the administrator can easily disable these features so they might not be available on every \OpenCPU server.
 
\subsubsection*{Github}

The \texttt{/ocpu/apps/:user/:package/} \API interfaces to \textbf{packages} which are on the \texttt{master} branch in a \Github user repository. For this to work, the github repository must contain the source \R package, and the repository name must be identical to the package name:

\indent \url{http://your.server.com/ocpu/apps/jeroen/} \\
\indent \url{http://your.server.com/ocpu/apps/jeroen/curl} \\
\indent \url{http://your.server.com/ocpu/apps/jeroen/curl/R} \\
\indent \url{http://your.server.com/ocpu/apps/jeroen/curl/R/curl_fetch_memory} \\
\indent \url{http://your.server.com/ocpu/apps/jeroen/curl/man/curl_fetch_memory} 

\begin{appendices}

\section{Installing \texttt{r-cran} packages from \texttt{c2d4u}}
\label{c2d4u}

R packages can be installed on the server in the usual ways, as was described earlier. However, on \Linux, \R packages need to be compiled from source which requires more time and additional build dependencies. As an alternative, Dirk Eddelbuettel and Michael Rutter have ``debianized" many of the popular \R packages on \CRAN and Bioconductor. Thereby, precompiled binaries of these \R packages can be installed using \texttt{apt-get}. For Ubuntu, many of these packages are available from Launchpad:

\begin{codeblock}
sudo add-apt-repository ppa:marutter/rrutter3.5 -y
sudo add-apt-repository ppa:marutter/c2d4u3.5 -y
sudo apt-get update
\end{codeblock}

This adds the required repositories to the system and retrieves the latest package list. To see which packages are currently available:

\begin{codeblock}
apt-cache search r-cran
apt-cache search r-bioc
\end{codeblock}

And to install a package:

\begin{codeblock}
sudo apt-get install r-cran-ggplot2
\end{codeblock}

And then navigate to \url{http://your.server.com/ocpu/library/ggplot2/}

\section{Using OpenCPU with RStudio}

The \OpenCPU cloud server works great together with RStudio server. Both systems run best on Ubuntu and will happily share the same \R installation. You can use RStudio server to develop and install \R packages/apps and make them available through the \OpenCPU \API. Starting version 1.3, the \OpenCPU repository includes a copy of \texttt{rstudio-server} for easy installation.

\begin{codeblock}
sudo apt-get install rstudio-server
\end{codeblock}

By default both \apache and \nginx are configured to proxy the \texttt{/rstudio/} path. Hence after installing both \texttt{opencpu} and \texttt{rstudio-server} they can be accessed directly through:

\indent \url{https://your.server.com/ocpu/} \\
\indent \url{https://your.server.com/rstudio/} 

Consult \url{https://www.rstudio.com/ide/docs/server/} for information on managing and configuring \texttt{rstudio-server}. Note that when a non-root user installs a package in \R or RStudio, the package will not be installed in the global library, but in the user personal package library. Personal package libraries are available through the \API at the \texttt{/user/:name/library}, e.g: \url{https://your.server.com/ocpu/user/jeroen/library}.

 Note that user libraries are only be available to \OpenCPU if the respective user has set the file mode permissions (\texttt{chmod}) to public readable (which is the default on Ubuntu). 

\end{appendices}

\end{document}