How to define a custom IDE in a devfile

[Deel96]

Is there a current documentation for running a custom IDE?
I only found an old version:
https://www.eclipse.org/che/docs/che-7/end-user-guide/support-for-theia-based-ides/

I created an own devfile like mentioned in the docs with a reference URL. The editor auto insertes a pastebin url, which looks pretty empty:
https://pastebin.com/raw/kYprWiNB

So I used the file from the docs an hosted my own file on pastebin. https://pastebin.com/raw/4YdE6DiT
When starting the workspace I get the error
Workspace emfcloud failed to start. Failed to start the workspace emfcloud, reason: Internal Server Error occurred, error time

Starting in verbose mode gives me the same. The dockerimage of the ide works locally without problems.

Possible reasons I found:

• For me it's not 100% clear how the specify the image url, when it's not a quay.io URL.
  I tried docker.io, registry.hub.docker.com but always get the error above, maybe the issues lays somewhere else?

At the moment I have a docker hub image from: https://hub.docker.com/repository/docker/browork/ide linked as registry.hub.docker.com/browork/ide

If I remove my changes

• type: cheEditor
  reference: 'https://pastebin.com/raw/QFYWXJc0'

the workspace starts without a problem.
If just use the 2 lines as a devfile I get the error above.

I'm testing this at the moment on Codeready Workspaces, but the issue above should be independent from it.

My devfile file:

metadata:
  name: emfcloud
projects:
  - name: nodejs-web-app
    source:
      location: 'https://codeready-codeready-workspaces-operator.apps.sandbox.x8i5.p1.openshiftapps.com/devfile-registry/resources/nodejs-nodejs-web-app-master.zip'
      type: zip
components:
  - type: cheEditor
    reference: 'https://pastebin.com/raw/QFYWXJc0'
  - id: vscode/typescript-language-features/latest
    type: chePlugin
  - id: ms-vscode/node-debug2/latest
    type: chePlugin
  - mountSources: true
    endpoints:
      - name: nodejs
        port: 3100
    memoryLimit: 512Mi
    type: dockerimage
    alias: nodejs
    image: 'registry.redhat.io/codeready-workspaces/plugin-java8-rhel8@sha256:4845d417584375398127969c06e42ad41cb22db21329eaf3fdf8ee99ed723b2b'
commands:
  - name: 1. Run the web app (and download dependencies)
    actions:
      - workdir: '${CHE_PROJECTS_ROOT}/nodejs-web-app/app'
        type: exec
        command: npm install; nodemon app.js
        component: nodejs
  - name: 2. Download dependencies
    actions:
      - workdir: '${CHE_PROJECTS_ROOT}/nodejs-web-app/app'
        type: exec
        command: npm install
        component: nodejs
  - name: 3. Run the web app
    actions:
      - workdir: '${CHE_PROJECTS_ROOT}/nodejs-web-app/app'
        type: exec
        command: nodemon app.js
        component: nodejs
  - name: 4. Run the web app (debugging enabled)
    actions:
      - workdir: '${CHE_PROJECTS_ROOT}/nodejs-web-app/app'
        type: exec
        command: nodemon --inspect app.js
        component: nodejs
  - name: 5. Stop the web app
    actions:
      - type: exec
        command: 'node_server_pids=$(pgrep -fx ''.*nodemon (--inspect )?app.js'' | tr "\\n" " ") && echo "Stopping node server with PIDs: ${node_server_pids}" && kill -15 ${node_server_pids} &>/dev/null && echo ''Done.'''
        component: nodejs
  - name: Attach remote debugger
    actions:
      - referenceContent: |
          {
            "version": "0.2.0",
            "configurations": [
              {
                "type": "node",
                "request": "attach",
                "name": "Attach to Remote",
                "address": "localhost",
                "port": 9229,
                "localRoot": "${workspaceFolder}",
                "remoteRoot": "${workspaceFolder}"
              }
            ]
          }
        type: vscode-launch

The dockerfile I use

FROM ubuntu:18.04 AS cpp-theia-base
 
