VS Code Sessions

As of the 1.4 Juliet Rose release, RStudio Workbench fully supports launching VS Code sessions from the RStudio Workbench homepage. Launching VS Code sessions requires configuration by an administrator, and this process is described in full detail in the RStudio Workbench Administration Guide.

RStudio Workbench Extension

Overview

RStudio Workbench VS Code sessions are intended to be used with the RStudio Workbench Extension. The extension provides users with a button to open the RStudio Workbench homepage in a new tab and enables users to easily and securely proxy Shiny, Dash, and Streamlit web servers. When the extension is installed, you'll see the RStudio logo in the Activity Bar on the left-hand side of the session and the RStudio Workbench home button in the Status Bar at the bottom of the screen. 

Installation Troubleshooting

VS Code integration requires the use of version 3.9.3 of the code-server binary and the launcher to be configured. When using a batch processing system (e.g. Slurm) or container orchestration platform (e.g. Kubernetes), the binary must be installed in every node that VS Code sessions will be launched in at the same location specified in your vscode.conf file. To verify that code-server is installed and configured properly, from the command line you can run the binary with the version flag. For example, if your binary exists at /opt/code-server/bin/code-server you'd run: /opt/code-server/bin/code-server --version and the output should contain 3.9.3. 

Depending on your configuration, this extension will either be installed manually in a single location using the install-vs-code-ext script or installed automatically when a user launches a session. If the extension has not been installed, you can troubleshoot the issue by returning to the homepage, navigating to the "Jobs" tab of the session's information, and selecting "Details". This will contain any error output that occurred while attempting to perform the install during the session launch.

Proxying Web Servers

The RStudio Workbench Extension includes a "Proxied Servers" view that is displayed when selecting the extension from the Activity Bar. This view contains a list of currently running web servers the user has started since session launch or that are running in the current workspace. Each item in this list contains the web server's name and the port the process is running on. Selecting an item will open the server in a new browser tab. 

The extension determines which servers to display by searching through the processes the user owns for those with open and listening sockets. The extension excludes processes it expects and recognizes as non-development servers such as R and Jupyter sessions. For R and Python processes, the extension represents the server's name as the directory name.

We have ensured the following server types can be proxied when using the extension in VS Code sessions: Shiny, Dash, and Streamlit. Other application types may work as expected as well. 

Shiny

Shiny servers started from the terminal or the Push icon () provided by the R extension can be accessed from the Proxied Servers view without any additional configurations.

Dash

Requirements

• A minimum dash version of 1.10.0 (earlier versions require the user to manually set the port variable in the run_server call)
• The server must be run with the debug argument set to True e.g. app.run_server(debug=True)
• The python-dotenv package (Python apps only)
  • Can be installed with pip install python-dotenv

Environment Variables

VS Code sessions support proxying both R and Dash servers. This is achieved through managing the PORT and DASH_REQUESTS_PREFIX_PATHNAME environment variables in .Renviron and .env files, respectively. Users should avoid setting these variables in their own code and configuration files.

Manually Setting A Port Number

To force RStudio Workbench to use a specific port, set the desired port in the run_server call or add a comment to the top of the main app file containing the port number in the following format:

# .run_server(port='your_port_num_here').

Frequently Asked Questions

Why is my server not running on the port provided in the .env file?

Dash doesn't always respect the port provided in python-dotenv, even when it is properly reading other variables from the file such as DASH_REQUESTS_PREFIX_PATHNAME. RStudio is looking into a long-term fix for this issue, but there are manual steps that can be taken to force dash to respect the provided port. 

To force dash to use the provided port, run your code using the Python extension and VS Code's debugger. Alternatively, update your main application file to load the python-dotenv file prior to importing dash, as in the following:

from dotenv import load_dotenv
load_dotenv()
import dash

Otherwise, the user can manually set the port their application is running on with either option described in Manually Setting A Port Number.

Why do I see "Address already in use" when starting my app, but no servers under Proxied Servers?

