Chapter 14. Administering workspaces

Use the stacks in the Dashboard to create a workspace. Images and configuration in these stacks are certified both for Docker and OpenShift. These stacks are used in daily functional testing.

14.10.1.1. Creating a workspace from stacks in the dashboard

To create a workspace from stacks in the Dashboard, take the following steps:

1. In the Dashboard, in the left panel, click Stacks.
2. Click the Duplicate stack icon for the stack that you want to create a clone of. A page titled after the selected stack opens.
3. Edit the fields that you want to edit.
4. Click Save.

14.10.1.2. Duplicating an existing stack

Create a stack and then use the resulting stack to create a workspace.

To create a copy of an existing stack, take the following steps:

1. In the Dashboard, in the left panel, click Stacks.
2. Click the Duplicate stack icon for the stack that you want to clone.
3. Edit the Name field.
4. In the Machines field, edit the Source field.
5. Click Save. The Stack is successfully updated message confirms that the stack is updated.
6. In the Dashboard, click Workspaces > Add Workspace.
7. In the SELECT STACK section, scroll through the list to locate the stack that you created in the preceding steps.
8. Click Create to create the workspace based on this stack.

14.10.1.3. Creating a custom stack from a custom recipe

Author a custom recipe and then create a stack. Use the resulting stack to create a workspace.

To create a custom stack from a custom recipe, take the following steps:

1. In the Dashboard, click Workspaces > Add Workspace.
2. From the SELECT STACK field, select the required stack.
3. Click Add Stack.
4. In the Create Stack dialog box, click Yes to confirm that you want to create the stack from a recipe.
5. In the Build stack from recipe window, type the recipe name from which you want to build this stack (example: FROM: eclipse/new-stack).
6. Click OK.
7. In the Name field, type a name for the stack.
8. In the Runtimes > Machines > Recipe section, click Show to ensure that the stack is being created using the recipe that you set in the preceding steps (eclipse/new-stack, in this case).
9. Click Save.

You can start a workspace in one of the following ways:

The workspace may take time to start depending on factors like network conditions, container image availability, and configured installers attempting to install additional tools and software in the runtime. Track the progress of the workspace start operation in the Workspace Start tab. The tabs for each machine in the workspace environment stream logs from the installers (terminal, exec agent, ws agent, and language servers if any).

After a workspace is created or started, you can modify it by adding projects, installers, environment variables, and volumes.

Change the configuration of a running workspace and saving it restarts the workspace. To learn more about workspace configuration, see:

A developer executes a command to achieve a particular step in the development workflow. CodeReady Workspaces provides the ability to organize commands per goal:

The context of a command defines the projects that the command can be used with. For example: a maven build command is relevant only if the project uses Maven.

Workspace commands are available in the Commands Explorer view. This view is accessible from the left pane. The commands are organized in this view by goal.

To create new commands, use the + icon next to a goal. Alternatively, you can select a command from the tree to edit, duplicate, or delete it.

The command editor is a distinct tab in the existing editor pane. Double-click the tab to use the full-screen edit mode. The editor can be split vertically or horizontally to display multiple editors at once.

CodeReady Workspaces provides macros that can be used within a command or preview URL to reference workspace objects. To learn more, see the Macros section.

When editing a command, you can access all the macros that can be used in the command’s instructions or in the preview URL. To display a complete list of macros, click on the Macros link.

You can auto-complete all macros used in the editor. To activate the auto-complete feature, press Ctrl+Space. This displays a menu listing all the possible macros based on what is typed.

You can use commands from the following widgets:

14.11.6.1. Using the Command Palette

Use the Shift+F10 keys to open the Command Palette. Use the arrow keys to navigate through the list of commands. Use Enter to execute a selected command.

14.11.6.2. Using the command toolbar

Using the command toolbar, you can execute the most common Run and Debug goals. The toolbar provides access to all the executed commands and previews.

14.11.6.2.1. Using the Run and Debug buttons

To trigger commands directly from the Run and Debug buttons, you must define the commands for the Run and Debug goals.

