Configuration

Workbench

This section describes how to configure the example page, shown below. The upper-region has controls for experimenting with the Tutorial API calls, and the lower region is an <iframe> hosting Posit Workbench.

Allow IFrame

For security reasons, Posit Workbench will not load inside a browser frame (such as an iframe) by default. You can modify this behavior by using the www-frame-origin option. See Frame origin for full details.

To enable the Tutorial API example page to host Posit Workbench on a non-production localhost server, do the following:

/etc/rstudio/rserver.conf

www-frame-origin=http://localhost:8080

Note

If the www-frame-origin option is set to same or any instead of a URI, you must add the following setting with the actual URI:

/etc/rstudio/rsession.conf

tutorial-api-client-origin=http://localhost:8080

Enable API calls from host page

To enable calling the Tutorial APIs from the hosting page:

/etc/rstudio/rsession.conf

tutorial-api-enabled=1

Enable callbacks from RStudio to host page

Workbench may optionally notify the hosting page of certain events using the JavaScript PostMessage mechanism.

The receiver is responsible for parsing, interpreting, and reacting to the value of the callbacks. Any JavaScript running in the context of the IDE iframe could do an arbitrary SendMessage to the parent (in addition to those being generated by the RStudio Pro IDE JavaScript). The host page should ensure the response string is valid JSON, and follows one of the patterns described in Tutorial API Callbacks.

To enable callbacks:

/etc/rstudio/rsession.conf

tutorial-api-parent-notify-enabled=1

Disable Posit Workbench home page

The Tutorial API cannot be used to manipulate the Posit Workbench Home Page. To disable the home page:

/etc/rstudio/rserver.conf

server-user-home-page=0

Note

The server-user-home-page setting is automatically forced on if Job Launcher sessions are enabled via launcher-sessions-enabled=true in /etc/rstudio/rserver.conf.

Disable multiple session support

Even with the Home Page disabled, a user can still open new sessions via Session / New Session which will open a new IDE instance outside of the host page. To prevent this:

/etc/rstudio/rserver.conf

server-multiple-sessions=0

If multiple sessions are disabled, the Home Page is automatically turned off, so not necessary to include both settings.

Note

The server-multiple-sessions setting is automatically forced on when Job Launcher sessions are enabled via launcher-sessions-enabled=true in /etc/rstudio/rserver.conf.

Serve the example page

Serve the folder /usr/lib/rstudio-server/extras/tutorial with a web server. For example, change to that directory in a terminal and run this command:

python2 -m SimpleHTTPServer 8080

python3 -m http.server 8080

Load http://localhost:8080/demo.htm in a web browser and you should see the page shown earlier.