Step 2. Verify Installation

Log files & diagnostic tools

Run the verification process and identify any configuration issues in your environment.

Posit Workbench includes an installation verification tool that attempts to launch sessions and jobs and provide diagnostic output for issues related to running Launcher sessions, ad hoc jobs, Jupyter sessions, or VS Code sessions.

The following troubleshooting steps will help you run the verification process and identify any configuration issues in your environment.

Running a test to verify your installation and configuration

The verification process requires you to stop the Workbench service, which can be done using the following command:

$ sudo rstudio-server stop

Set default container images

If using a container-based Job Launcher cluster, add the following lines to your Workbench configuration file so that the verification process uses these Docker images during the testing process (replace <workbench version> with your desired version of Workbench including the build number, for example rstudio-workbench-2023.12.1-XXX.proX):

/etc/rstudio/rserver.conf

launcher-sessions-container-images=rstudio/r-session-complete:jammy-<workbench version>
launcher-adhoc-container-images=rstudio/r-session-complete:jammy-<workbench version>

Note

If using launcher-sessions-auto-update as recommended in the Launcher Configuration documentation, you should use the following Docker images:

/etc/rstudio/rserver.conf

launcher-sessions-container-images=rstudio/workbench-session:ubuntu2204-r4.4.1_4.3.3-py3.12.6_3.11.10
launcher-adhoc-container-images=rstudio/workbench-session:ubuntu2204-r4.4.1_4.3.3-py3.12.6_3.11.10

You can then start the Launcher verification process by using the following command:

$ sudo rstudio-server verify-installation --verify-user=<USER>

Replace <USER> with a valid user that is able to use Workbench in your installation.

The verification process will perform tests using the specified user account and check various aspects of launching sessions and jobs, including mounting the user’s home directories into containers.

A successful verification test will return output similar to the following:

Checking Job Launcher configuration...
Ensuring server-user is a Job Launcher admin...
Getting list of Job Launcher clusters...
Job launcher configured with the following clusters: Kubernetes, Local
launcher-adhoc-clusters is empty - all clusters may be used to launch adhoc jobs
launcher-sessions-clusters is empty - all clusters may be used to launch session jobs
02 May 2020 05:29:35 [rserver] WARNING Project sharing is currently not supported when running launcher sessions. 
It has automatically been disabled for session 4d4356ec67e7babe88f4a; LOGGED FROM: 
void rstudio::server::job_launcher::setProfile(const string&, const string&, const string&, const string&, 
bool, rstudio::core::r_util::SessionLaunchProfile*)
/var/lib/jenkins/workspace/IDE/pro-pipeline/v1.2-patch/src/cpp/server/ServerJobLauncher.cpp:107
Launched R session job for cluster Kubernetes and image rstudio/r-session-complete:jammy-<workbench version>
Waiting for job to run...
Job transitioned to status Pending
Job transitioned to status Pending with status message: Created pod: session-4d4356ec67e7babe88f4a-rstudio---session-test-job-xkbfw2
Job transitioned to status Pending with status message: 
Successfully assigned rstudio/session-4d4356ec67e7babe88f4a-rstudio---session-test-job-xkbfw2 to ip-172-31-30-139.us-east-2.compute.internal
Job transitioned to status Pending with status message: containers with unready status: [50506d5573575359475966796a636c2b3342333574413d3d]
Job transitioned to status Pending with status message: Container image "rstudio/r-session-complete:jammy-<workbench version>" already present on machine
Job transitioned to status Pending with status message: Created container 50506d5573575359475966796a636c2b3342333574413d3d
Job transitioned to status Pending with status message: Started container 50506d5573575359475966796a636c2b3342333574413d3d
Job is running
Waiting for job to finish...
Job has finished running
Job exited successfully
02 May 2020 05:29:40 [rserver] WARNING Project sharing is currently not supported when running launcher sessions. 
It has automatically been disabled for session 4d4356ec67e7b2e24a23f; 
LOGGED FROM: void rstudio::server::job_launcher::setProfile(const string&, const string&, const string&, const string&, 
bool, rstudio::core::r_util::SessionLaunchProfile*) /var/lib/jenkins/workspace/IDE/pro-pipeline/v1.2-patch/src/cpp/server/ServerJobLauncher.cpp:1070
Launched R session job for cluster Local
Waiting for job to run...
Job transitioned to status Pending
Job is running
Waiting for job to finish...
Job has finished running
Job exited successfully
Launched adhoc job for cluster Kubernetes and image rstudio/r-session-complete:jammy-<workbench version>
Waiting for job to run...
Job transitioned to status Pending
Job transitioned to status Pending with status message: Created pod: adhoc-test-job-lz77v-s85b6
Job transitioned to status Pending
Job transitioned to status Pending with status message: Successfully assigned rstudio/adhoc-test-job-lz77v-s85b6 
to ip-172-31-30-139.us-east-2.compute.internal
Job transitioned to status Pending with status message: containers with unready status: [4d74786b6474446a546d51476a6b657843335a444b513d3d]
Job transitioned to status Pending with status message: Container image "rstudio/r-session-complete:jammy-<workbench version>" already present on machine
Job transitioned to status Pending with status message: Created container 4d74786b6474446a546d51476a6b657843335a444b513d3d
Job transitioned to status Pending with status message: Started container 4d74786b6474446a546d51476a6b657843335a444b513d3d
Job has finished running
Job exited successfully
Launched adhoc job for cluster Local
Waiting for job to run...
Job transitioned to status Pending
Job is running
Waiting for job to finish...
Job has finished running
Job exited successfully

Otherwise, the testing process will show any errors that occurred.

Restart services and test

After running the verification process then identifying and correcting any issues, restart the Workbench and Launcher services:

$ sudo rstudio-server restart
$ sudo rstudio-launcher restart

Verify that the services are running and try to start a new session from the Workbench home page.

If the services are still not starting or you are still experiencing errors when starting a new session, then proceed
Step 3 - Check Service Status.