ENV DEBIAN_FRONTEND noninteractive
 
RUN apt-get update && \
	apt-get upgrade -y && \
	apt-get install -y default-jdk maven && \
	apt-get install wget build-essential cmake libopenblas-dev gnupg curl make git g++-multilib clangd-10 gdb -y
 
RUN update-alternatives --install /usr/bin/clangd clangd /usr/bin/clangd-10 100
 
RUN curl -fsSL https://deb.nodesource.com/setup_10.x | bash - && \
	apt-get install nodejs -y && \
	npm install -g yarn
 
# Make readable for root only
RUN chmod -R 750 /var/run/
 
RUN useradd -ms /bin/bash theia
 
WORKDIR /coffee-editor
 
COPY --chown=theia:theia . .
USER theia
 
ENV test=2
RUN ./run.sh -bcf 
 
WORKDIR /coffee-editor/web/browser-app
 
EXPOSE 3000
 
CMD yarn start --hostname 0.0.0.0

[azatsarynnyy]

Hello @Deel96,
The docs link you're referring to is an old one. See:

Just choose a stable version from the dropdown menu. Or follow this direct link https://www.eclipse.org/che/docs/stable/end-user-guide/selecting-a-workspace-ide/
There are two sub-chapters that describe two possible ways to provide a custom IDE Devfile:

• through the che-editor URL parameter
• through the che-editor.yaml file

I hope that helps you.

[Deel96]

Hi @azatsarynnyy,
Thank your for your reply. I missunderstood the new documentation that you can only use predefined IDEs. Later my usecase is described :https://www.eclipse.org/che/docs/stable/end-user-guide/specifying-an-in-browser-ide-for-a-git-repository-by-using-che-editor.yaml/#using-a-web-reference-for-your-ide_che

Using a che-editor.yaml file seems like the easiest way to get started:

1. create a che-editor.yaml file inside the project
2. add this to the che-editor.yaml file

reference: https://someaccessibleUrl/referenced-che-editor.yaml # mandatory
override:                                              # optional
  containers:
      - name: theia-ide
        memoryLimit: 1280Mi

It's not clear to me if the reference Url should point to the vanilla che-editor.yaml file or to my own like specified later in the documentation:https://www.eclipse.org/che/docs/stable/end-user-guide/specifying-an-in-browser-ide-for-a-git-repository-by-using-che-editor.yaml/#using-an-embedded-editor-ddefinition-for-your-ide_che

I tried to create a project which has the corresponding files:
https://github.com/Deel96/editor

For simplicity I also have the referenced yaml file in the repo which i include via raw.github.com

If I open the repo via QuickAdd in Che the github repo opens with vanilla theia-che.

[azatsarynnyy]

@Deel96
I'm not sure about the way with using the reference:.
I can recommend putting the editor Devfile to .che/che-editor.yaml directly, without the reference: field.
See an example here https://github.com/azatsarynnyy/java-spring-petclinic/blob/theia-test/.che/che-editor.yaml

Just provide your images in:

• https://github.com/azatsarynnyy/java-spring-petclinic/blob/cf26cfe40c52026c5ebe2021b032774b96f81801/.che/che-editor.yaml#L15
• https://github.com/azatsarynnyy/java-spring-petclinic/blob/cf26cfe40c52026c5ebe2021b032774b96f81801/.che/che-editor.yaml#L143

[Deel96]

@azatsarynnyy
Ok, I'll try to put everything in one file.
You mentioned two places for images.
Line 15 is the image of the IDE which I tried running locally?
What kind of image is needed for line 143?

If I use my che-editor file without reference (everything in the che-editor.yaml file) the workspace still opens with che-theia.
Maybe Quick Add is the wrong way to do it.

At least that's the devfile I can see in eclipse che after the quick add

apiVersion: 1.0.0
metadata:
  name: editor295x
projects:
  - name: editor
    source:
      location: 'https://github.com/Deel96/editor.git'
      type: github
components:
  - id: redhat/vscode-xml/latest
    type: chePlugin
  - id: redhat/vscode-yaml/latest
    type: chePlugin

Seems like nothing of my che-editor.yaml has been used. If I change the yaml file to the example your provided no components get injected and only the github source is inside the devfile on eclipse che.

apiVersion: 1.0.0
metadata:
  name: editor-testingndju
projects:
  - name: editor-testing
    source:
      location: 'https://github.com/Deel96/editor-testing.git'
      type: github

[azatsarynnyy]

What kind of image is needed for line 143?

you can keep it the same as it's in your example here https://github.com/Deel96/editor/blob/d66ef4655c015432ae25df348e8da110254250e8/.che/che-editor.yaml#L31

@Deel96 I've just noticed the version of your Devfile is apiVersion: 1.0.0

I wonder what Che version you use? Because all the examples I provided and the docs are related to the Devfile v.2

[Deel96]

@azatsarynnyy

You're right, I changed it to version 2. Until now I used the codereadyworkspace because I had problems setting che up locally.

With a local deployment with version 7.52 on OpenShift Local. I noticed that che doesn't find the devfile. Checking other repos suggests that the yamlfile has to be in the root directory with the name "devfile.yaml".

But I guess the devfile is for everything dispite the IDE.

But I also noticed that the che-editor.yaml seems not to be taken into account at all.
If I use the example with che-idea: https://github.com/che-samples/gradle-demo-project/blob/devfilev2/.che/che-editor.yaml
I still get che-theia.
I also found your issue about that: #21639

Is there a workaround to force another IDE to be used? I guess the bug also is present on other platforms like minikube?

[azatsarynnyy]

@Deel96
yes, you right, there's a bug with picking up .che/che-editor.yaml file.
There's one more option. You can provide che-editor URL parameter pointing to the editor Devfile.
https://<che_fqdn>#<git_repository_url>?che-editor=<editor_key>

The <editor_key> can be an editor ID as it's specified in the plug-in registry, e.g.: https://www.eclipse.org/che/docs/stable/end-user-guide/url-parameter-for-the-workspace-ide/
Also, the <editor_key> can be a link to che-editor.yaml file (e.g. gist), but without the first inline: section.

[Deel96]

@azatsarynnyy

Selecting an ide via url with the editor_key works for me.
What I didn't manage to get working is with providing a url to the che-editor.yaml file.

Example:
https://<che_fqdn>#https://github.com/Deel96/editor?che-editor=https://gist.githubusercontent.com/Deel96/1da10f28232ace4e3471818942711723/raw/d176c937c8b8bd8eefe01512e4ff7754f91fd591/che-editor.yaml

Doing so I get following error:

Failed to create the workspace
Failed to request factory resolver: Error occurred during creation a workspace from devfile located at `https://github.com/Deel96`. Cause: Neither of `apiVersion` or `schemaVersion` found. This is not a valid devfile.

This also happens if I just do
https://<che_fqdn>#https://github.com/Deel96

Seems like a devfile has to be present in the root folder anyway?

[azatsarynnyy]

@Deel96 if .che/che-editor.yaml is provided with the sources, the entire content should be wrapped into the inline: section.
https://www.eclipse.org/che/docs/stable/end-user-guide/specifying-an-in-browser-ide-for-a-git-repository-by-using-che-editor.yaml/#using-an-embedded-editor-ddefinition-for-your-ide_che

So in this editor Devfile https://github.com/Deel96/editor/blob/main/.che/che-editor.yaml
you need to wrap the content into the top-level inline:.
Most likely, that's the reason why Che says

Cause: Neither of apiVersion or schemaVersion found. This is not a valid devfile.

[Deel96]

@azatsarynnyy
Ah okay, I missunderstood you above where you said I have to provide it without inline.

Since .che/che-editor.yaml isn't applied anyways at the moment, I removed the folder for now and I will provide che-editor.yaml via an URL parameter from a gist.
I also removed the devfile.yaml on the rootlevel for now since I couldn't make the error go away.