Most likely, another user has already started a process using this port. Only servers started by the active user will be displayed under Proxied Servers, but other servers may be running from other users on the system. The RStudio Workbench extension attempts to only use available ports, but dash doesn't always respect the port provided in the python-dotenv file. See Why is my server not running on the port provided in the .env file? for more information.

Why does my Dash application say Loading but never loads?

This often means that Dash isn't reading the environment variables set by RStudio. To troubleshoot this, first confirm all Requirements are met. The following commands can be run to confirm the required packages are installed: pip list | grep python_dotenv, pip list | grep dash.

Next, check the values of the "PORT" and "DASH_REQUESTS_PREFIX_PATHNAME" environment variables from your Python environment. This can be done by using the os package and the command: print(os.environ.get("PORT")). The port should be a number, typically around 8050, and the pathname should have the following pattern: /s/2995c3c9ab5a7abde5fc2/p/61f46e92/. If you've confirmed Python is reading the file but the app is still not working, follow the instructions in Why is my server not running on the port provided in the .env file? for further guidance.

Streamlit

Like Shiny servers, Streamlit servers do not require additional user configuration and will be made available when the user starts them. 

Frequently Asked Questions

Why are there two server entries?

By default, Streamlit applications listen on both IPv4 and IPv6 versions of each port, so the RStudio Workbench Extension creates one entry per open port. This behavior can be modified through Streamlit by setting --server.address=127.0.0.1 when running the app or by changing the setting in your config.toml file. 

Python Extension

VS Code sessions running with the RStudio Workbench extension support Python development and server proxying without any additional extensions required, but users may want to install the Python extension to further improve their development experience. There have been past compatibility issues between code-server and the Python extension, so it is recommended to use the most recent version available in the Extensions Marketplace. At the time this was written this version is  2021.5.842923320, and there are no known issues between it and code-server 3.9.3. 

While RStudio does not provide support for external extensions, we will make issues known as we discover them. Further support can be found on the extension's repository, the code-server repository, and Stack Overflow.

Known Issues With Older Configurations

Extension Fails To Activate

The 2021 Python extension series does not activate with code-server versions before 3.9.3.

Earlier versions of the Python extension would not activate on the user's first VS Code session, requiring the user to quit their first session and start a second to use the extension. 

Debugging

The built-in debugger does not work with versions of code-server before 3.9.3 and several versions of the Python extension. The only version of the extension to work with earlier versions of code-server is v2020.10.332292344. Incompatible versions display the following error when attempting to use the debugger:

Error: The number of constructor arguments in the derived class s must be >= than the number of constructor arguments of its base class.

Frequently Asked Questions

Why does the Extensions Marketplace say "No extensions found"?

This is likely due to your server's configuration. The marketplace can be disabled for certain users by configuring a global extensions directory to which users have read but not write access. This prevents extensions from appearing in the marketplace.

If you have administrative privileges and would like users to be able to manage their own extensions, remove the extensions-dir argument from your vscode.conf file and restart the server. 

Why are there so many pop-ups in the corner?

VS Code provides information and warnings to the user through pop-ups in the lower right corner of the screen. These pop-ups may come from VS Code, the RStudio Workbench Extension, or third-party extensions. Users may see more of them on their first session launch or after installing a new extension. In general, this is the VS Code way of communicating non-urgent messages to users. 

Why am I being warned that my domain is untrusted?

If SSL has not been configured in RStudio Workbench, you may see the following warning when launching a VS Code session: "code-server is being accessed over an insecure domain. Web views, the clipboard, and other functionality will not work as expected."

These limitations occur due to browser restrictions in insecure environments and primarily affect copy/paste functionality. More information regarding the problem, workaround, and improvement plan is available on the code-server repository. Instructions for configuring SSL in RStudio Workbench are available in the Admin Guide. 

Why am I asked if I want to open an external website when clicking a link from the RStudio Workbench Extension?

As a security protection, VS Code prompts for confirmation whenever a link will bring the user outside of their session, even when the destination exists on the same domain. Users can select "Configure Trusted Domains" to add the domain to their trusted domains list and not see these warnings again when prompted with this window. The warning includes the full URL for the address they are trying to navigate to. Trusted domains can only be configured on a per-user basis, and there is no global setting.