docs: default extension in visual studio code

modules/administration-guide/nav.adoc

@@ -101,9 +101,10 @@
 *** xref:enabling-fuse-for-all-workspaces.adoc[]
 * xref:managing-ide-extensions.adoc[]
 ** xref:extensions-for-microsoft-visual-studio-code-open-source.adoc[]
-** xref:trusted-extensions-for-microsoft-visual-studio-code.adoc[]
 * xref:configuring-visual-studio-code.adoc[]
 ** xref:configuring-single-and-multiroot-workspaces.adoc[]
+** xref:trusted-extensions-for-microsoft-visual-studio-code.adoc[]
+** xref:default-extensions-for-microsoft-visual-studio-code.adoc[]
 * xref:managing-workloads-using-the-che-server-api.adoc[]
 * xref:upgrading-che.adoc[]
 ** xref:upgrading-the-chectl-management-tool.adoc[]

modules/administration-guide/pages/configuring-visual-studio-code.adoc

@@ -10,3 +10,5 @@
 Learn how to configure Visual Studio Code - Open Source ("Code - OSS").
 
 * xref:configuring-single-and-multiroot-workspaces.adoc[]
+* xref:trusted-extensions-for-microsoft-visual-studio-code.adoc[]
+* xref:default-extensions-for-microsoft-visual-studio-code.adoc[]

modules/administration-guide/pages/default-extensions-for-microsoft-visual-studio-code.adoc

@@ -0,0 +1,147 @@
+:_content-type: PROCEDURE
+:description: Configure default extensions
+:keywords: extensions, workspace
+:navtitle: Configure default extensions
+// :page-aliases:
+
+[id="visual-studio-code-default-extensions"]
+= Configure default extensions
+
+Default extensions, like recommended extensions, allow you to work with a pre-installed set of extensions.
+
+Recommended extension is specified by adding the extension identifier to the workspace file or to the *.vscode/extensions.json* file of your project.
+When the editor starts, the recommended extension will be fetched from the extension marketplace and installed.
+
+Default extensions are specified by putting the extension binary *.vsix* file path to the __DEFAULT_EXTENSIONS__ environment variable.
+After startup, the editor checks for the environment variable, and if it is specified, takes the path to the extensions and installs it in the background without disturbing the user.
+
+Recommended extensions from *.vscode/extensions.json* and default extensions from the __DEFAULT_EXTENSIONS__ environment variable both installs extensions on editor startup. Recommended extensions are useful when extensions are different per workspace and when the desired extensions are available in the plugin registry configured in {prod-short}. Default extensions described in this documentation are useful for installing .vsix extensions by default from the editor level.
+
+[NOTE]
+====
+It is possible to specify several extensions separated by semicolon.
+
+[source,yaml]
+----
+  DEFAULT_EXTENSIONS='/projects/extension-1.vsix;/projects/extension-2.vsix'
+----
+====
+
+Below you can find several examples how to add *.vsix* files to your workspace and how to define the DEFAULT_EXTENSIONS environment variable.
+
+.Procedure
+
+This documentation describes three different ways to embed default .vsix extensions for your workspace.
+
+* Put the extension binary to the source repository.
++
+The easiest way is to put the extension binary to the Git repository and define the environment variable in the devfile.
+If the *extension.vsix* file exists in the repository root, the __DEFAULT_EXTENSIONS__ could be set for a tooling container.
+Just specify it in your *.devfile.yaml* like below.
++
+[source,yaml]
+----
+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'
+----
+
+* Use the Devfile *postStart* event to fetch extension binaries from the network.
++
+It is possible to use *curl* or *wget* to download extensions to your workspace.
+For that you need to:
++
+** specify a devfile command to donload one or several extensions to your workpace
+** add a *postStart* event to run the command on workspace startup
+** define the __DEFAULT_EXTENSIONS__ environment variable in the Devfile
++
+The following sample demonstrates what should be added to the devfile to add two extensions.
++
+[source,yaml]
+----
+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
+----
+
+* Include the extensions' *.vsix* binaries in the *che-code* image.
++
+Having default extensions bundled in the editor image along with the __DEFAULT_EXTENSIONS__ environment variable defined in a ConfigMap, will allow you to apply the default extensions without the need to change the Devfile.
++
+Following steps will help you to add the extensions you need to the editor image.
++
+1. Create a directory and place one or several *.vsix* extensions in this directory.
++
+2. Create a Dockerfile with following content.
++
+[source,]
+----
+# 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
+----
++
+3. Build the image and then push it to a registry.
++
+[,console]
+----
+$ docker build -t yourname/che-code:next .
+$ docker push yourname/che-code:next
+----
++
+4. Add the new ConfigMap in the user's {orch-namespace}, 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 {orch-namespace}.
++
+[source,yaml]
+----
+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'
+----
++
+5. Create a workspace using *yourname/che-code:next* image.
+First, open the dashboard and navigate to the *Create Workspace* tab on the left-hand side.
+Then, in the *Editor Selector* section expand the *Use an Editor Definition* dropdown and set the editor URI to the *Editor Image*.
+Finally, create a workspace by clicking on any sample or by setting a git repository URL.