Supported Recipe Formats

Depending on the infrastructure, Che supports the following recipes out of the box (default Che build):

Infrastructure Docker Image Dockerfile Composefile Kubernetes yaml
Docker Supported Supported Supported Not supported
OpenShift Supported Not supported Not supported Supported

Docker Image

DockerImage recipe type implies that Che will pull an image from a Docker registry or use the one that is local and run it (in case of Docker) or create a pod that references this image in container spec. There are certain requirements and limitations for a Docker image to be a workspace machine:

  1. Non-terminating CMD or ENTRYPOINT. If you use your custom image, make sure it has something like tail -f /dev/null as one of its main processes.
  2. No processes and operations with sudo in CMD (OpenShift only, see Enable sudo)
  3. OpenShift only - it is recommended to use Che base stacks that are certified to run OK on OpenShift. You can also build your own image, but inherit from one of base stacks.

Dockerfile

A Dockerfile is a set of instructions that Docker performs to build an image. After you provide a Dockerfile for your workspace machine, Che will initiate Docker build, and once successful, run the resulting image. There are certain limitations here as well:

  1. There’s no context in docker build in Che. It means that commands like COPY and ADD will fail.
  2. Build of huge images may take much time, so, if you have a long Dockerfile, it’s better to build an image locally, push it to DockerHub and then use it as DockerImage recipe type (see above). Che has a reasonable timeout for a workspace to start which is 5 mins.

Composefile

When on Docker, you can run multi-container workspaces using Composefiles. However, there is some unsupported syntax:

Local “build.context” and “build.dockerfile”

Since Che workspaces can be distributed, you cannot have host-local build and Dockerfile contexts. You can, however, place these aspects so that they are remotely hosted in a git repository. Che will source the file from the remote system and then use it as its build context.

If the Dockerfile or build context requires other files to be ADD or COPY into the image that is created, then you could run into a failure, as the local Che workspace generator will not have access to those other remote files. To address this issue, you can pre-package the build context or Dockerfile into an image, push into a registry, and then reference the already-built image in your compose file. This is what we do for internal development at Codenvy.

build:
  ## remote context will work
  context: https://github.com/eclipse/che-dockerfiles.git#master:recipes/stack-base/ubuntu

  ## local context will not work
  context: ./my/local/filesystem

Using Private Repositories:

To use private repositories in a remote build context, you need to setup ssh keys on your host machine and add remote repository hostname/IP to the list of known hosts.

## The following will use master branch and build in recipes/stack-base/ubuntu folder
build:
  context: git@github.com:eclipse/che-dockerfiles.git#master:recipes/stack-base/ubuntu

Build Image

In the event that a Compose file includes both build instructions and a build image the build instructions are seen as overriding, so the build image is skipped if it exists.

Container Name

container_name: my_container

container_name is skipped during execution. Instead, Che generates container names based on its own internal patterns. Because many developers could be running the same Compose file on the same Che workspace node at the same time naming conflicts need to be avoided.

Volumes

To define volumes for workspace machines, see Volumesvolumes. Volume instructions in a Composefile are not supported.

Networks

## Not supported
networks:
  internal:
  aliases: ['my.alias’]
## Not supported
networks:
  internal:
  driver: bridge

Che does not yet currently support compose networks. We do, however, support the use of aliases through links command.

Hostname

Hostname is not supported and the machine’s name will be used for the hostname. User can use links aliases syntax to add additional hostname(s) to a machine.

Ports

Binding ports to the host system is not supported. This is done to ensure that each container does not used already assigned host ports because many developers could be running the same compose file on the same Che server host at the same time. Users can add servers to machines though.

Privileged

To secure the underlying host system privileged compose command is not supported.

The Che server can be configured to give all containers privileged access by setting the environment variable CHE_PROPERTY_machine_docker_privilege__mode=true. However, this makes the host system vulnerable and gives all containers access to the host system.

Environment File The env_file compose command is not supported. Environment variables can be manually entered in compose file or machine configuration. See: Environment variables.

Kubernetes YAML

When a workspace is being started, Che creates a Kubernetes pod. A few gotchas:

  1. Che allows user to create pods and services only
  2. Other object kinds will be ignored (PVC and route) or a workspace fails to start with an exception from Kubernetes.
  3. Volumes are not supported both in container and pod definition. See: Volumes for info about persisting ans sharing data between pods.

Below is an example of a custom recipe with two containers and one pod, and a service that is bound to port 8081:

kind: List
items:
-
 kind: Service
 apiVersion: v1
 metadata:
  name: my-service
 spec:
  selector:
    name: app
  ports:
  - protocol: TCP
    port: 8081
    targetPort: 8081
-
  apiVersion: v1
  kind: Pod
  metadata:
    name: app
  spec:
    containers:
      -
        image: eclipse/ubuntu_jdk8:latest
        name: main
        ports:
         -
          containerPort: 8081
          protocol: TCP
      -
        image: eclipse/ubuntu_jdk8:latest
        name: main1

You can also have one pod and several containers in it. Che will treat those containers as workspace machines. You can also define machine names in annotations. PodName/Container Name is the default naming pattern for a machine. You can use annotations though:

kind: List
items:
-
  apiVersion: v1
  kind: Pod
  metadata:
    name: any123123
    annotations:
      org.eclipse.che.container.main.machine_name: myMachine
      org.eclipse.che.container.main1.machine_name: myMachine1
  spec:
    containers:
      -
        image: rhche/spring-boot:latest
        name: main
        ports:
          -
            containerPort: 8080
            protocol: TCP
        resources: {}

      -
        image: rhche/spring-boot:latest
        name: main1
        ports:
          -
            containerPort: 8080
            protocol: TCP
        resources: {}