Configuring a workspace using a devfile

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

What is a devfile

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

  • the source code

  • the development components, such as 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. Devfiles saved in Git repository can use multiple names, such as devfile.yaml or .devfile.yaml.

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)

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
  • A running instance of Eclipse Che. To install an instance of Eclipse Che, see Installing Che.

  • The devfile.yaml or .devfile.yaml file is located in the root folder of a Git repository that is available over HTTPS. See Making a workspace portable using a devfile for detailed information about creating and using devfiles.

Procedure

Run the workspace by opening the following URL: +https+://:/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 Installing Che.

  • The devfile.yaml or .devfile.yaml file is located in the root folder of a Git repository, on a specific branch of the user’s choice that is accessible 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: +https+://:/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: +https+://:/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: +https+://:/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, use the following factory URL:

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

The resulting workspace has 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, use the following factory URL:

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 has 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, use the following factory URL:

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

The resulting workspace has the following devfile model:

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

When overriding attributes, everything that follows the attributes keyword is interpreted as an attribute name, so you can 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 has 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