You are asked to choose the default command associated with a button when you use this button for the first time and this button has multiple commands defined for a goal. Consecutive clicks of this button trigger the previously selected command.

To select a command to execute from a goal, click and hold the button. This command becomes the default command associated with the button.

14.11.6.2.2. Using the command controller

Use the command controller to view the state of the workspace and the last command that was executed. You can see the time span since a command was started and decide if it should be stopped or relaunched.

To view the list of all the previously executed commands when multiple commands are executed, click on the widget.

To clean the list, remove the process of the command from the list of processes.

14.11.6.2.3. Using the Preview button

For commands used to start servers, define the preview URL to access the running server. To learn more, see the Preview URLs section.

The Preview button provides quick access to all of fthe servers that are running in the machines of the workspace.

A command may contain a single instruction or a succession of commands. For example:

cd /projects/spring				1
mvn clean install

cd /projects/spring; mvn clean install		1

cd /projects/spring && mvn clean install	1

To check for conditions, use loops and other bash syntax:

mvn -f ${current.project.path} clean install	1
  if [[ $? -eq 0 ]]; then
    cp /projects/kitchensink/target/*.war /home/user/wildfly-10.0.0.Beta2/standalone/deployments/ROOT.war
    echo "BUILD ARTIFACT SUCCESSFULLY DEPLOYED..."
else
    echo "FAILED TO DEPLOY NEW ARTIFACT DUE TO BUILD FAILURE..."
fi

CodeReady Workspaces provides macros that can be used within a command or preview URL to reference workspace objects. Macros are translated into real values only when used in the IDE.

The following table lists the macros and their descriptions.

The workspace machine has a set of system environment variables that have been exported. They are reachable from your command scripts using the bash syntax.

export					1

$TOMCAT_HOME/bin/catalina.sh run	2

A stack is a workspace configuration template. Stacks are used to create workspaces in the User Dashboard. The stack includes meta-information such as scope, tags, components, description, name, and identification. You can filter stacks by machine type and scope. The type is either single machine or multi machine. You can also search for a stack by keyword. Stacks are displayed in the User Dashboard on the Create a workspace page.

See the Creating and starting workspaces user guide for more information.

CodeReady Workspaces includes some stacks and sample applications that are pre-configured and tested. Stacks that are contributed by the CodeReady Workspaces community are not tested. Community stacks are located in the community stacks GitHub repository.

Each directory has ${technology}-stack.json and ${technology}-samples.json.

To import a stack, follow these steps:

You can choose a different name or ID when there is a conflict with the stack ID or name.

For a multi-user setup, you can make your stack available for a particular user or all users in the system. See stack sharing for more information.

To import sample applications, move *-stacks.json files to:

You can find Dockerfiles for all stacks in the CodeReady Workspaces Dockerfiles repository.

You can share stacks with selected users or with all users in the system if you have system privileges. You share stacks by making REST calls.

To share stacks with users:

{
"userId": "*",
  "domainId": "stack",
  "instanceId": "${STACK_ID}",
  "actions": [
    "read",
    "search"
  ]
}

If you get 204, all the users in the system see the stack. To share a stack with a particular user, get the user’s ID and use it instead of * in the JSON file.

The administrator can remove pre-configured stacks and replace them with custom stacks. The administrator can also remove permissions from stacks. You can create stacks either in the user dashboard or by using any REST client. You can use Swagger ($CHE_HOST:$CHE_PORT/swagger) to bundle with CodeReady Workspaces.

Stacks are loaded from a JSON file that is packaged into resources of a special component that is deployed with the workspace master. This JSON file is not exposed to users. You can perform stack management using REST APIs in the User Dashboard.

When a user first starts CodeReady Workspaces, stacks are loaded from a JSON file only when the database is initialized. This is the default policy that can be changed. To keep getting stack updates with the new CodeReady Workspaces stacks, set CHE_PREDEFINED_STACKS_RELOADONSTART=true in che.env. When set to true, stacks.json is used to update CodeReady Workspaces database each time the CodeReady Workspaces server starts. This means CodeReady Workspaces gets all the stacks in stacks.json and uploads the stacks to a database. This allows you to keep existing custom stacks and get stack updates from new CodeReady Workspaces releases. New and edited stacks that have fixes in the stack definition are merged in with the other stacks.

Name conflicts are possible. A name conflict happens when a new CodeReady Workspaces version provides a stack with a name that already exists in the database.

Every stack is based on a container image. The image is used in an OpenShift deployment when a workspace is started. The resulting container in a pod is used both as build and runtime for a user application. It is also used in CodeReady Workspaces agents that are installers that activate the terminal, workspace agent, and language servers.

Because all agents have their dependencies, the underlying images must have those dependencies available.

Agents are injected in the running containers. Therefore, the current container user must have write access to the ~/che directory. This is also a requirement for an image that can be used in a workspace stack definition.

FROM registry.redhat.io/codeready-workspaces/stacks-java-rhel8
RUN sudo dnf install some-software

FROM <myregistry/myimage>
USER root
RUN dnf install -y java-1.8.0-openjdk-devel [some-software]
CMD tail -f /dev/null

Depending on the infrastructure, CodeReady Workspaces supports the following default recipe formats:

The Docker-formatted container image recipe pulls an image from a Docker registry or uses the local image. The recipe then runs the image and creates a pod that references this image in the container specification. The following are Docker-formatted container image requirements and limitations for a workspace machine:

A Dockerfile is a set of instructions that Docker performs to build an image. After you provide a Dockerfile for your workspace machine, CodeReady Workspaces initiates a Docker build and runs the resulting image. The following are the limitations:

You can run multi-container workspaces using Compose files on Docker. The following syntax is not supported: Local "build.context" and "build.dockerfile".

Because workspaces can be distributed, you cannot have host-local build and Dockerfile contexts. You can remotely host these aspects in a Git repository. CodeReady Workspaces sources the Compose file from the remote system and uses it as the build context.

You can run into a failure when the Dockerfile or build context requires you to ADD or COPY other files into the image. The local workspace generator cannot access these remote files.

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

## 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

container_name: my_container

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

When a workspace is starting, CodeReady Workspaces creates various Kubernetes resources to support the IDE and development tools. Workspaces primarily consist of a Deployment which runs a Kubernetes pod. The following are limitatons and restrictions:

The following is an example of a custom recipe with two containers, a simple config map, one deployment, and a service that is bound to port 8081:

kind: List
items:
  -
    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: my-deployment
    spec:
      replicas: 1
      selector:
        matchLabels:
          my-workspace-pod: dev
      template:
        metadata:
          name: dev-pod
          labels:
            my-workspace-pod: dev
        spec:
          containers:
            -
              image: eclipse/ubuntu_jdk8:latest
              name: main
              ports:
              -
                containerPort: 8081
                protocol: TCP
              env:
              -
                name: MY_ENV_VAR
                valueFrom:
                  configMapKeyRef:
                    name: my-configmap
                    key: my-key
            -
              image: eclipse/ubuntu_jdk8:latest
              name: main1
  -
    apiVersion: v1
    kind: ConfigMap
    metadata:
      name: my-configmap
    data:
      my-key: my-value
  -
    kind: Service
    apiVersion: v1
    metadata:
      name: my-service
    spec:
      selector:
        name: app
      ports:
      - protocol: TCP
        port: 8081
        targetPort: 8081

As a bare minimum, a Kubernetes YAML recipe must contain at least one Pod or Deployment, in which the main dev machine is run.

You can also specify multiple containers within the workspace pod. CodeReady Workspaces treats those containers as workspace machines. These containers can have machine names defined in annotations. PodName/Container Name is the default naming pattern for a machine.

The following is an example of using annotations:

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: {}

A server defines the protocol port of a process that runs in a machine. It has a name, path, and attributes. The path defines the base path of the service that is used by the server. Attributes are optional and can be used to tune the server or for identification. You can add a server when you need to access a process in your workspace machine.

To add a server, use the User Dashboard or edit the workspace machine configuration YAML file.

The following is an example of the YAML file:

"node": {
    "port": "3000",
    "protocol": "http",
    "path": "/",
    "attributes": {}
}

The following is an example of the User Dashboard:

Adding the server with port 3000 does not mean you can use this port to access a server. Each server is assigned a URL when a workspace is running.

In this example, you added a server with port 3000 and started a workspace. The following are ways to get the server’s preview URL:

You can also see internal server URLs. Internal servers launch when the workspace container or pod is available.

To access a port internally within a workspace, expose it internally, but do not make it publicly accessible. For example, a database server is exposed only for the web application and because of security concerns, it should not be accessible publicly. The database server is exposed as internal.

To expose a server as internal, add the corresponding attribute into the server configuration YAML file:

"db": {
    "port": "3200",
    "protocol": "tcp",
    "attributes": {
        "internal": "true"
    }
}

The application is able to fetch the database URL from the workspace runtime and access the database. The database URL is not accessible publicly from the browser.

Secure servers are exposed publicly but access is restricted only for users who have permissions to the workspace. The authentication proxy is set up as the exposed server and the machine token is required to request it.

To expose a server as secure, add the corresponding attributes into the server configuration YAML file:

"tooling": {
    "port": "4921",
    "protocol": "http",
    "attributes": {
        "secure": "true",
        "unsecuredPaths": "/liveness",
        "cookiesAuthEnabled": "true"
    }
}

The following describes the attributes:

Installers are scripts that are added into machines in a runtime. Once running, installers:

Installers are typically language servers and tools that provide features such as SSH access to a workspace machine. You can find a complete list of available installers in the Workspace details > Installers tab.

The following is an example of installers:

"installers": [
    "org.eclipse.che.exec",
    "org.eclipse.che.terminal",
    "org.eclipse.che.ws-agent",
    "org.eclipse.che.ssh"
        ]

Installers are saved in a configuration file that a bootstrapper uses to execute jobs. An installer script works exactly the same way as other shell scripts in Linux. The CodeReady Workspaces server checks if the launched process is running.

Some installers activate special agents, such as the workspace, terminal, and execution agents. If a workspace agent fails to start, the workspace is treated as if it has been started but the IDE is not usable. If the execution agent fails, the commands widget is unavailable.

You can enable or disable installers per machine by using the User Dashboard or by updating the workspace machine configuration. When an installer is enabled, the bootstrapper executes an installer script after the workspace has started.

The following shows installers that are enabled and disabled:

CodeReady Workspaces installers are stored in the Installer Registry. They can be viewed and edited through the Installer Registry REST API:

By default, workspace containers start with a default volume and have a minimum of one PVC that is located in the /projects directory.

Workspace projects are physically located in the /projects directory. When a workspace stops, the machines are destroyed, but the volumes persist.

In order for your data to persist for a local Maven repository, the node_modules/ directory, Ruby gems, or the authorized_keys file for SSH connections, your workspace will need additional volumes. Each machine can add as many volumes as the underlying infrastructure can support. OpenShift may impose a limit on the number of volumes.

You can add volumes either by using the User Dashboard or by updating the machine configuration. The following is an example of the configuration file:

"volumes": {
  "myvolume": {
    "path": "/absolute/path/in/workspace"
  }
}

To avoid failures when updating the workspace configuration using REST APIs:

To configure workspaces on the OpenShift and Kubernetes infrastructure as ephemeral, set the persistVolumes attribute to false in the workspace configuration.

The following is an example of the configuration file:

"attributes": {
  "persistVolumes": "false"
}

In this case, regardless of the PVC strategy, all volumes would be created as emptyDir for the given workspace. When a workspace pod is removed for any reason, the data in the emptyDir volume is deleted forever.

Projects are always associated with a workspace and saved in a workspace configuration.

The following is an example of the project YAML file:

"projects": [
   {
     "description": "A basic example using Spring servlets. The app returns values entered into a submit form.",
     "source": {
       "location": "https://github.com/che-samples/web-java-spring.git",
       "type": "git",
       "parameters": {}
     },
     "links": [],
     "mixins": [],
     "problems": [],
     "name": "web-java-spring",
     "type": "maven",
     "path": "/web-java-spring",
     "attributes": {}
   }
 ]

Once a project is saved into a workspace configuration, the IDE checks if the project exists on a file system. Use the source.location URL to import projects that do yet exist on the file system. This happens during the IDE initialization stage.

You can add the following projects:

Project import tools can be found on the User Dashboard when you are creating a new workspace or editing an existing workspace in the IDE. Project import tools can also be found in the Workspace menu.

The following shows example projects:

Plug-in developers can define their own project types. Since project types trigger certain behaviors within the IDE, the construction of the projects is important to understand.

A sub-project is a portion of a project that can have sets of commands run against it where the sub-directory is treated as the root working directory. Sub-projects make it possible to organize a single repository into multiple, independently buildable, and runnable units.

To create a module, right-click on a directory in the IDE explorer tree and select Convert to Project. You can then execute commands directly against this sub-project.

You can step into or out of the project tree. When you step into a directory, that directory is set as the project tree root and the explorer refreshes the view. All commands are then executed against this directory root.

When a workspace is starting, an environment recipe is sent to Docker or to the OpenShift API. The CodeReady Workspaces server then listens to events provided by the given infrastructure. The CodeReady Workspaces server expects a running Docker container or an OpenShift pod. The server fails to start an environment and consequently the starting of the workspace fails if the infrastructure is unable to create and start a container or a pod from the provided recipe.

A recipe can be incorrect due to the following reasons:

The CodeReady Workspaces server and agents, which run in a workspace container or pod, and the user’s browser communicate with each other. Firewall, filtered ports, and other network restrictions may cause trouble when starting a workspace.

A workspace is considered to be in a RUNNING state after the CodeReady Workspaces server verifies that the workspace agent is up. The workspace agent also tries to reach the CodeReady Workspaces server. All this happens in separate containers or pods, and the user’s browser is not yet involved. The workspace started by user $userName message in the CodeReady Workspaces server logs indicates the following:

When a workspace starts, the CodeReady Workspaces server creates and starts a container or a pod or a set of containers and pods as per the environment recipe. After the container or pod is running, a bootstrapping process begins - the bootstrapper binary is downloaded and launched. If the server logs show bootstrapping failures, or you do not see any output in the Machine tab of the Workspaces view, the reason is that bootstrapper is not downloaded. The following are possible the reasons for the bootstrapper download failure:

To work around the problem, download the bootstrapper binary manually. On OpenShift, access the pod on the command line (shell or the terminal in the web console) and run the following commands:

$ cd /tmp/bootstrapper
$ ls -la  1
$ curl ${CHE_URL}/agent-binaries/linux_amd64/bootstrapper/bootstrapper

To prevent the curl command from failing, unblock port 80 on your network. On OpenShift with https routes, unblock port 443.

For recipe types of dockerfile, compose, or openshift, content, not location, is specified.

"recipe": {
  "type": "compose",
  "content": "services:\n db:\n  image: eclipse/mysql\n  environment:\n   MYSQL_ROOT_PASSWORD: password\n   MYSQL_DATABASE: petclinic\n   MYSQL_USER: petclinic\n   MYSQL_PASSWORD: password\n  mem_limit: 1073741824\n dev-machine:\n  image: eclipse/ubuntu_jdk8\n  mem_limit: 2147483648\n  depends_on:\n    - db",
  "contentType": "application/x-yaml"
}

The project object structure has the source.location and source.type parameters. There are two importer types: git and zip. New location types can be provided by custom plugins, such as svn.

Incorrectly configured projects or projects missing sources are marked with error codes and messages explaining the error. In the example above, the project does not have errors and mixins.

A mixin adds additional behaviors to the project, the IDE panels, and menus. Mixins are reusable across any project type. To define the mixins to add to a project, specify an array of strings, with each string containing the identifier for the mixin.

The pullrequest mixin requires additional configuration from the attributes object of the project.

The project object can include source.parameters, which is a map that can contain additional parameters. Example: related to project importer.

Commands can be both tied to a workspace and an individual project. In the example below, a command is saved to workspace configuration.

The followling image shows ways to save commands in the project configuration.

A runtime object is created when a workspace is in a running state. Runtime returns server URLs, internal or external, depending on the server configuration. Interested clients, like the User Dashboard and the IDE, use these URLs.

Clone a public workspace on che.openshift.io by clicking try a factory.

Factories can be invoked from a factory URL built in multiple ways. You can replace the localhost:8080 domain with the hostname of any CodeReady Workspaces installation.

Using factories on che.openshift.io requires the user to be authenticated. Users who are not authenticated see a login screen after they click on the factory URL. Users without an account can create one using the same dialog.

Once a factory is executed, it either loads an existing workspace or generates a new one, depending on the factory configuration. The name of the workspace is determined by the factory configuration, and its name becomes a part of the URL used to access the factory. The format is: {hostname}/{username}/{workspace}.

You have just created your first developer workspace using factories. Read on to learn more about:

A factory configuration is a JSON snippet either stored within CodeReady Workspaces or as a .factory.json file. You can create factories within the IDE using the CodeReady Workspaces URL syntax, within the dashboard, or on the command line with the API and CLI.

factory : {
  "v"         : 4.0,            1
  "workspace" : {},             2
  "policies"  : {},             3
  "ide"       : {},             4
  "creator"   : {},             5
}

The factory.workspace is identical to the workspace:{} object for CodeReady Workspaces and contains the structure of the workspace. To learn more about the workspace JSON object, see Workspace Data Model.

You can export workspaces and then reuse the workspace definition within a factory. workspaces are composed of the following:

The factory.policies, factory.ide, and factory.creator objects are unique to factories. They provide meta information to the automation engine that alter the presentation of the factory URL or the behavior of the provisioning.

factory.workspace.project : {
  "mixins"     : [ "pullrequest" ],

  "attributes" : {
    "local_branch"         : [ "timing" ],
    "contribute_to_branch" : [ "master" ]
  },

  "source" : {
    "type"       : "git",
    "location"   : "https://github.com/codenvy/che.git",
    "parameters" : {
      "keepVcs" : "true"
    }
  }
}

factory.policies : {
  "referer"   : STRING,                 1
  "since"     : EPOCHTIME,              2
  "until"     : EPOCHTIME,              3
  "create"    : [perClick | perUser]    4
}

factory.ide.{event} : {                 1
  "actions" : [{}]                      2
}

factory.ide.{event}.actions : [{
  "id"         : String,                3
  properties : {}                       4
}]

"ide" : {
  "onProjectsLoaded" : {                                               1
    "actions" : [{
      "id" : "openFile",                                               2
      "properties" : {                                                 3
        "file" : "/my-project/pom.xml"
      }
    },
    {
      "id" : "runCommand",                                             4
      "properties" : {
        "name" : "MCI"                                                 5
      }
    }
  ]},
  "onAppLoaded": {
     "actions": [
        {
           "properties:{
              "greetingTitle": "Getting Started",                      6
              "greetingContentUrl": "http://example.com/README.html"   7
           },
           "id": "openWelcomePage"
        }
     ]
  },
  "onAppClosed" : {                                                    8
    "actions" : [{
      "id" : "warnOnClose"                                             9
    }]
  }
}

{
  "id" : "openFile",
    "properties" : {
      "file" : "/my-project/pom.xml",
      "line" : "50"
  }
}

{
  "commandLine": "sed -i 's/***/userId984hfy6/g' /projects/console-java-simple/README.md",
  "name": "replace",
  "attributes": {
    "goal": "Common",
    "previewUrl": ""
  },
  "type": "custom"
}

"ide": {
    "onProjectsLoaded": {
      "actions": [
        {
          "properties": {
            "name": "replace"
          },
          "id": "runCommand"
        }
      ]
    }
  }

factory.creator : {
  "name"      : STRING,            1
  "email"     : STRING,            2
  "created"   : EPOCHTIME,         3
  "userId"    : STRING             4
}