Runtime Recipes

A recipe defines part of the runtime of a workspace. A recipe is included in a stack along with meta information that defines how the workspace runtime should be created. When creating custom workspace runtime it’s often best to create a custom stack with a custom recipe.

Workspaces can have a single runtime or multiple runtimes. SLX.cloud uses Docker, though SLX.cloud could handle runtimes other than Docker, to create runtime(s) from Dockerfiles for a single-container runtime, or compose files to create single-container/multi-container runtime(s).

A recipe references either a Dockerfile or compose definition that need to be built into image(s) or reference already-built image(s). When a workspace is created from a particular stack, SLX.cloud will take a recipe, create or use existing Docker image(s) from it, and then create runtime Docker container(s) from that/those image(s). That/Those runtime Docker container(s) will be your workspace runtime(s).

Single-Container Recipes

Defining

You can author your own recipe as a way to make your workspace runtime shareable. You can provide a URL to a custom recipe (Dockerfile or Docker compose file) or write a new custom recipe (Dockerfile or Docker compose file) from the dashboard.

Please note, SLX.cloud only supports certain compose syntax.

che-recipe-write.jpg

The easiest way is to inherit from a SLX.cloud based Docker image and then add your dependencies.

Inherit From an SLX.cloud Base Image

SLX.cloud base images are authored by Silexica and hosted on DockerHub. These base images have all of the dependencies necessary for a SLX.cloud workspace to operate normally.

To reference SLX.cloud Docker images in your Dockerfile or Docker compose recipe:

##Dockerfile
FROM silexica/tools:latest

##Compose
image: silexica/tools:latest

SLX.cloud Runtime Required Dependencies

Dependency Why? How? (Ubuntu/Debian)
User with root privileges To install our developer tools agents (like terminal access and intellisense) we need root access or a user who has sudo rights. USER root

or grant your preferred user sudo rights without password prompt.
Non-terminating CMD To keep a container running Dockerfile
CMD tail -f /dev/null

Compose
command: [tail, -f, /dev/null]

All SLX.cloud images must have a non-terminating CMD command so that the container doesn’t shut down immediately after loading. If you want to override the default CMD, add tail -f /dev/null to the execution. For example:

##Dockerfile
CMD sudo service apache2 start && tail -f /dev/null

##Compose
command: [sudo, service, apache2, start, &&, tail, -f, /dev/null]

Optional Dependencies

Dependency Why? How? (Ubuntu/Debian)
svn Required to import projects stored in subversion repositories. sudo apt-get install subversion -y

Even though SLX.cloud workspaces require Java 1.8, it is ok not to have it in your custom image. In this case, SLX.cloud agent will automatically install it. Of course, this takes time (openjdk package is installed via a package manager like apt-get, dnf or yum).

Exposing Ports (Mandatory)

All workspace processes run in Docker containers. SLX.cloud uses Docker’s method to access/preview apps by exposing and publishing ports.

All ports exposed in a base image are randomly published by Docker onto host interfaces. Docker uses the ephemeral port range to externalize your services’ ports. What SLX.cloud does with exposed ports is an equivalent to docker run -P where -P lets Docker choose local ports.

To make your app/process accessible

1: Expose the port your app/process is bound to. For example, if your application runs on 3000, add the following instruction to your custom Dockerfile or Docker compose recipe:

##Exposing a single port in a Dockerfile
EXPOSE 3000

##Exposing a single port in a compose file
expose: 3000

##Exposing multiple ports in a Dockerfile
EXPOSE 3000 5000

##Exposing multiple ports in a compose file
expose:
 - 3000
 - 5000

2: Go to user dashboard for your workspace and click on the Runtimes tab. Select your machine and then in a section called “Server” you will see a table with all the ports exposed in the recipe and their corresponding externally published ports.

3: You can also get the published port automatically by using a macro in a command. When authoring a command, set its preview URL to ${server.port.<your-apps-port>} where <your-apps-port> is the port in your recipe’s expose command. When the command is executed, this macro is translated into a host:port URL.

There is no way to expose a port once the workspace is running. To expose an additional ports, the ports need to be added to the runtime recipe or added directly to the runtime instance via the dashboard Workspaces>(click workspace name)>Runtime Tab.

che-workspace-runtime-servers.png

Multi-Container Recipes

The majority of the Docker Compose file syntax works with SLX.cloud . However, SLX.cloud is a distributed system that supports multiple users on a single node, and in order to manage this distribution and multi-user capabilities, there are certain compose features that are not supported.

Unsupported Compose Syntax

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

Since SLX.cloud 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. SLX.cloud 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 SLX.cloud 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/ubuntu_jre

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

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, SLX.cloud generates container names based on its own internal patterns. Because many developers could be running the same Compose file on the same SLX.cloud workspace node at the same time naming conflicts need to be avoided.

Networks

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

SLX.cloud 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 SLX.cloud server host at the same time. Users can expose ports and provide a command macro ${server.port.<port>} in the IDE to determine the ephemeral port assigned.

Privileged

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

Environment File

The env_file compose command is not supported. Environment variables can be manually entered in compose file or source /<path>/<environment filename> can be added to the command compose command.