Skip to content

Commit 7c82517

Browse files
vitaliy-guliydkwon17deerskindoll
authored
docs: default extension in visual studio code (#2819)
Signed-off-by: Vitaliy Gulyy <vgulyy@redhat.com> Co-authored-by: David Kwon <dakwon@redhat.com> Co-authored-by: Jana Vrbkova <jvrbkova@redhat.com>
1 parent 51f68eb commit 7c82517

File tree

3 files changed

+180
-1
lines changed

3 files changed

+180
-1
lines changed

‎modules/administration-guide/nav.adoc

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -101,9 +101,10 @@
101101
*** xref:enabling-fuse-for-all-workspaces.adoc[]
102102
* xref:managing-ide-extensions.adoc[]
103103
** xref:extensions-for-microsoft-visual-studio-code-open-source.adoc[]
104-
** xref:trusted-extensions-for-microsoft-visual-studio-code.adoc[]
105104
* xref:configuring-visual-studio-code.adoc[]
106105
** xref:configuring-single-and-multiroot-workspaces.adoc[]
106+
** xref:trusted-extensions-for-microsoft-visual-studio-code.adoc[]
107+
** xref:default-extensions-for-microsoft-visual-studio-code.adoc[]
107108
* xref:managing-workloads-using-the-che-server-api.adoc[]
108109
* xref:upgrading-che.adoc[]
109110
** xref:upgrading-the-chectl-management-tool.adoc[]

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

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,3 +10,5 @@
1010
Learn how to configure Visual Studio Code - Open Source ("Code - OSS").
1111

1212
* xref:configuring-single-and-multiroot-workspaces.adoc[]
13+
* xref:trusted-extensions-for-microsoft-visual-studio-code.adoc[]
14+
* xref:default-extensions-for-microsoft-visual-studio-code.adoc[]

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

Lines changed: 176 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,176 @@
1+
:_content-type: PROCEDURE
2+
:description: Configure default extensions
3+
:keywords: extensions, workspace
4+
:navtitle: Configure default extensions
5+
// :page-aliases:
6+
7+
[id="visual-studio-code-default-extensions"]
8+
= Configuring default extensions
9+
10+
Default extensions are a pre-installed set of extensions, specified by putting the extension binary `.vsix` file path to the __DEFAULT_EXTENSIONS__ environment variable.
11+
12+
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.
13+
14+
Configuring default extensions is useful for installing .vsix extensions from the editor level.
15+
16+
[NOTE]
17+
====
18+
If you want to specify multiple extensions, separate them by semicolon.
19+
20+
[source,yaml]
21+
----
22+
DEFAULT_EXTENSIONS='/projects/extension-1.vsix;/projects/extension-2.vsix'
23+
----
24+
====
25+
26+
Read on to learn how to define the DEFAULT_EXTENSIONS environment variable, including multiple examples of adding `.vsix` files to your workspace.
27+
28+
There are three different ways to embed default `.vsix` extensions into your workspace:
29+
30+
* Put the extension binary into the source repository.
31+
* Use the devfile `postStart` event to fetch extension binaries from the network.
32+
* Include the extensions' `.vsix` binaries in the `che-code` image.
33+
34+
.Putting the extension binary into the source repository
35+
36+
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.
37+
If the `extension.vsix` file exists in the repository root, you can set the __DEFAULT_EXTENSIONS__ for a tooling container.
38+
39+
.Procedure
40+
* Specify __DEFAULT_EXTENSIONS__ in your `.devfile.yaml` as shown in the following example:
41+
+
42+
====
43+
[source,yaml]
44+
----
45+
schemaVersion: 2.3.0
46+
metadata:
47+
generateName: example-project
48+
components:
49+
- name: tools
50+
container:
51+
image: quay.io/devfile/universal-developer-image:ubi8-latest
52+
env:
53+
- name: 'DEFAULT_EXTENSIONS'
54+
value: '/projects/example-project/extension.vsix'
55+
----
56+
====
57+
58+
.Using the devfile *postStart* event to fetch extension binaries from the network
59+
60+
You can use cURL or GNU Wget to download extensions to your workspace.
61+
For that you need to:
62+
63+
--
64+
* specify a devfile command to download extensions to your workpace
65+
* add a `postStart` event to run the command on workspace startup
66+
* define the __DEFAULT_EXTENSIONS__ environment variable in the devfile
67+
--
68+
69+
.Procedure
70+
* Add the values shown in the following example to the devfile:
71+
+
72+
====
73+
[source,yaml]
74+
----
75+
schemaVersion: 2.3.0
76+
metadata:
77+
generateName: example-project
78+
components:
79+
- name: tools
80+
container:
81+
image: quay.io/devfile/universal-developer-image:ubi8-latest
82+
env:
83+
- name: DEFAULT_EXTENSIONS
84+
value: '/tmp/extension-1.vsix;/tmp/extension-2.vsix'
85+
86+
commands:
87+
- id: add-default-extensions
88+
exec:
89+
# name of the tooling container
90+
component: tools
91+
# download several extensions using curl
92+
commandLine: |
93+
curl https://.../extension-1.vsix --location -o /tmp/extension-1.vsix
94+
curl https://.../extension-2.vsix --location -o /tmp/extension-2.vsix
95+
96+
events:
97+
postStart:
98+
- add-default-extensions
99+
----
100+
====
101+
+
102+
[WARNING]
103+
====
104+
In some cases curl may download a `.gzip` compressed file. This might make installing the extension impossible.
105+
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.
106+
107+
[source,yaml]
108+
----
109+
curl https://some-extension-url --location -o /tmp/extension.vsix.gz
110+
gunzip /tmp/extension.vsix.gz
111+
----
112+
====
113+
114+
.Including the extensions `.vsix` binaries in the `che-code` image.
115+
116+
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.
117+
118+
Following the steps below to add the extensions you need to the editor image.
119+
120+
.Procedure
121+
* Create a directory and place your selected `.vsix` extensions in this directory.
122+
123+
* Create a Dockerfile with the following content:
124+
+
125+
====
126+
[source,]
127+
----
128+
# inherit che-incubator/che-code:latest
129+
FROM quay.io/che-incubator/che-code:latest
130+
USER 0
131+
132+
# copy all .vsix files to /default-extensions directory
133+
RUN mkdir --mode=775 /default-extensions
134+
COPY --chmod=755 *.vsix /default-extensions/
135+
136+
# add instruction to the script to copy default extensions to the working container
137+
RUN echo "cp -r /default-extensions /checode/" >> /entrypoint-init-container.sh
138+
----
139+
====
140+
141+
* Build the image and then push it to a registry:
142+
+
143+
====
144+
[,console]
145+
----
146+
$ docker build -t yourname/che-code:next .
147+
$ docker push yourname/che-code:next
148+
----
149+
====
150+
151+
* 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}.
152+
+
153+
====
154+
[source,yaml]
155+
----
156+
kind: ConfigMap
157+
apiVersion: v1
158+
metadata:
159+
name: vscode-default-extensions
160+
labels:
161+
controller.devfile.io/mount-to-devworkspace: 'true'
162+
controller.devfile.io/watch-configmap: 'true'
163+
annotations:
164+
controller.devfile.io/mount-as: env
165+
data:
166+
DEFAULT_EXTENSIONS: '/checode/default-extensions/extension1.vsix;/checode/default-extensions/extension2.vsix'
167+
----
168+
====
169+
170+
* Create a workspace using `yourname/che-code:next` image.
171+
First, open the dashboard and navigate to the *Create Workspace* tab on the left side.
172+
+
173+
--
174+
.. In the *Editor Selector* section, expand the *Use an Editor Definition* dropdown and set the editor URI to the *Editor Image*.
175+
.. Create a workspace by clicking on any sample or by using a Git repository URL.
176+
--

0 commit comments

Comments
 (0)