Quick start with Eclipse Che

This guide will run through creating a simple hello world devfile project using Eclipse Che. The purpose of this guide is to provide a practical introduction to those just starting out with devfiles.

Prerequisites

Eclipse Che 7.65.x
kubectl or oc
Access to a Kubernetes or OpenShift cluster

Procedure

Obtain access to Eclipse Che if you do not already have it, as an individual this can be done by setting up a local instance of Eclipse Che
- You can use minikube to run your cluster locally, follow these steps to get started
- An alternative is to use the Eclipse Che hosted by Red Hat, see the corresponding guide in Eclipse Che documentation if this method is used
For this quick start guide, we will create a simple hello world Express.js application
In Eclipse Che, create an empty workspace

Create the files which make up the simple hello world Express.js application

package.json file

package.json

{
    "name": "helloworld-devfile",
    "version": "1.0.0",
    "description": "",
    "main": "app.js",
    "type": "module",
    "dependencies": {
        "@types/express": "^4.17.17",
        "express": "^4.18.2"
    }
}

Application source code

app.js

import express from "express"


const PORT = 3000
const app = express()


app.get("/", (req, res) => {
    res.send("Hello world!")
})


app.listen(PORT, () => {
    console.log(`Listening on port ${PORT}..`)
})

Create a devfile with the filename .devfile.yaml. The devfile should be populated with content similar to the following
- The schemaVersion of the devfile can to set to the desired devfile specification version to use
  - It is recommended to use the latest release, currently 2.2.0
- The metadata.name field is the name of the workspace for the project
  .devfile.yaml
```
schemaVersion: 2.2.0
metadata:
  name: helloworld-example
```
Next, create the first component to serve as the dev environment for the project, for this use the container component with the name dev-tooling and the quay.io/devfile/universal-developer-image:latest image
- name is the identifier used to refer to the component
- image is the container image to use for the component, quay.io/devfile/universal-developer-image is the default development tooling image used by Eclipse Che with multiple programming languages supports (including Node.js).
  .devfile.yaml
```
 schemaVersion: 2.2.0
 metadata:
   name: helloworld-example
+components:
+  - name: dev-tooling
+    container:
+      image: quay.io/devfile/universal-developer-image:ubi8-latest
```

The dev-tooling container will host the expressjs app which listens on port 3000, define this port in the component by specifying an entry under endpoints

Each endpoint has at least a name to identify them and the targetPort to specify the port number to forward

.devfile.yaml

 schemaVersion: 2.2.0
 metadata:
   name: helloworld-example
 components:
   - name: dev-tooling
     container:
       image: quay.io/devfile/universal-developer-image:ubi8-latest
+      endpoints:
+        - name: http-3000
+          targetPort: 3000

Now that the dev-tooling container is defined, commands are useful to add in the IDE (the default is VS Code) some UI elements to guide developers during the development cycle. Define the command to install the dependencies needed to run the application (npm install)
- The id field identifies the command so that it can be referenced in events or composite commands.
- An exec command specifies explicit shell command(s) to run on a given component
- commandLine defines the shell command(s) to execute as part of that devfile command
- The group specifies what kind of command it is or if it is the default of its kind, isDefault
  Install command
```
commands:
  - id: install
    exec:
      commandLine: npm install
      component: dev-tooling
      workingDir: ${PROJECT_SOURCE}
      group:
        isDefault: true
        kind: build
```

Next, define the command to run the application (node app.js)

Run command

commands:
  - id: run
    exec:
      commandLine: node app.js
      component: dev-tooling
      workingDir: ${PROJECT_SOURCE}
      group:
        isDefault: true
        kind: run

Now the devfile is ready to be used to run the application with Eclipse Che

Complete Workspace Devfile

.devfile.yaml

schemaVersion: 2.2.0
metadata:
  name: helloworld-example
components:
  - name: dev-tooling
    container:
      image: quay.io/devfile/universal-developer-image:ubi8-latest
      endpoints:
        - name: http-3000
          targetPort: 3000
commands:
  - id: install
    exec:
      commandLine: npm install
      component: dev-tooling
      workingDir: ${PROJECT_SOURCE}
      group:
        isDefault: true
        kind: build
  - id: run
    exec:
      commandLine: node app.js
      component: dev-tooling
      workingDir: ${PROJECT_SOURCE}
      group:
        isDefault: true
        kind: run

Click 'Eclipse Che' in the bottom left corner, then select 'Eclipse Che: Restart Workspace from Local Devfile' to reload the workspace with the new devfile

Once the workspace has finished restarting, run the install command by opening the menu, open 'Terminal/Run Task', under the 'Run Task' menu open 'devfile/devfile: install', the task should open a terminal with the following

Output of running the 'install' command in Che

 *  Executing task: devfile: install 




added 67 packages, and audited 68 packages in 8s


7 packages are looking for funding
  run `npm fund` for details


found 0 vulnerabilities
npm notice 
npm notice New major version of npm available! 8.3.1 -> 9.6.5
npm notice Changelog: https://github.com/npm/cli/releases/tag/v9.6.5
npm notice Run npm install -g npm@9.6.5 to update!
npm notice 
 *  Terminal will be reused by tasks, press any key to close it.

Run the application with the run command by going through the same steps as install but under the 'Run Task' menu open 'devfile/devfile: run', the task should open
- The run command will execute until the user interrupts it, such as killing it with Ctrl-C
Output of running the 'run' command in Che
```
 *  Executing task: devfile: run 


Listening on port 3000..
```
Under the 'EXPLORER', expand the 'ENDPOINTS' panel and copy the http-3000 endpoint URL
Paste the endpoint URL in a new tab and the response should just show "Hello World!"
(Optional) Normally when creating a workspace it is recommended to use a sample under 'Select a Sample' from the embedded devfile registry to start your project, a similar devfile project workspace can be created using the 'Node.js Express Web Application' sample
Congratulations! You have written your first devfile project with Eclipse Che!

Devfile.io