To quickly and easily configure a Che workspace, use a devfile. For an introduction to devfiles and instructions for their use, see below.

What is a devfile

A devfile is a file that describes and define a development environment:

  • the source code

  • the development components (browser IDE tools and application runtimes)

  • a list of pre-defined commands

  • projects to clone

Devfiles are YAML files that Che consumes and transforms into a cloud workspace composed of multiple containers. The devfile can be saved in the root folder of a Git repository, a feature branch of a Git repository, a publicly accessible destination, or as a separate, locally stored artifact.

When creating a workspace, Che uses that definition to initiate everything and run all the containers for the required tools and application runtimes. Che also mounts file-system volumes to make source code available to the workspace.

Devfiles can be versioned with the project source code. When there is a need for a workspace to fix an old maintenance branch, the project devfile provides a definition of the workspace with the tools and the exact dependencies to start working on the old branch. Use it to instantiate workspaces on demand.

Che maintains the devfile up-to-date with the tools used in the workspace:

  • Projects of the workspace (path, Git location, branch)

  • Commands to perform daily tasks (build, run, test, debug)

  • Runtime environment (container images to run the application)

  • Che-Theia plug-ins with tools, IDE features, and helpers that a developer would use in the workspace (Git, Java support, Sonarlint, Pull Request)

Disambiguation between stacks and devfiles

This section describes differences between stacks in Che 6.x and devfiles in Che 7.3

Starting with Che 7.3:

  • A stack is a pre-configured Che workspace.

  • A devfile is a configuration YAML file that Che consumes and transforms in a cloud workspace composed of multiple containers.

In Che 6.x, stacks were defined by a stacks.json file that was included with the che server. In contrast, in Che 7.3, the stacks.json file does not exist. Instead, a stack is defined in the devfile registry, which is a separate service. Every single devfile in the registry corresponds to a stack.

Note that in Che 6.x, stacks and workspaces were defined using two different formats. However, with Che 7.3, the devfile format is used to define both. Nevertheless, a user opening the user dashboard does not notice any difference: in Che 7.3, a list of stacks is still present to choose from as a starting point to create a workspace.

Creating a workspace from the default branch of a Git repository

A Che workspace can be created by pointing to a devfile that is stored in a Git source repository. The Che instance then uses the discovered devfile.yaml file to build a workspace using the /f?url= API.

Prerequisites
Procedure

Run the workspace by opening the following URL: http(s)://che-host:che-port/f?url=https://<GitRepository>

Example
https://che.openshift.io/f?url=https://github.com/eclipse/che

Creating a workspace from a feature branch of a Git repository

A Che workspace can be created by pointing to devfile that is stored in a Git source repository on a feature branch of the user’s choice. The Che instance then uses the discovered devfile to build a workspace.

Prerequisites
  • A running instance of Eclipse Che. To install an instance of Eclipse Che, see Che quick-starts.

  • The devfile.yaml file in the root folder of a Git repository on a specific branch of the user’s choice available over HTTPS. See Making a workspace portable using a devfile for detailed information about creating and using devfiles.

Procedure

Execute the workspace by opening the following URL: http(s)://che-host:che-port/f?url=<GitHubBranch>

Example

Use following URL format to open an experimental quarkus-quickstarts branch hosted on che.openshift.io.

https://che.openshift.io/f?url=https://github.com/maxandersen/quarkus-quickstarts/tree/che

Creating a workspace from a publicly accessible standalone devfile using HTTP

A workspace can be created using a devfile, the URL of which is pointing to the raw content of the devfile. The Che instance then uses the discovered devfile to build a workspace.

Prerequisites
Procedure
  1. Execute the workspace by opening the following URL: http(s)://che-host:che-port/f?url=https://<yourhosturl>/devfile.yaml

Example
https://che.openshift.io/f?url=https://gist.githubusercontent.com/themr0c/ef8e59a162748a8be07e900b6401e6a8/raw/8802c20743cde712bbc822521463359a60d1f7a9/devfile.yaml

Overriding devfile values using factory parameters

Values in the following sections of a remote devfile can be overridden using specially constructed additional factory parameters:

  • apiVersion

  • metadata

  • projects

  • attributes

Prerequisites
Procedure
  1. Open the workspace by navigating to the following URL: http(s)://che-host:che-port/f?url=https://<hostURL>/devfile.yaml&override.<parameter.path>=<value>

Example of overriding the generateName property

Consider the following initial devfile:

---
apiVersion: 1.0.0
metadata:
  generateName: golang-
projects:
...

To add or override generateName value, the following factory URL can be used:

https://che.openshift.io/f?url=https://gist.githubusercontent.com/themr0c/ef8e59a162748a8be07e900b6401e6a8/raw/8802c20743cde712bbc822521463359a60d1f7a9/devfile.yaml&override.metadata.generateName=myprefix

The resulting workspace will have the following devfile model:

---
apiVersion: 1.0.0
metadata:
  generateName: myprefix
projects:
...
Example of overriding project source branch property

Consider the following initial devfile:

---
apiVersion: 1.0.0
metadata:
  generateName: java-mysql-
projects:
  - name: web-java-spring-petclinic
    source:
      type: git
      location: "https://github.com/spring-projects/spring-petclinic.git"
...

To add or override source branch value, the following factory URL can be used:

https://che.openshift.io/f?url=https://gist.githubusercontent.com/themr0c/ef8e59a162748a8be07e900b6401e6a8/raw/8802c20743cde712bbc822521463359a60d1f7a9/devfile.yaml&override.projects.web-java-spring-petclinic.source.branch=1.0.x

The resulting workspace will have the following devfile model:

apiVersion: 1.0.0
metadata:
  generateName: java-mysql-
projects:
  - name: web-java-spring-petclinic
    source:
      type: git
      location: "https://github.com/spring-projects/spring-petclinic.git"
      branch: 1.0.x
...
Example of overriding or creating an attribute value

Consider the following initial devfile:

---
apiVersion: 1.0.0
metadata:
  generateName: golang-
attributes:
   persistVolumes: false
projects:
...

To add or override persistVolumes attribute value, the following factory URL can be used:

https://che.openshift.io/f?url=https://gist.githubusercontent.com/themr0c/ef8e59a162748a8be07e900b6401e6a8/raw/8802c20743cde712bbc822521463359a60d1f7a9/devfile.yaml&override.attributes.persistVolumes=true

The resulting workspace will have the following devfile model:

---
apiVersion: 1.0.0
metadata:
  generateName: golang-
attributes:
   persistVolumes: true
projects:
...

When overriding attributes, everything that follows the attributes keyword treat as an attribute name, so it’s possible to use dot-separated names:

https://che.openshift.io/f?url=https://gist.githubusercontent.com/themr0c/ef8e59a162748a8be07e900b6401e6a8/raw/8802c20743cde712bbc822521463359a60d1f7a9/devfile.yaml&override.attributes.dot.name.format.attribute=true

The resulting workspace will have the following devfile model:

---
apiVersion: 1.0.0
metadata:
  generateName: golang-
attributes:
   dot.name.format.attribute: true
projects:
...

Creating a workspace using chectl and a local devfile

A Che workspace can be created by pointing the chectl tool to a locally stored devfile. The Che instance then uses the discovered devfile to build a workspace.

Prerequisites
Procedure
  1. Run a workspace from a devfile using the workspace:start parameter with the chectl tool as follows:

$ chectl workspace:start --devfile=devfile.yaml
Tags: