Administration Guide

To deploy CodeReady Workspaces with a self-signed certificate, run the following command:

$ ./deploy.sh --deploy --oauth

To deploy CodeReady Workspaces to a cluster configured with public certificates, run the following command:

$ ./deploy.sh --deploy --public-certs

To deploy with an external Red Hat Single Sign-On (Red Hat SSO) and enable a Red Hat SSO instance, take the following steps:

The deploy script supports the following combinations of external Red Hat SSO and PostgreSQL:

The deploy script does not support the external database and bundled Red Hat SSO combination currently. Provisioning of the database and the Red Hat SSO realm with the client happens only with bundled resources. If you are connecting your own database or Red Hat SSO, you should pre-create resources.

To deploy with the external PostgreSQL database and Red Hat SSO, take the following steps:

To view the installation logs on the terminal, take the following steps:

To view installation logs in OpenShift console, take the following steps:

You can upload an existing public key instead of creating a new SSH key. When uploading a key, add the host name (using no www or https - as in the example below). Note that the Public key > View button is not be available when using this option because the public file should be generated already.

The following examples are specific to GitHub and GitLab, but a similar procedure can be used with all Git or SVN repository providers that use SSH authentication. See documentation provided by other providers for additional assistance.

$ ssh-keygen -p -f <your_key_file> -m PEM

$ ssh-keygen -f <new_key_file> -m PEM

Example 11.1. GitHub example

When not using GitHub OAuth, you can manually upload a key. To add the associated public key to a repository or account on github.com:

1. Click your user icon (top right).
2. Go to Settings > SSH and GPG keys and click the New SSH key button.
3. Enter a title and paste the public key copied from CodeReady Workspaces to the Key text field.

Example 11.2. GitLab example

To add the associated public key to a Git repository or account on gitlab.com:

1. Click your user icon (top right).
2. Go to Settings > SSH Keys.
3. Enter a title and paste the public key copied from CodeReady Workspaces to the Key text field.

Commit your changes by navigating to Git > Commit…​ in the main menu, or use the Alt+C shortcut.

Behavior for files in the list view is the same as in the Compare window (see Reviewing changed files section). Double-clicking a file opens diff window with it.

Push your commits by navigating to Git > Remotes…​ > Push in the main menu, or use the Alt+Shift+C shortcut.

Get changes from a remote repository by navigating to Git > Remotes…​ > Pull in the main menu, or use the Alt+P shortcut.

You can use Rebase instead of merge to keep your local commits on top (for more information, see Git pull documentation).

Manage your git branches by navigating to Git > Branches…​ in the main menu, or use the Ctrl+B shortcut.

You can filter the branches view by choosing to see only local or remote branches.

The default workspace RAM limit and the RAM allocation request can be configured by passing the CHE_WORKSPACE_DEFAULT__MEMORY__LIMIT__MB and CHE_WORKSPACE_DEFAULT__MEMORY__REQUEST__MB parameters to a CodeReady Workspaces deployment.

For example, use the following configuration to limit the amount of RAM used by workspaces to 2048 MB and to request the allocation of 1024 MB of RAM:

$ oc set env dc/che CHE_WORKSPACE_DEFAULT__MEMORY__LIMIT__MB=2048 \
                         CHE_WORKSPACE_DEFAULT__MEMORY__REQUEST__MB=1024

To setup a single OpenShift project:

In the command above, eclipse-che is the CodeReady Workspaces namespace.

The workspace PVC strategy is configurable:

To define the unique strategy, set CHE_INFRA_KUBERNETES_PVC_STRATEGY to unique.

Every workspace gets its own PVC, which means a workspace PVC is created when a workspace starts for the first time. A workspace PVC is deleted when a corresponding workspace is deleted.

To define the unique strategy, set CHE_INFRA_KUBERNETES_PVC_STRATEGY to per-workspace.

To perform a recreate update:

To perform a rolling update:

If new version of CodeReady Workspaces server contains some DB migrations, but there is still API compatibility between old and new version, recreate update type may be used, without stopping running workspaces.

API incompatible versions should be updated with full workspaces stop. It means that /api/system/stop?shutdown=true must be called prior to update.

