Tutorial: Install VS Code on a cloud provider VM and set up remote access

DevSecOps teams can sometimes find they need to run an instance of Visual Studio Code (VS Code) remotely for team members to share when they don't have enough local resources. However, installing, running, and using VS Code on a remote virtual machine (VM) via a cloud provider can be a complex process full of pitfalls and false starts. This tutorial covers how to automate the installation of VS Code on a VM running on a cloud provider.

This approach involves two separate GitLab projects, each with its own pipeline. The first one uses Terraform to instantiate a virtual machine in GCP running Linux Debian. The second one installs VS Code on the newly instantiated VM. Lastly, we provide a procedure on how to set up your local Mac laptop to connect and use the VS Code instance installed on the remote VM.

Create a Debian Linux distribution VM on GCP

Here are the steps to create a Debian Linux distribution VM on GCP.

Prerequisites

1. A GCP account. If you don't have one, please create one.
2. A GitLab account on gitlab.com

Note: This installation uses:

• Debian 5.10.205-2 (2023-12-31) x86_64 GNU/Linux, a.k.a Debian 11

Create a service account and download its key

Before you create the first GitLab project, you need to create a service account in GCP and then generate and download a key. You will need this key so that your GitLab pipelines can communicate to GCP and the GitLab API.

1. To authenticate GCP with GitLab, sign in to your GCP account and create a GCP service account with the following roles:

• Compute Network Admin
• Compute Admin
• Service Account User
• Service Account Admin
• Security Admin

3. Download the JSON file with the service account key you created in the previous step.

4. On your computer, encode the JSON file to base64 (replace /path/to/sa-key.json to the path where your key is located):

   base64 -i /path/to/sa-key.json | tr -d \\n
   

NOTE: Save the output of this command. You will use it later as the value for the BASE64_GOOGLE_CREDENTIALS environment variable.

Configure your GitLab project

Next, you need to create and configure the first GitLab project.

1. Create a group in your GitLab workspace and name it gcpvmlinuxvscode.

2. Inside your newly created group, clone the following project:

   [email protected]:tech-marketing/sandbox/gcpvmlinuxvscode/gcpvmlnxsetup.git
   

3. Drill into your newly cloned project, gcpvmlnxsetup, and set up the following CI/CD variables to configure it:

   1. On the left sidebar, select Settings > CI/CD.
   2. Expand Variables.
   3. Set the variable BASE64_GOOGLE_CREDENTIALS to the base64 encoded JSON file you created in the previous section.
   4. Set the variable TF_VAR_gcp_project to your GCP project ID.
   5. Set the variable TF_VAR_gcp_region to your GCP region ID, e.g. us-east1, which is also its default value.
   6. Set the variable TF_VAR_gcp_zone to your GCP zone ID, e.g. us-east1-d, which is also its default value.
   7. Set the variable TF_VAR_machine_type to the GCP machine type ID, e.g. e2-standard-2, which is also its default value.
   8. Set the variable TF_VAR_gcp_vmname to the GCP vm name you want to give the VM, e.g. my-test-vm, which is also its default value.

Note: We have followed a minimalist approach to set up this VM. If you would like to customize the VM further, please refer to the Google Terraform provider and the Google Compute Instance Terraform provider documentation for additional resource options.

Provision your VM

After configuring your project, manually trigger the provisioning of your VM as follows:

1. On the left sidebar, go to Build > Pipelines.
2. Next to Play ({play}), select the dropdown list icon ({chevron-lg-down}).
3. Select Deploy to manually trigger the deployment job.

When the pipeline finishes successfully, you can see your new VM on GCP:

• Check it on your GCP console's VM instances list.

Remove the VM

Important note: Only run the cleanup job when you no longer need the GCP VM and/or the VS Code that you installed in it.

A manual cleanup job is included in your pipeline by default. To remove all created resources:

1. On the left sidebar, select Build > Pipelines and select the most recent pipeline.
2. For the destroy job, select Play ({play}).

Install and set up VS Code on a GCP VM

Perform the steps in this section only after you have successfully finished the previous sections above. In this section, you will create the second GitLab project that will install VS Code and its dependencies on the running VM on GCP.

Prerequisites

1. A provisioned GCP VM. We covered this in the previous sections.

Note: This installation uses:

• VS Code Version 1.85.2

Configure your project

Note: Since you will be using the ssh command multiple times on your laptop, we strongly suggest that you make a backup copy of your laptop local directory $HOME/.ssh before continuing.

Next, you need to create and configure the second GitLab project.

1. Head over to your GitLab group gcpvmlinuxvscode, which you created at the beginning of this post.

2. Inside group, gcpvmlinuxvscode, clone the following project:

   [email protected]:tech-marketing/sandbox/gcpvmlinuxvscode/vscvmsetup.git
   

3. Drill into your newly cloned project, vscvmsetup and set up the following CI/CD variables to configure it:

   1. On the left sidebar, select Settings > CI/CD.
   2. Expand Variables.
   3. Set the variable BASE64_GOOGLE_CREDENTIALS to the base64 encoded JSON file you created in project gcpvmlnxvsc. You can copy this value from the variable with the same name in project gcpvmlnxvsc.
   4. Set the variable gcp_project to your GCP project ID.
   5. Set the variable gcp_vmname to your GCP region ID, e.g. us-east1.
   6. Set the variable gcp_zone to your GCP zone ID, e.g. us-east1-d.
   7. Set the variable vm_pwd to the password that you will use to ssh to the VM.
   8. Set the variable gcp_vm_username to the first portion (before the "@" sign) of the email associated to your GCP account, which should be your GitLab email.

Run the project pipeline

After configuring the second GitLab project, manually trigger the provisioning of VS Code and its dependencies to the GCP VM as follows:

1. On the left sidebar, select Build > Pipelines and click on the button Run Pipeline. On the next screen, click on the button Run pipeline.

   The pipeline will:

   • install xauth on the virtual machine. This is needed for effective X11 communication between your local desktop and the VM
   • install git on the VM
   • install Visual Studio Code on the VM.

2. At this point, you can wait until the pipeline successfully completes. If you don't want to wait, you can continue to do the first step of the next section. However, you must ensure the pipeline has successfully completed before you can perform Step 2 of the next section.

Connect to your VM from your local Mac laptop

Now that you have an instance of VS Code running on a Linux VM on GCP, you need to configure your Mac laptop to be able to act as a client to the remote VM. Follow these steps:

1. To connect to the remote VS Code from your Mac, you must first install XQuartz on your Mac. You can execute the following command on your Mac to install it:

brew install xquartz

Or, you can follow the instructions from the following tutorial from the University of North Dakota.

After the pipeline for project vscvmsetup successfully executes to completion (pipeline you manually executed in the previous section), you can connect to the remote VS Code as follows:

2. Launch XQuartz on your Mac (it should be located in your Applications folder). Its launching should open up an xterm on your Mac. If it does not, then you can select Applications > Terminal from the XQuartz top menu.
3. On the xterm, enter the following command:

gcloud compute ssh --zone "[GCP zone]" "[name of your VM]" --project "[GCP project]" --ssh-flag="-Y"

Where:

• [VM name] is the name of the VM you created in project gcpvmlnxvsc. Its value should be the same as the gcp_project variable.
• [GCP zone] is the zone where the VM is running. Its value should be the same as the gcp_vmname variable.
• [GCP project] is the name of your GCP project assigned name. Its value should be the same as the gcp_project variable.

Note: If you have not installed the Google Cloud CLI, please do so by following the Google documentation.

4. If you have not used SSH on your Mac before, you may not have a .ssh in your HOME directory. If this is the case, you will be asked if you would like to continue with the creation of this directory. Answer Y.

5. Next, you will be asked to enter the same password twice to generate a public/private key. Enter the same password you used when defining the variable vm_pwd in the required configuration above.

6. Once the SSH key is done propagating, you will need to enter the password again two times to log in to the VM.

7. You should now be logged in to the VM.

Create a personal access token

The assumption here is that you already have a GitLab project that you would want to open from and work on the remote VS Code. To do this, you will need to clone your GitLab project from the VM. First, you will be using a personal access token (PAT) to clone your project.

1. Head over to your GitLab project (the one that you'd like to open from the remote VS Code).
2. From your GitLab project, create a PAT, name it pat-gcpvm and ensure that it has the following scopes: read_repository, write_repository, read_registry, write_registry, and ai_features
3. Save the generated PAT somewhere safe; you will need it later.

Clone the read_repository

1. On your local Mac, from the xterm where you are logged on to the remote VM, enter the following command:

git clone https://[your GitLab username]:[personal_access_token]@gitlab.com/[GitLab project name].git 

Where:

• [your GitLab username] is your GitLab handle.
• [personal_access_token] is the PAT you created in the previous section.
• [GitLab project name] is the name of the project that contains the GitLab Code Suggestions test cases.

Launch Visual Studio Code

1. From the xterm where you are logged in to the VM, enter the following command:

code

Wait for a few seconds and Visual Studio Code will appear on your Mac screen.

2. From the VS Code menu, select **File > Open Folder..."
3. In the File chooser, select the top-level directory of the GitLab project you cloned in the previous section

That's it! You're ready to start working on your cloned GitLab project using the VS Code that you installed on a remote Linux-based VM.

Troubleshooting

While using the remotely installed VS Code from your local Mac, you may encounter a few issues. In this section, we provide guidance on how to mitigate them.

Keyboard keys not mapped correctly

If, while running VS Code, you are having issues with your keyboard keys not being mapped correctly, e.g. letter e is backspace, letter r is tab, letter s is clear line, etc., do the following:

1. In VS Code, select File > Preferences > Settings.
2. Search for "keyboard". If having issues with the letter e, then search for "board". Click on the "Keyboard" entry under "Application."
3. Ensure that the Keyboard Dispatch is set to "keyCode."
4. Restart VS Code.
5. If you need further help, this is a good resource for keyboard problems.

Error loading webview: Error

If while running VS Code, you get a message saying:

"Error loading webview: Error: Could not register service worker: InvalidStateError: Failed to register a ServiceWorker: The document is in an invalid state."

1. Exit VS Code and then enter this cmd from the xterm window:

killall code

You may need to execute this command two or three times in a row to kill all VS Code processes.

2. Ensure that all VS Code-related processes are gone by entering the following command from the xterm window:

ps -ef | grep code

3. Once all the VS Code-related processes are gone, restart VS Code by entering the following command from the xterm window:

code

Some useful commands to debug SSH

Here are some useful commands to run on the VM that can help you debug SSH issues:

1. To get the status, location and latest event of sshd:

sudo systemctl status ssh

2. To see the log of sshd:

journalctl -b -a -u ssh

3. To restart to SSH daemon:

sudo systemctl restart ssh.service

Or

sudo systemctl restart ssh

4. To start a root shell:

sudo -s

Get started

This article described how to:

• instantiate a Linux-based VM on GCP
• install VS Code and dependencies on the remote VM
• clone an existing GitLab project of yours in the remote VM
• open your remotely cloned project from the remotely installed VS Code

As a result, you can basically use your laptop as a thin client that accesses a remote server, where all the work takes place.

The automation to get all these parts in place was done by GitLab. Sign up for a free 30-day GitLab Ultimate trial to get started today!