When using my custom che-editor.yaml file I get now the following error about my theia-ide (my custom ide):

Container theia-ide has state ImagePullBackOff

used URL : https://192.168.59.108.nip.io/dashboard/#https://github.com/Deel96/editor?che-editor=https://gist.githubusercontent.com/Deel96/1da10f28232ace4e3471818942711723/raw/10da68f57738e32fbe9c18b2795e5e9af8f044b0/che-editor.yaml

I get the same error if I try to use the for example che-idea:

https://192.168.59.108.nip.io/#https://github.com/Deel96/editor?che-editor=che-incubator/che-idea/latest

Failed to open the workspace
Init Container che-idea-injector has state ImagePullBackOff

editorkey = che-theia/latest

Works

[azatsarynnyy]

Container theia-ide has state ImagePullBackOff

@Deel96 can you check the workspace pod's events? There should be more details on the exact problem.
Often, it happens because an image can't be downloaded within the default timeout.

On my local cluster, I usually pre-download the large images "by hand". E.g.:

• eval $(minikube -p minikube docker-env)
• docker pull my-large-image

[Deel96]

@azatsarynnyy
That also what I assumed. My image is pretty big (3gb).
Can you tell me how I access the workspace pod's event?

Prefetching "worked". I now get a 404 after the workspace started, but that's probably because of my ide image.
After my research the ide should expose the ide on port 3100. Is there something else I have to consider?

[azatsarynnyy]

After my research the ide should expose the ide on port 3100

in Che-Theia, it's specified by the THEIA_PORT environment variable
https://github.com/eclipse-che/che-theia/blob/f2d0d9813e8cbbd35919efa8c65dbcb213bfe5f8/dockerfiles/theia/src/entrypoint.sh#L38

[Deel96]