Machines may contain services that must be protected with authentication, e.g. agents like workspace agent and terminal. For this purpose, machine authentication mechanism should be used. Machine tokens were introduced to avoid passing the Keycloak tokens to the machine side (which can be potentially insecure). Another reason is that Keycloak tokens may have relatively small lifetime and require periodical renewal/refresh which is hard to manage and keep in sync with same user session tokens on clients etc.

As agents cannot be queried using Keycloak token, there is only Machine Token option. Machine token can be also passed in header or query parameter.

# Header
{
  "alg": "RS512",
  "kind": "machine_token"
}
# Payload
{
  "wsid": "workspacekrh99xjenek3h571",
  "uid": "b07e3a58-ed50-4a6e-be17-fcf49ff8b242",
  "uname": "john",
  "jti": "06c73349-2242-45f8-a94c-722e081bb6fd"
}
# Signature
{
  "value": "RSASHA512(base64UrlEncode(header) + . +  base64UrlEncode(payload))"
}

13.9.2.2. Authentication schema

The way how CodeReady Workspaces master interacts with agents with enabled authentication mechanism is the following:

Machine token verification on agents is done by the following components:

• org.eclipse.che.multiuser.machine.authentication.agent.MachineLoginFilter - doing basically the same as the appropriate filter on a master, the only thing that is different it’s a way how agent obtains the public signature part. The public key for the signature check is placed in a machine environment, with algorithm description.
• auth.auth.go - the entry point for all request that is proceeding on go agents side, the logic of token verification is similar with MachineLoginFilter.

User’s Keycloak token is used to execute queries to secured API on his behalf through REST clients. A valid token must be attached as request header or query parameter - ?token=$token. CodeReady Workspaces Swagger can be accessed from http://che_host:8080/swagger. A user must be signed-in through Keycloak so that access token is included in request headers.

By default, swagger loads swagger.json from CodeReady Workspaces master.

To work with WS Agent, a URL to its swagger.json should be provided. It can be retrieved from Workspace Runtime, by getting URL to WS Agent server endpoint and adding api/docs/swagger.json to it. Also, to authenticate on WS Agent API, user must include Machine Token, which can be found in Workspace Runtime as well.

To use Swagger for a workspace agent, user must do following steps:

"wsagent/http": {
  "url": "http://172.19.20.180:32777/api",
  "attributes": {},
  "status": "RUNNING"
}

"machineToken": "eyJhbGciOiJSUzUxMiIsImtpbmQiOiJtYWNoaW5lX3Rva2VuIn0.eyJ3c2lkIjoid29ya3NwYWNlMzEiLCJ1aWQiOiJ1c2VyMTMiLCJ1bmFtZSI6InRlc3RVc2VyIiwianRpIjoiOTAwYTUwNWYtYWY4ZS00MWQxLWFhYzktMTFkOGI5OTA5Y2QxIn0.UwU7NDzqnHxTr4vu8UqjZ7-cjIfQBY4gP70Nqxkwfx8EsPfZMpoHGPt8bfqLWVWkpp3OacQVaswAOMOG9Uc9FtLnQWnup_6vvyMo6gchZ1lTZFJMVHIw9RnSJAGFl98adWe3NqE_DdM02PyHb23MoHqE_xd8z3eFhngyaMImhc4",

Permissions are used to control the actions of users and establish a security model. You can control resources managed by CodeReady Workspaces and allow certain actions by assigning permissions to users.

Permissions can be applied to the following:

The user who creates a workspace is the workspace owner. The workspace owner has the following permissions by default: read, use, run, configure, setPermissions, and delete. Workspace owners invite users into the workspace and control workspace permissions for each user.

The following permissions are associated with workspaces:

An organization is a named set of users.

The following permissions are applicable to organizations:

System permissions control aspects of the whole CodeReady Workspaces installation.

The following permissions are applicable to the organization:

All system permissions will be granted to the administration user configured with the `CHE_SYSTEM_ADMIN__NAME` property (the default is admin). This happens at CodeReady Workspaces Server start. If the user is not present in the CodeReady Workspaces user database, it happens after the user’s login.

Users with the manageSystem permission have access to the following services:

Users with the monitorSystem permission have access to the following services:

The manageSystem permission can be extended to provide a super-privileged mode. This allows the user to perform advanced actions on any resources managed by the system. You can read and stop any workspaces with the manageSystem permission and assign permissions to users as needed.

