From 87dde9679c2dc14d40734fcf54b2bc594ac4ee31 Mon Sep 17 00:00:00 2001 From: Vitaliy Gulyy Date: Wed, 13 Nov 2024 18:19:05 +0200 Subject: [PATCH 01/17] docs: default extension in visual studio code Signed-off-by: Vitaliy Gulyy --- modules/administration-guide/nav.adoc | 3 +- .../pages/configuring-visual-studio-code.adoc | 2 + ...ions-for-microsoft-visual-studio-code.adoc | 137 ++++++++++++++++++ 3 files changed, 141 insertions(+), 1 deletion(-) create mode 100644 modules/administration-guide/pages/default-extensions-for-microsoft-visual-studio-code.adoc diff --git a/modules/administration-guide/nav.adoc b/modules/administration-guide/nav.adoc index a85fcb205c..1efb5e5a30 100644 --- a/modules/administration-guide/nav.adoc +++ b/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[] diff --git a/modules/administration-guide/pages/configuring-visual-studio-code.adoc b/modules/administration-guide/pages/configuring-visual-studio-code.adoc index eeae434a06..cc084e05ef 100644 --- a/modules/administration-guide/pages/configuring-visual-studio-code.adoc +++ b/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[] diff --git a/modules/administration-guide/pages/default-extensions-for-microsoft-visual-studio-code.adoc b/modules/administration-guide/pages/default-extensions-for-microsoft-visual-studio-code.adoc new file mode 100644 index 0000000000..5c30a7bb8a --- /dev/null +++ b/modules/administration-guide/pages/default-extensions-for-microsoft-visual-studio-code.adoc @@ -0,0 +1,137 @@ +:_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 is started up, the recommended extension will be fetched from the extension marketplace and installed. + +Default extension is specified by putting the extension binary *.vsix* file path to the __DEFAULT_EXTENSIONS__ environment variable. +After the startup, the editor checks for the environment variable, and if it is specified, takes the path to the extension and installs it in the background without disturbing the user. + +[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 a *.vsix* files to your workspace and how to define DEFAULT_EXTENSIONS environment variable. + +.Procedure + +* 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] +---- +components: + - name: tools + container: + image: quay.io/devfile/universal-developer-image:ubi8-latest + env: + - name: 'DEFAULT_EXTENSIONS' + value: '/projects/sample/extension.vsix' +---- + +* Use Devfile *postStart* event to fetch the extension binary 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 __DEFAULT_EXTENSIONS__ environment variable in the Devfile ++ +Following sample demonstrate what should be added to the devfile to add two extensions. ++ +[source,yaml] +---- +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 extension *.vsix* binaries to *che-code* image. ++ +Having default extensions bundled in the editor image along with __DEFAULT_EXTENSIONS__ environment variable defined in a configmap, will allow you to use 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, prepare and put one or several *.vsix* extensions to 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 the registry. ++ +[,console] +---- +$ docker build -t yourname/che-code:next . +$ docker push yourname/che-code:next +---- ++ +4. Add new configmap, define __DEFAULT_EXTENSIONS__ environment variable, specify absolute paths to the extensions. ++ +[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 *Create Workspace*. +Then, in the *Editor Selector* section expand *Use an Editor Definition* and put the editor URI to the *Editor Image*. +Finally, create a workspace by clicking on any sample or by putting a git resitory URL. From 196dfd9350cad90dcdaea9778c17532e5ffa0dff Mon Sep 17 00:00:00 2001 From: Vitaliy Gulyy Date: Wed, 13 Nov 2024 18:40:39 +0200 Subject: [PATCH 02/17] docs: default extension in visual studio code Signed-off-by: Vitaliy Gulyy --- .../default-extensions-for-microsoft-visual-studio-code.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/modules/administration-guide/pages/default-extensions-for-microsoft-visual-studio-code.adoc b/modules/administration-guide/pages/default-extensions-for-microsoft-visual-studio-code.adoc index 5c30a7bb8a..39729290c8 100644 --- a/modules/administration-guide/pages/default-extensions-for-microsoft-visual-studio-code.adoc +++ b/modules/administration-guide/pages/default-extensions-for-microsoft-visual-studio-code.adoc @@ -84,7 +84,7 @@ events: * Include extension *.vsix* binaries to *che-code* image. + -Having default extensions bundled in the editor image along with __DEFAULT_EXTENSIONS__ environment variable defined in a configmap, will allow you to use default extensions without the need to change the Devfile. +Having default extensions bundled in the editor image along with __DEFAULT_EXTENSIONS__ environment variable defined in a config map, will allow you to use default extensions without the need to change the Devfile. + Following steps will help you to add the extensions you need to the editor image. + @@ -114,7 +114,7 @@ $ docker build -t yourname/che-code:next . $ docker push yourname/che-code:next ---- + -4. Add new configmap, define __DEFAULT_EXTENSIONS__ environment variable, specify absolute paths to the extensions. +4. Add new config map, define __DEFAULT_EXTENSIONS__ environment variable, specify absolute paths to the extensions. + [source,yaml] ---- From 9813b95d1665d82a7dcf3d32d03816f77e343c61 Mon Sep 17 00:00:00 2001 From: Vitaliy Gulyy Date: Thu, 14 Nov 2024 15:25:54 +0200 Subject: [PATCH 03/17] Update modules/administration-guide/pages/default-extensions-for-microsoft-visual-studio-code.adoc Co-authored-by: David Kwon --- .../default-extensions-for-microsoft-visual-studio-code.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/administration-guide/pages/default-extensions-for-microsoft-visual-studio-code.adoc b/modules/administration-guide/pages/default-extensions-for-microsoft-visual-studio-code.adoc index 39729290c8..5229206b29 100644 --- a/modules/administration-guide/pages/default-extensions-for-microsoft-visual-studio-code.adoc +++ b/modules/administration-guide/pages/default-extensions-for-microsoft-visual-studio-code.adoc @@ -10,7 +10,7 @@ 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 is started up, the recommended extension will be fetched from the extension marketplace and installed. +When the editor starts, the recommended extension will be fetched from the extension marketplace and installed. Default extension is specified by putting the extension binary *.vsix* file path to the __DEFAULT_EXTENSIONS__ environment variable. After the startup, the editor checks for the environment variable, and if it is specified, takes the path to the extension and installs it in the background without disturbing the user. From 87335693613689005e7557be15059197fe5190d9 Mon Sep 17 00:00:00 2001 From: Vitaliy Gulyy Date: Thu, 14 Nov 2024 15:26:11 +0200 Subject: [PATCH 04/17] Update modules/administration-guide/pages/default-extensions-for-microsoft-visual-studio-code.adoc Co-authored-by: David Kwon --- .../default-extensions-for-microsoft-visual-studio-code.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/administration-guide/pages/default-extensions-for-microsoft-visual-studio-code.adoc b/modules/administration-guide/pages/default-extensions-for-microsoft-visual-studio-code.adoc index 5229206b29..b3b9dff5f9 100644 --- a/modules/administration-guide/pages/default-extensions-for-microsoft-visual-studio-code.adoc +++ b/modules/administration-guide/pages/default-extensions-for-microsoft-visual-studio-code.adoc @@ -12,7 +12,7 @@ Default extensions, like recommended extensions, allow you to work with a pre-in 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 extension is specified by putting the extension binary *.vsix* file path to the __DEFAULT_EXTENSIONS__ environment variable. +Default extensions are specified by putting the extension binary *.vsix* file path to the __DEFAULT_EXTENSIONS__ environment variable. After the startup, the editor checks for the environment variable, and if it is specified, takes the path to the extension and installs it in the background without disturbing the user. [NOTE] From 70d1e5ac405cfb98614ac6bd4a0f3eb2b2a2bb05 Mon Sep 17 00:00:00 2001 From: Vitaliy Gulyy Date: Thu, 14 Nov 2024 15:26:41 +0200 Subject: [PATCH 05/17] Update modules/administration-guide/pages/default-extensions-for-microsoft-visual-studio-code.adoc Co-authored-by: David Kwon --- .../default-extensions-for-microsoft-visual-studio-code.adoc | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/modules/administration-guide/pages/default-extensions-for-microsoft-visual-studio-code.adoc b/modules/administration-guide/pages/default-extensions-for-microsoft-visual-studio-code.adoc index b3b9dff5f9..6a82209f3d 100644 --- a/modules/administration-guide/pages/default-extensions-for-microsoft-visual-studio-code.adoc +++ b/modules/administration-guide/pages/default-extensions-for-microsoft-visual-studio-code.adoc @@ -13,7 +13,9 @@ Recommended extension is specified by adding the extension identifier to the wor 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 the startup, the editor checks for the environment variable, and if it is specified, takes the path to the extension and installs it in the background without disturbing the user. +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] ==== From d65da71a1b3ce595d871000094943aa53e6a12c9 Mon Sep 17 00:00:00 2001 From: Vitaliy Gulyy Date: Thu, 14 Nov 2024 15:27:05 +0200 Subject: [PATCH 06/17] Update modules/administration-guide/pages/default-extensions-for-microsoft-visual-studio-code.adoc Co-authored-by: David Kwon --- .../default-extensions-for-microsoft-visual-studio-code.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/administration-guide/pages/default-extensions-for-microsoft-visual-studio-code.adoc b/modules/administration-guide/pages/default-extensions-for-microsoft-visual-studio-code.adoc index 6a82209f3d..ff0f695244 100644 --- a/modules/administration-guide/pages/default-extensions-for-microsoft-visual-studio-code.adoc +++ b/modules/administration-guide/pages/default-extensions-for-microsoft-visual-studio-code.adoc @@ -27,7 +27,7 @@ It is possible to specify several extensions separated by semicolon. ---- ==== -Below you can find several examples how to add a *.vsix* files to your workspace and how to define DEFAULT_EXTENSIONS environment variable. +Below you can find several examples how to add *.vsix* files to your workspace and how to define the DEFAULT_EXTENSIONS environment variable. .Procedure From 42f8beaf94eb133baa886640f5dedbbdce52c518 Mon Sep 17 00:00:00 2001 From: Vitaliy Gulyy Date: Thu, 14 Nov 2024 15:27:58 +0200 Subject: [PATCH 07/17] Update modules/administration-guide/pages/default-extensions-for-microsoft-visual-studio-code.adoc Co-authored-by: David Kwon --- .../default-extensions-for-microsoft-visual-studio-code.adoc | 2 ++ 1 file changed, 2 insertions(+) diff --git a/modules/administration-guide/pages/default-extensions-for-microsoft-visual-studio-code.adoc b/modules/administration-guide/pages/default-extensions-for-microsoft-visual-studio-code.adoc index ff0f695244..19424e3912 100644 --- a/modules/administration-guide/pages/default-extensions-for-microsoft-visual-studio-code.adoc +++ b/modules/administration-guide/pages/default-extensions-for-microsoft-visual-studio-code.adoc @@ -31,6 +31,8 @@ Below you can find several examples how to add *.vsix* files to your workspace a .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. From e4e3e300098a9edc5627f382e339db51efa0758e Mon Sep 17 00:00:00 2001 From: Vitaliy Gulyy Date: Thu, 14 Nov 2024 15:28:51 +0200 Subject: [PATCH 08/17] Update modules/administration-guide/pages/default-extensions-for-microsoft-visual-studio-code.adoc Co-authored-by: David Kwon --- .../default-extensions-for-microsoft-visual-studio-code.adoc | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/modules/administration-guide/pages/default-extensions-for-microsoft-visual-studio-code.adoc b/modules/administration-guide/pages/default-extensions-for-microsoft-visual-studio-code.adoc index 19424e3912..4ea06dc3ff 100644 --- a/modules/administration-guide/pages/default-extensions-for-microsoft-visual-studio-code.adoc +++ b/modules/administration-guide/pages/default-extensions-for-microsoft-visual-studio-code.adoc @@ -41,13 +41,16 @@ 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/sample/extension.vsix' + value: '/projects/example-project/extension.vsix' ---- * Use Devfile *postStart* event to fetch the extension binary from the network. From 692ffb8277aa17f0e25ade1ef1f44151e143f232 Mon Sep 17 00:00:00 2001 From: Vitaliy Gulyy Date: Thu, 14 Nov 2024 15:29:55 +0200 Subject: [PATCH 09/17] Update modules/administration-guide/pages/default-extensions-for-microsoft-visual-studio-code.adoc Co-authored-by: David Kwon --- .../default-extensions-for-microsoft-visual-studio-code.adoc | 3 +++ 1 file changed, 3 insertions(+) diff --git a/modules/administration-guide/pages/default-extensions-for-microsoft-visual-studio-code.adoc b/modules/administration-guide/pages/default-extensions-for-microsoft-visual-studio-code.adoc index 4ea06dc3ff..70112dcb84 100644 --- a/modules/administration-guide/pages/default-extensions-for-microsoft-visual-studio-code.adoc +++ b/modules/administration-guide/pages/default-extensions-for-microsoft-visual-studio-code.adoc @@ -66,6 +66,9 @@ Following sample demonstrate what should be added to the devfile to add two exte + [source,yaml] ---- +schemaVersion: 2.3.0 +metadata: + generateName: example-project components: - name: tools container: From 159f97453297de7086c4dd4d0a0c41c2a106c2f8 Mon Sep 17 00:00:00 2001 From: Vitaliy Gulyy Date: Thu, 14 Nov 2024 15:38:20 +0200 Subject: [PATCH 10/17] Apply suggestions from code review Co-authored-by: David Kwon --- ...ions-for-microsoft-visual-studio-code.adoc | 22 +++++++++---------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/modules/administration-guide/pages/default-extensions-for-microsoft-visual-studio-code.adoc b/modules/administration-guide/pages/default-extensions-for-microsoft-visual-studio-code.adoc index 70112dcb84..54d877649c 100644 --- a/modules/administration-guide/pages/default-extensions-for-microsoft-visual-studio-code.adoc +++ b/modules/administration-guide/pages/default-extensions-for-microsoft-visual-studio-code.adoc @@ -53,16 +53,16 @@ components: value: '/projects/example-project/extension.vsix' ---- -* Use Devfile *postStart* event to fetch the extension binary from the network. +* 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 __DEFAULT_EXTENSIONS__ environment variable in the Devfile +** define the __DEFAULT_EXTENSIONS__ environment variable in the Devfile + -Following sample demonstrate what should be added to the devfile to add two extensions. +The following sample demonstrates what should be added to the devfile to add two extensions. + [source,yaml] ---- @@ -92,13 +92,13 @@ events: - add-default-extensions ---- -* Include extension *.vsix* binaries to *che-code* image. +* Include the extensions' *.vsix* binaries in the *che-code* image. + -Having default extensions bundled in the editor image along with __DEFAULT_EXTENSIONS__ environment variable defined in a config map, will allow you to use default extensions without the need to change the Devfile. +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, prepare and put one or several *.vsix* extensions to this directory. +1. Create a directory and place one or several *.vsix* extensions in this directory. + 2. Create a Dockerfile with following content. + @@ -116,7 +116,7 @@ COPY --chmod=755 *.vsix /default-extensions/ RUN echo "cp -r /default-extensions /checode/" >> /entrypoint-init-container.sh ---- + -3. Build the image and then push it to the registry. +3. Build the image and then push it to a registry. + [,console] ---- @@ -124,7 +124,7 @@ $ docker build -t yourname/che-code:next . $ docker push yourname/che-code:next ---- + -4. Add new config map, define __DEFAULT_EXTENSIONS__ environment variable, specify absolute paths to the extensions. +4. Add the new ConfigMap, 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] ---- @@ -142,6 +142,6 @@ data: ---- + 5. Create a workspace using *yourname/che-code:next* image. -First, open the dashboard and navigate to *Create Workspace*. -Then, in the *Editor Selector* section expand *Use an Editor Definition* and put the editor URI to the *Editor Image*. -Finally, create a workspace by clicking on any sample or by putting a git resitory URL. +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. From 6750ee241f154b1f4d4a47030f286b2b11a5d53d Mon Sep 17 00:00:00 2001 From: Vitaliy Gulyy Date: Thu, 14 Nov 2024 16:47:48 +0200 Subject: [PATCH 11/17] Update modules/administration-guide/pages/default-extensions-for-microsoft-visual-studio-code.adoc Co-authored-by: David Kwon --- .../default-extensions-for-microsoft-visual-studio-code.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/administration-guide/pages/default-extensions-for-microsoft-visual-studio-code.adoc b/modules/administration-guide/pages/default-extensions-for-microsoft-visual-studio-code.adoc index 54d877649c..413b40d048 100644 --- a/modules/administration-guide/pages/default-extensions-for-microsoft-visual-studio-code.adoc +++ b/modules/administration-guide/pages/default-extensions-for-microsoft-visual-studio-code.adoc @@ -124,7 +124,7 @@ $ docker build -t yourname/che-code:next . $ docker push yourname/che-code:next ---- + -4. Add the new ConfigMap, 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}. +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] ---- From 2c63de4be90d0f85e90b32a918bad15e542481fa Mon Sep 17 00:00:00 2001 From: Vitaliy Gulyy Date: Thu, 14 Nov 2024 19:53:14 +0200 Subject: [PATCH 12/17] docs: default extension in visual studio code Signed-off-by: Vitaliy Gulyy --- ...xtensions-for-microsoft-visual-studio-code.adoc | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/modules/administration-guide/pages/default-extensions-for-microsoft-visual-studio-code.adoc b/modules/administration-guide/pages/default-extensions-for-microsoft-visual-studio-code.adoc index 413b40d048..500092024e 100644 --- a/modules/administration-guide/pages/default-extensions-for-microsoft-visual-studio-code.adoc +++ b/modules/administration-guide/pages/default-extensions-for-microsoft-visual-studio-code.adoc @@ -91,6 +91,18 @@ events: postStart: - add-default-extensions ---- ++ +[WARNING] +==== +It some cases *curl* may download *gzip* compressed file. This may make it impossible to install the extension. +To fix that try to save the file to *.vsix.gz* and then decompress it with *gunzip*. It will replace *.vsix.gz* with unpacked *.vsix* file. + +[source,yaml] +---- +curl https://some-extension-url --location -o /tmp/extension.vsix.gz +gunzip /tmp/extension.vsix.gz +---- +==== * Include the extensions' *.vsix* binaries in the *che-code* image. + @@ -142,6 +154,6 @@ data: ---- + 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. +First, open the dashboard and navigate to the *Create Workspace* tab on the left 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. From 414a57b9c3073df58f8e89d0e4463e3bc8eadba0 Mon Sep 17 00:00:00 2001 From: Vitaliy Gulyy Date: Thu, 14 Nov 2024 21:12:16 +0200 Subject: [PATCH 13/17] docs: highlight samples with border Signed-off-by: Vitaliy Gulyy --- ...xtensions-for-microsoft-visual-studio-code.adoc | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/modules/administration-guide/pages/default-extensions-for-microsoft-visual-studio-code.adoc b/modules/administration-guide/pages/default-extensions-for-microsoft-visual-studio-code.adoc index 500092024e..66f8db4288 100644 --- a/modules/administration-guide/pages/default-extensions-for-microsoft-visual-studio-code.adoc +++ b/modules/administration-guide/pages/default-extensions-for-microsoft-visual-studio-code.adoc @@ -39,6 +39,7 @@ The easiest way is to put the extension binary to the Git repository and define 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 @@ -52,18 +53,22 @@ components: - 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 +-- +** specify a devfile command to download 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 @@ -91,6 +96,7 @@ events: postStart: - add-default-extensions ---- +==== + [WARNING] ==== @@ -114,6 +120,7 @@ Following steps will help you to add the extensions you need to the editor image + 2. Create a Dockerfile with following content. + +==== [source,] ---- # inherit che-incubator/che-code:latest @@ -127,17 +134,21 @@ 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 @@ -152,6 +163,7 @@ metadata: 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 side. From b18352c352cfd635f8290993101b1b237c7fba1e Mon Sep 17 00:00:00 2001 From: Vitaliy Gulyy Date: Fri, 15 Nov 2024 12:41:20 +0200 Subject: [PATCH 14/17] Update modules/administration-guide/pages/default-extensions-for-microsoft-visual-studio-code.adoc Co-authored-by: David Kwon --- .../default-extensions-for-microsoft-visual-studio-code.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/modules/administration-guide/pages/default-extensions-for-microsoft-visual-studio-code.adoc b/modules/administration-guide/pages/default-extensions-for-microsoft-visual-studio-code.adoc index 66f8db4288..5127ee051b 100644 --- a/modules/administration-guide/pages/default-extensions-for-microsoft-visual-studio-code.adoc +++ b/modules/administration-guide/pages/default-extensions-for-microsoft-visual-studio-code.adoc @@ -100,8 +100,8 @@ events: + [WARNING] ==== -It some cases *curl* may download *gzip* compressed file. This may make it impossible to install the extension. -To fix that try to save the file to *.vsix.gz* and then decompress it with *gunzip*. It will replace *.vsix.gz* with unpacked *.vsix* file. +In some cases *curl* may download a *gzip* compressed file. This may make it impossible to install the extension. +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. [source,yaml] ---- From 5d0d01bc8113ef89e67d9e2db7f2f4682403d9c3 Mon Sep 17 00:00:00 2001 From: Vitaliy Gulyy Date: Sun, 17 Nov 2024 15:12:07 +0200 Subject: [PATCH 15/17] Apply suggestions from code review Co-authored-by: Jana Vrbkova --- ...ions-for-microsoft-visual-studio-code.adoc | 44 ++++++++++--------- 1 file changed, 23 insertions(+), 21 deletions(-) diff --git a/modules/administration-guide/pages/default-extensions-for-microsoft-visual-studio-code.adoc b/modules/administration-guide/pages/default-extensions-for-microsoft-visual-studio-code.adoc index 5127ee051b..e08065550f 100644 --- a/modules/administration-guide/pages/default-extensions-for-microsoft-visual-studio-code.adoc +++ b/modules/administration-guide/pages/default-extensions-for-microsoft-visual-studio-code.adoc @@ -7,19 +7,15 @@ [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. +Default extensions are a pre-installed set of extensions, specified by putting the extension binary `.vsix` file path to the __DEFAULT_EXTENSIONS__ environment variable. -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. +After startup, the editor checks for this environment variable, and if it is specified, takes the path to the extensions and installs it in the background without disturbing the user. -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. +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. +You can specify several extensions separated by semicolon. [source,yaml] ---- @@ -27,17 +23,22 @@ It is possible to specify several extensions separated by semicolon. ---- ==== -Below you can find several examples how to add *.vsix* files to your workspace and how to define the DEFAULT_EXTENSIONS environment variable. +Read on to learn how to define the DEFAULT_EXTENSIONS environment variable with multiple examples of adding `.vsix` files to your workspace. .Procedure -This documentation describes three different ways to embed default .vsix extensions for your workspace. +There are three different ways to embed default `.vsix` extensions into your workspace: + +* 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. -* Put the extension binary to the source repository. +.Putting the extension binary into 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. +Putting the extension binary into the Git repository and defining the environment variable in the devfile is the easiest way to add default extensions to your workspace. +If the `extension.vsix` file exists in the repository root, you can set the __DEFAULT_EXTENSIONS__ for a tooling container. +.Procedure +* Specify __DEFAULT_EXTENSIONS__ in your `.devfile.yaml` as shown in the following example: + ==== [source,yaml] @@ -55,9 +56,9 @@ components: ---- ==== -* Use the Devfile *postStart* event to fetch extension binaries from the network. +.Using 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. +You can use cURL or GNU Wget to download extensions to your workspace. For that you need to: + -- @@ -66,7 +67,8 @@ For that you need to: ** define the __DEFAULT_EXTENSIONS__ environment variable in the Devfile -- + -The following sample demonstrates what should be added to the devfile to add two extensions. +.Procedure +* Add the values shown in the following example to the devfile: + ==== [source,yaml] @@ -110,9 +112,9 @@ gunzip /tmp/extension.vsix.gz ---- ==== -* Include the extensions' *.vsix* binaries in the *che-code* image. +.Including 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. +With default extensions bundled in the editor image along with the __DEFAULT_EXTENSIONS__ environment variable defined in a ConfigMap, you can apply the default extensions without changing the devfile. + Following steps will help you to add the extensions you need to the editor image. + @@ -167,5 +169,5 @@ data: + 5. Create a workspace using *yourname/che-code:next* image. First, open the dashboard and navigate to the *Create Workspace* tab on the left 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. +.. In the *Editor Selector* section, expand the *Use an Editor Definition* dropdown and set the editor URI to the *Editor Image*. +.. Create a workspace by clicking on any sample or by using a Git repository URL. From 723ef3e713e5ff769575ea10f38d673e1f64e5d0 Mon Sep 17 00:00:00 2001 From: Vitaliy Gulyy Date: Mon, 18 Nov 2024 13:01:07 +0200 Subject: [PATCH 16/17] Apply formatting Signed-off-by: Vitaliy Gulyy --- ...ions-for-microsoft-visual-studio-code.adoc | 39 ++++++++++--------- 1 file changed, 21 insertions(+), 18 deletions(-) diff --git a/modules/administration-guide/pages/default-extensions-for-microsoft-visual-studio-code.adoc b/modules/administration-guide/pages/default-extensions-for-microsoft-visual-studio-code.adoc index e08065550f..6bb760ea74 100644 --- a/modules/administration-guide/pages/default-extensions-for-microsoft-visual-studio-code.adoc +++ b/modules/administration-guide/pages/default-extensions-for-microsoft-visual-studio-code.adoc @@ -25,8 +25,6 @@ You can specify several extensions separated by semicolon. Read on to learn how to define the DEFAULT_EXTENSIONS environment variable with multiple examples of adding `.vsix` files to your workspace. -.Procedure - There are three different ways to embed default `.vsix` extensions into your workspace: * Put the extension binary into the source repository. @@ -34,9 +32,10 @@ There are three different ways to embed default `.vsix` extensions into your wor * Include the extensions' `.vsix` binaries in the `che-code` image. .Putting the extension binary into the source repository -+ + Putting the extension binary into the Git repository and defining the environment variable in the devfile is the easiest way to add default extensions to your workspace. If the `extension.vsix` file exists in the repository root, you can set the __DEFAULT_EXTENSIONS__ for a tooling container. + .Procedure * Specify __DEFAULT_EXTENSIONS__ in your `.devfile.yaml` as shown in the following example: + @@ -57,16 +56,16 @@ components: ==== .Using the devfile *postStart* event to fetch extension binaries from the network -+ + You can use cURL or GNU Wget to download extensions to your workspace. For that you need to: -+ + -- ** specify a devfile command to download 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 -- -+ + .Procedure * Add the values shown in the following example to the devfile: + @@ -113,14 +112,15 @@ gunzip /tmp/extension.vsix.gz ==== .Including the extensions `.vsix` binaries in the `che-code` image. -+ + With default extensions bundled in the editor image along with the __DEFAULT_EXTENSIONS__ environment variable defined in a ConfigMap, you can apply the default extensions without changing 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. + +.Procedure +* Create a directory and place one or several *.vsix* extensions in this directory. + +* Create a Dockerfile with following content. + ==== [source,] @@ -137,8 +137,8 @@ COPY --chmod=755 *.vsix /default-extensions/ RUN echo "cp -r /default-extensions /checode/" >> /entrypoint-init-container.sh ---- ==== -+ -3. Build the image and then push it to a registry. + +* Build the image and then push it to a registry. + ==== [,console] @@ -147,8 +147,8 @@ $ 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}. + +* 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] @@ -166,8 +166,11 @@ data: DEFAULT_EXTENSIONS: '/checode/default-extensions/extension1.vsix;/checode/default-extensions/extension2.vsix' ---- ==== -+ -5. Create a workspace using *yourname/che-code:next* image. + +* Create a workspace using *yourname/che-code:next* image. First, open the dashboard and navigate to the *Create Workspace* tab on the left side. ++ +-- .. In the *Editor Selector* section, expand the *Use an Editor Definition* dropdown and set the editor URI to the *Editor Image*. .. Create a workspace by clicking on any sample or by using a Git repository URL. +-- From 020c3584c671a477afe27827db715d6bd552443d Mon Sep 17 00:00:00 2001 From: Vitaliy Gulyy Date: Tue, 19 Nov 2024 11:45:14 +0200 Subject: [PATCH 17/17] Apply suggestions from code review Co-authored-by: Jana Vrbkova --- ...ions-for-microsoft-visual-studio-code.adoc | 30 +++++++++---------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/modules/administration-guide/pages/default-extensions-for-microsoft-visual-studio-code.adoc b/modules/administration-guide/pages/default-extensions-for-microsoft-visual-studio-code.adoc index 6bb760ea74..06e7692b5e 100644 --- a/modules/administration-guide/pages/default-extensions-for-microsoft-visual-studio-code.adoc +++ b/modules/administration-guide/pages/default-extensions-for-microsoft-visual-studio-code.adoc @@ -5,17 +5,17 @@ // :page-aliases: [id="visual-studio-code-default-extensions"] -= Configure default extensions += Configuring default extensions Default extensions are a pre-installed set of extensions, specified by putting the extension binary `.vsix` file path to the __DEFAULT_EXTENSIONS__ environment variable. After startup, the editor checks for this environment variable, and if it is specified, takes the path to the extensions and installs it in the background without disturbing the user. -Default extensions described in this documentation are useful for installing .vsix extensions by default from the editor level. +Configuring default extensions is useful for installing .vsix extensions from the editor level. [NOTE] ==== -You can specify several extensions separated by semicolon. +If you want to specify multiple extensions, separate them by semicolon. [source,yaml] ---- @@ -23,7 +23,7 @@ You can specify several extensions separated by semicolon. ---- ==== -Read on to learn how to define the DEFAULT_EXTENSIONS environment variable with multiple examples of adding `.vsix` files to your workspace. +Read on to learn how to define the DEFAULT_EXTENSIONS environment variable, including multiple examples of adding `.vsix` files to your workspace. There are three different ways to embed default `.vsix` extensions into your workspace: @@ -61,9 +61,9 @@ You can use cURL or GNU Wget to download extensions to your workspace. For that you need to: -- -** specify a devfile command to download 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 +* 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 @@ -101,7 +101,7 @@ events: + [WARNING] ==== -In some cases *curl* may download a *gzip* compressed file. This may make it impossible to install the extension. +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. [source,yaml] @@ -113,14 +113,14 @@ gunzip /tmp/extension.vsix.gz .Including the extensions `.vsix` binaries in the `che-code` image. -With default extensions bundled in the editor image along with the __DEFAULT_EXTENSIONS__ environment variable defined in a ConfigMap, you can apply the default extensions without changing the devfile. +With default extensions bundled in the editor image, and the __DEFAULT_EXTENSIONS__ environment variable defined in the ConfigMap, you can apply the default extensions without changing the devfile. -Following steps will help you to add the extensions you need to the editor image. +Following the steps below to add the extensions you need to the editor image. .Procedure -* Create a directory and place one or several *.vsix* extensions in this directory. +* Create a directory and place your selected `.vsix` extensions in this directory. -* Create a Dockerfile with following content. +* Create a Dockerfile with the following content: + ==== [source,] @@ -138,7 +138,7 @@ RUN echo "cp -r /default-extensions /checode/" >> /entrypoint-init-container.sh ---- ==== -* Build the image and then push it to a registry. +* Build the image and then push it to a registry: + ==== [,console] @@ -148,7 +148,7 @@ $ docker push yourname/che-code:next ---- ==== -* 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}. +* Add the new ConfigMap to 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] @@ -167,7 +167,7 @@ data: ---- ==== -* Create a workspace using *yourname/che-code:next* image. +* Create a workspace using `yourname/che-code:next` image. First, open the dashboard and navigate to the *Create Workspace* tab on the left side. + --