Posit Workbench Code Server

Workbench

PWB Code Server

Starting in Workbench version 2024.09, Posit powers VS Code Sessions with Posit Workbench Code Server (PWB Code Server), which is built directly off a fork of Microsoft’s Visual Studio Code - Open Source repository. Previous versions of Workbench used an open-source project called code-server to run VS Code sessions in Posit Workbench. Using coder/code-server to run VS Code sessions is no longer supported.

New Workbench installation

If Workbench 2024.09 is being installed as a fresh install, the PWB Code server is configured as the default code server. Additional migration steps, shown below, aren’t required. You can continue to configure PWB Code Server as described on the PWB Code Server configuration page.

Migration

PWB Code Server comes bundled with Workbench version 2024.07 and greater. However, if you’re upgrading from a previously installed version, your preexisting configuration may still be configured for the legacy code-server installation. To migrate over to PWB Code Server:

  1. Update the exe option in vscode.conf to point to the new PWB Code Server binary (this can be done manually or with the configure-vs-code command)
  2. Update the args option in vscode.conf to remove legacy options not recognized by PWB Code Server
  3. Determine whether or not to migrate user data into PWB Code Server
  4. Install or migrate any extensions into PWB Code Server
  5. (Optional) Remove the legacy software from the filesystem
  6. Restart Workbench for the changes to take effect

Step 1: Update the exe option in vscode.conf

Follow one of the following options: manually updating, or using the configure-vs-code command

Option 1a: Manually update exe option

In vscode.conf modify the exe option to exe=/usr/lib/rstudio-server/bin/pwb-code-server/bin/code-server.

Option 1b: Regenerate vscode.conf with configure-vs-code
Backup your configuration files

The command in this section can overwrite your vscode.conf and vscode-user-settings.json files. It is recommended to backup these files before continuing in case you need to revert the changes made.

If you don’t have a highly customized VS Code configuration, you can regenerate vscode.conf with new default values. To overwrite your vscode.conf file and replace it with the new default values, run:

Terminal
sudo rstudio-server configure-vs-code

Step 2: Migrating code server args

The default setting in vscode.conf of args=--host=0.0.0.0 is the same for both code servers. If you haven’t modified this value, skip this section.

If the args option includes --verbose to turn on logging, this should be changed to the analog for PWB Code server: --log trace, or removed to turn off debug logging.

If you have configured custom value(s) in the args option, it is possible PWB Code Server does not support them. If this is the case, users can still launch VS Code sessions in most scenarios. Doing so logs a warning to the session’s Details page in the following format:

Ignoring option 'option-name': not supported for the server.

If you have configured a global extensions directory by including --extensions-dir= in args, PWB Code Server uses the same directory for extensions, and they do not need to be reinstalled. If you configure PWB Code Server to use a different directory, copy the code-server directory to this new directory or follow the process described in [Installing extensions].

Step 3: Migrating user data

Both code servers store data in a dedicated directory within each user’s home directory. This data includes state, logs, user settings, and extensions the user has installed themselves.

If you have not specified a user-data-dir option in vscode.conf, PWB Code Server uses a different directory than code-server, and users need to reinstall any extensions they have installed themselves and reconfigure their environments. Using separate directories prevents either code server from reading, modifying, or removing data from the other code server. By default, PWB Code Server uses ~/.vscode-server. The legacy code server uses ~/.local/share/code-server.

To preserve user’s settings and extensions, you can instruct them to copy their current data directory to PWB Code Server’s data directory. Alternatively, you can configure PWB Code Server to use the old directory by setting user-data-dir=~/.local/share/code-server in vscode.conf.

If users can install their own extensions, and you do not migrate user extensions, all extensions configured in vscode.extensions.conf are installed on the user’s first session launch.

Step 4: Installing extensions

If you have configured a new global extensions directory or are using user extension directories and did not migrate extensions, after configuring PWB Code Server in vscode.conf, follow the Posit Workbench Extension installation instructions.

The instructions for Pre-installing extensions apply as well, but when using a global extensions directory, be sure to use the binary under pwb-code-server to run the commands with the PWB Code Server binary directly. For example:

Terminal
$ export PWB_CODE_SERVER=/usr/lib/rstudio-server/bin/pwb-code-server/bin/code-server
$ $PWB_CODE_SERVER --extensions-dir=/opt/code-server/extensions --install-extension <your-extension-here>

Step 5: (Optional) Remove legacy software

PWB Code Server bundles the PWB VS Code Extension so that it no longer needs to be installed separately. If you had previously installed this to a global extensions directory, you can now remove it.

Future releases of Workbench will remove the legacy VS Code components. If you’d like to remove these now, delete the following directories:

  • /usr/lib/rstudio-server/bin/code-server
  • /usr/lib/rstudio-server/bin/vscode-workbench-ext

Step 6: Restart Workbench

Once you’ve finished making all the changes above, restart Workbench

Terminal
$ sudo rstudio-server restart
Back to top