Chapter 6. Configuring Visual Studio Code - Open Source ("Code - OSS")

Procedure

• Provide your own workspace file.

  • Put a workspace file with the name .code-workspace into the root of your repository. After workspace creation, the Visual Studio Code - Open Source ("Code - OSS") will use the workspace file as it is.

    {
    	"folders": [
    		{
    			"name": "project-name",
    			"path": "."
    		}
    	]
    }

    Important

    Be careful when creating a workspace file. In case of errors, an empty Visual Studio Code - Open Source ("Code - OSS") will be opened instead.

    Important

    If you have several projects, the workspace file will be taken from the first project. If the workspace file does not exist in the first project, a new one will be created and placed in the /projects directory.

• Specify alternative workspace file.

  • Define the VSCODE_DEFAULT_WORKSPACE environment variable in your devfile and specify the right location to the workspace file.

       env:
         - name: VSCODE_DEFAULT_WORKSPACE
           value: "/projects/project-name/workspace-file"

• Open a workspace in a single-root mode.

  • Define VSCODE_DEFAULT_WORKSPACE environment variable and set it to the root.

       env:
         - name: VSCODE_DEFAULT_WORKSPACE
           value: "/"

Verification

• The value of the variable will be parsed on the workspace startup and the corresponding trustedExtensionAuthAccess section will be added to the product.json.

• Put the extension binary into the source repository.
• Use the devfile postStart event to fetch extension binaries from the network.
• Include the extensions' .vsix binaries in the che-code image.

Procedure

• Specify DEFAULT_EXTENSIONS in your .devfile.yaml as shown in the following example:

  schemaVersion: 2.3.0
  metadata:
    generateName: example-project
  components:
    - name: tools
      container:
        image: quay.io/devfile/universal-developer-image:ubi8-latest
        env:
          - name: 'DEFAULT_EXTENSIONS'
            value: '/projects/example-project/extension.vsix'

• specify a devfile command to download extensions to your workpace
• add a postStart event to run the command on workspace startup
• define the DEFAULT_EXTENSIONS environment variable in the devfile

Procedure

• Add the values shown in the following example to the devfile:

  schemaVersion: 2.3.0
  metadata:
    generateName: example-project
  components:
    - name: tools
      container:
        image: quay.io/devfile/universal-developer-image:ubi8-latest
        env:
          - name: DEFAULT_EXTENSIONS
            value: '/tmp/extension-1.vsix;/tmp/extension-2.vsix'
  
  commands:
    - id: add-default-extensions
      exec:
        # name of the tooling container
        component: tools
        # download several extensions using curl
        commandLine: |
          curl https://.../extension-1.vsix --location -o /tmp/extension-1.vsix
          curl https://.../extension-2.vsix --location -o /tmp/extension-2.vsix
  
  events:
    postStart:
      - add-default-extensions

  Warning

  In some cases curl may download a .gzip compressed file. This might make installing the extension impossible. To fix that try to save the file as a .vsix.gz file and then decompress it with gunzip. This will replace the .vsix.gz file with an unpacked .vsix file.

  curl https://some-extension-url --location -o /tmp/extension.vsix.gz
  gunzip /tmp/extension.vsix.gz

Procedure

• Create a directory and place your selected .vsix extensions in this directory.

• Create a Dockerfile with the following content:

  # inherit che-incubator/che-code:latest
  FROM quay.io/che-incubator/che-code:latest
  USER 0
  
  # copy all .vsix files to /default-extensions directory
  RUN mkdir --mode=775 /default-extensions
  COPY --chmod=755 *.vsix /default-extensions/
  
  # add instruction to the script to copy default extensions to the working container
  RUN echo "cp -r /default-extensions /checode/" >> /entrypoint-init-container.sh

• Build the image and then push it to a registry:

  $ docker build -t yourname/che-code:next .
  $ docker push yourname/che-code:next

• Add the new ConfigMap to the user’s project, define the DEFAULT_EXTENSIONS environment variable, and specify the absolute paths to the extensions. This ConfigMap sets the environment variable to all workspaces in the user’s project.

  kind: ConfigMap
  apiVersion: v1
  metadata:
    name: vscode-default-extensions
    labels:
      controller.devfile.io/mount-to-devworkspace: 'true'
      controller.devfile.io/watch-configmap: 'true'
    annotations:
      controller.devfile.io/mount-as: env
  data:
    DEFAULT_EXTENSIONS: '/checode/default-extensions/extension1.vsix;/checode/default-extensions/extension2.vsix'

• Create a workspace using yourname/che-code:next image. First, open the dashboard and navigate to the Create Workspace tab on the left side.

  1. In the Editor Selector section, expand the Use an Editor Definition dropdown and set the editor URI to the Editor Image.
  2. Create a workspace by clicking on any sample or by using a Git repository URL.