The super-privileged mode is disabled by default. You can change to super-privileged mode by configuring the `CHE_SYSTEM_SUPER__PRIVILEGED__MODE` variable to true in the che.env file.

List of services that are enabled for users with manageSystems permissions and with super-privileged mode on:

A stack is a runtime configuration for a workspace. See stack definition for more information on stacks.

The following permissions are applicable to stacks:

All permissions can be managed using the provided REST API. The APIs are documented using Swagger at [{host}/swagger/#!/permissions].

To list the permissions that apply to a specific resources, run this command:

$ GET /permissions

The domain values are:

To list the permissions that apply to a user, run this command:

$ GET /permissions/{domain}

The domain values are:

To list the permissions that apply to all users, run this command:

GET /permissions/{domain}/all

The domain values are:

To assign permissions to a resource, run this command:

POST /permissions

The domain values are:

The following is a message body that requests permissions for a user with a userID to a workspace with a workspaceID:

{
  "actions": [
    "read",
    "use",
    "run",
    "configure",
    "setPermissions"
  ],
  "userId": "userID",
  "domainId": "workspace",
  "instanceId": "workspaceID"
}

The instanceId parameter corresponds to the ID of the resource that retrieves the permission for all users. The userId parameter corresponds to the ID of the user that has been granted certain permissions.

A user with setPermissions privileges can share a workspace and grant read, use, run, configure, or setPermissions privileges to other users.

To share workspace permissions:

Organizations allow administrators to group CodeReady Workspaces users and allocate resources. The system administrator controls and allocates resources and permissions within the administrator dashboard.

CHE_MAIL_PORT=465
CHE_MAIL_HOST=smtp.gmail.com
CHE_MAIL_SMTP_STARTTLS_ENABLE=true
CHE_MAIL_SMTP_AUTH=true
CHE_MAIL_SMTP_AUTH_USERNAME=no-reply@gmail.com
CHE_MAIL_SMTP_AUTH_PASSWORD=password

The Resource API manages the resources that are utilized by CodeReady Workspaces users. The CodeReady Workspaces administrators set the limits on the amount of resources available for each resource type and each user.

There are two kinds of accounts used in CodeReady Workspaces:

Resource usage mostly refers to resources used by workspaces and runtimes in the development flow.

CodeReady Workspaces supports the following types of resources:

Total resources

GET resource/${accountId}: Gets the list of total resources an account can use;

Used resources

GET resource/{accountId}/used: Gets the resources used by an account;

Available resources

GET resource/${accountId}/available: Gets the resources that are available and not used by an account. If no resources are used, the available resources equal total resources. If resources are used, the available resources equals total resources minus used resources.

Resource details

GET resource/{accountId}/details: Gets detailed information about the resources available for an account. The detailed information includes: resource providers, resource-usage start time, and resource-usage end time.

For more information about the response objects and required parameters, see the Swagger page at ${che-host}/swagger/#/resource.

The following are ways to distribute resources to an account:

The CodeReady Workspaces administrator can limit how workspaces are created and the resources that these workspaces consume. Detailed information about each property can be found in the che.env file.

The unit has the following formats:

The Resource-free API manages the free resources that are provided by the system configuration. You can override resources for an account.

Free Resources

GET resource/free: Gets the resources that are available.

GET resource/free/{accountId}: Gets the resources that are available for this account.

Set Free Resources

POST resource/free: Sets the maximum amount of resources available for the user organization account. This number overrides the Сhe configuration. It will be used in all further operations with resources.

Remove Free Resources

DELETE resource/free/{accountId}: Deletes the number of resources available for the user and organization account. The system configuration defines the amount of resources available.

For more information on response objects and required parameters, see the Swagger page at {che-host}/swagger/#/resource-free.

Distributed Organization Resources

GET organization/resource/{organizationId}: Gets the resources that the parent organization provides to the sub-organization.

Sub-Organization Resources Cap

GET organization/resource/{suborganizationId}/cap: Gets the maximum amount of resources that are available for a sub-organization; By default, sub-organizations can use all the resources of the parent organization.

Set Sub-Organization Resources Cap

POST organization/resource/{suborganizationId}/cap: Sets the maximum amount of resources for a sub-organization. This limits the usage of shared resources by the sub-organization.

See the Swagger page at {che-host}/swagger/#/organization-resource for more detailed specification of response objects and required parameters.

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
}