For documentation in case someone in the future reads this:
I exposed my IDE on port 3100 (on codeside and in the che-editor.yaml file).
The frontend is accessible but now I face the issue that the hostname (https//cheurl/workspacef815da4f8af8498b/theia-ide/3100/#/folder) is not known upfront because the url contains a hash.

For simplicity I have my client and server part inside one container.
I guess the solution might be:
1: opening also the port of the api server
2: injecting the "dynamic" url into the frontend -> That is the problem I face atm

[azatsarynnyy]

Can you tell me how I access the workspace pod's event?

I'm using the OpenShift Console. It is also possible with kubectl/oc get events command.

... because the url contains a hash

Theia uses the URL fragment for providing the folder to open.

The "dynamic" URL shouldn't be a problem, as I understand it. The frontend knows what backend URL to request based on the URL of the frontend page itself.

This code from upstream Theia may help https://github.com/eclipse-theia/theia/blob/master/packages/core/src/browser/endpoint.ts

[Deel96]

I'm using the OpenShift Console. It is also possible with kubectl/oc get events command.
This gives me:

5m39s Normal BackOff pod/workspaced8273c46efad4604-587495468c-f9p6t Back-off pulling image "docker.io/browork/ide:latest"

Gave the same informations but prepulling the images fixed it (see above).

---

Regarding the issue with the "localhost" URL. I think the cause lays somewhere else.
Edit: I'm sure its not a URL problem. Accessing the application from another machine also works, so the localhost things are all container internaly.

I published the same image on an "alternative solution for workspaces", where everything works as expected.
I noticed there that there is something different about the user.

In my dockerfile I create the user "theia", which starts the serverside components.

RUN useradd -ms /bin/bash theia
....
USER theia
...
build.sh
....
CMD yarn start

Below you can see what gets printed out from the theia terminal integrated in the frontend:
Other solution

$ whoami
theia
$ groups
theia
$ groups root
root : root
$ groups theia
theia : theia
$ groups $USER
theia
$ id -Gn
theia
$ id -Gn $USER
theia
$ echo $USER
 
$ id -u $USER
1000

This is what I get on the eclipse-che instance (same image as above):

$ whoami
whoami: cannot find name for user ID 1234
$ groups
root groups: cannot find name for group ID 1234
1234
$ groups root
root : root
$ groups theia
theia : theia
$ groups $USER
root groups: cannot find name for group ID 1234
1234
$ id -Gn
root id: cannot find name for group ID 1234
1234
$ id -Gn $USER
root id: cannot find name for group ID 1234
1234
$ echo $USER

$ id -u $USER
1234

First I thought it has something to do with the che-machine-exec container, but there is a uid of 12345 specified.
https://github.com/eclipse-che/che-machine-exec/blob/main/build/dockerfiles/Dockerfile#L18

Inside the logs of the "theia-ide" container inside the user1-che pod I see many errors because of missing permissions for folder creations.
I guess thats the reson why my backend services inside the container fail to start, because it works on the other solution where another user (theia) is used.

My question now is: how can I change the user from 1234 to another one?
Or is there something different I can/should try?

[azatsarynnyy]

how can I change the user from 1234 to another one?

I'm not sure I can help with that one. Maybe, building a custom image...

[Deel96]

how can I change the user from 1234 to another one?

I'm not sure I can help with that one. Maybe, building a custom image...

The image I use is a custom image. Changing the ownership of the files inside the dockerfile to uid 1234 didn't helped.

For more context on the other solution: I have a helm chart where I have to provide the userid. When I match it to the id I get from creating the "theia" user (id 1000) it works as expected.

I also noticed that the container is started with uid 1234 from kubernetes/minikube.

If I start the container inside minikube manually (eval $(minikube docker-env)) with docker run -p 3100:3100 localhost:5000/ide it works as expected from the ip of minikube.

[Deel96]

Okay I found the problem. 512 MB for the container I took from vanilla che-theia was not enough for my custom ide since it also contains language servers. Sadly no errors pointed me this way.
Maybe showing that a container is running close to its allowed ressources may be a nice feature.
@azatsarynnyy Thank you so much for the help. I learned a lot about che in this issue and while debugging the problem.
I have some more questions, but these are out of scope of this ticket.

Best Regards

[azatsarynnyy]

Okay I found the problem. 512 MB for the container I took from vanilla che-theia was not enough for my custom ide since it also contains language servers.

@Deel96 I'm glad you were able to figure out the root cause of the problem.

Sadly no errors pointed me this way.
Maybe showing that a container is running close to its allowed ressources may be a nice feature.

I agree that's a problem. That's why Che-Theia and Che-Code editors include the Resource Monitor plug-in that displays the info about the cluster resources consumption. We also have some plans for improvements to that plug-in: #20809, #21624.
For a custom IDE, I think only a cluster console is helpful.

I have some more questions, but these are out of scope of this ticket.

Feel free to ask the questions you have in the issues, mattermost channel, or on the community calls.

[Deel96]

@ashumilova
As a next step I looked into exposing a sidecar container to the internet like many examples do (e.g. Nodejs stack which exposes the api ).

I am a bit confused of the combination of the devfile and the che-editor file.

With the che-editor file I'm able to use a custom IDE.
e.g.
https://192.168.49.2.nip.io/dashboard/#https://github.com/Deel96/editor?che-editor=https://gist.githubusercontent.com/Deel96/daae1b9c7ac5aa150db0e96313c84a45/raw/5092691341a8435d14903f3cf369155d1b7ee90b/che-editor.yaml

From my editor repo which has no devfile. On startup I also get the message that no devfile could be found so the default configuration is used:

My question now is where do I specify for example a tools container with nodejs which should run an internally and publicly exposed api.
If I copy paste the devfile from the nodejs example into my repo and start the workspace like before with the url parameter I get vanilla che-theia:

Notice that the following link is on my editor-testing repo with the same content, just added with a devfile.

https://192.168.49.2.nip.io/dashboard/#https://github.com/Deel96/editor-testing?che-editor=https://gist.githubusercontent.com/Deel96/daae1b9c7ac5aa150db0e96313c84a45/raw/5092691341a8435d14903f3cf369155d1b7ee90b/che-editor.yaml

So I guess I have to add this also to the che-editor file?
What I find a bit strange is that if I look at the devfile of the created workspace, its pretty empty:

But on workspace restart che manages to start the workspace with the right ide.
The devfile in the description of the nodejs example is the same thing listed as in the devfile of the repo.

Adding the nodejs/redhat universal image to the che-editor.yaml works as expected.
Even the exposing of the nodejs api works out of the box.
I noticed that the urls for the sidecar containers can be derived from the normal url.

IDE on
https://192.168.49.2.nip.io/workspaced381305089e34ab0/theia-ide/3100

First sidecar/container of the devfile which is exposed will be exposed here:
https://workspaced381305089e34ab0-1.192.168.49.2.nip.io

With that it is possible to get access to the sidecar containers without haven the port extension (which would

TLDR: To specify a workspace I either use devfile.yaml or in che-editor.yaml (via .che or via url). But if I specify both the devfile wins?

[azatsarynnyy]

@Deel96 I'm not sure I understand your question correctly, but I'll try to answer )
There are several types of CRDs (Custom Resource Definitions) used for running Eclipse Che.

A project Devfile is stored in the DevWorkspace CRD and an editor's Devfile is stored in the DevWorkspaceTemplate CRD.
Che Dashboard shows only the project's Devfile. But not an editor's Devfile. That's why you don't see your che-editor.yaml in the Dashboard.

[Deel96]

Hi @azatsarynnyy My question at the end is basicly if it's possible to combine a devfile.yaml and a che-editor.yaml file.
In my experience the che-editor file is omitted if a devfile is present.
To get a custom sidecar container with a custom ide I had to put everything inside che-editor.

I thought that I would need a devfile.yaml for the workspace and che-editor.yaml file for the ide.

Is my impression wrong or do you either use che-editor or devfile.yaml?

[azatsarynnyy]

@Deel96 recently, I've noticed there's a problem that .che/che-editor.yaml is ignored by Che. I'm not sure in what Che version it was introduced. I've reported a corresponding GitHub issue #21639.
Probably, you ran into the same problem.
As a workaround, I'm using the ?che-editor URL parameter instead of the .che/che-editor.yaml file.

[davidxwwang]

@azatsarynnyy @Deel96 thanks for your great answers and discuss！but l also have a lot questions:
(1) if l want use my IDE(not the default one), it only need replace someone like https://github.com/azatsarynnyy/java-spring-petclinic/blob/cf26cfe40c52026c5ebe2021b032774b96f81801/.che/che-editor.yaml#L15 to my IDE image based on theia and the quay.io/eclipse/che-theia-endpoint-runtime-binary:next , does something else need do?
(2) the default theia use port 3000, but the che-theia user port 3100, should l do something for the export port warp or do nothing?
(3) which statement tell che use self customed IDE, eg: https://github.com/azatsarynnyy/java-spring-petclinic/blob/cf26cfe40c52026c5ebe2021b032774b96f81801/.che/che-editor.yaml#L15
(4) if user define the che-editor or user url like https://192.168.59.108.nip.io/dashboard/#https://github.com/Deel96/editor?che-editor=https://gist.githubusercontent.com/Deel96/1da10f28232ace4e3471818942711723/raw/10da68f57738e32fbe9c18b2795e5e9af8f044b0/che-editor.yaml how che-theia invokes the custom IDE(not the default one), **how it works,**thanks!

[azatsarynnyy]

@davidxwwang
(1) - yes, it should be enough in most the cases
(2) - you should expose the port your Theia editor is listening to. For Che-Theia, it's set here
(3) - there are a couple of options: che-editor URL parameter or .che/che-editor.yaml file in the repo. See more details in the docs here
(4) - when you start a Che Workspace, Che looks for a custom editor definition defined in the places mentioned in (3).
Then, the custom editor Devfile becomes a part of the entire DevWorkspace custom resource definition used by the DevWorkspace Operator to deploy all the needed resources to a cluster. The endpoint with type: main is used for opening an IDE.