Chapter 2. Installing CodeReady Workspaces on OpenShift v3

This section describes how to obtain installation files for Red Hat CodeReady Workspaces and how to use them to deploy the product on an instance of OpenShift (such as Red Hat OpenShift Container Platform) v3.

Prerequisites

Minimum hardware requirements

Minimum 5 GB RAM to run CodeReady Workspaces. The Red Hat Single Sign-On (Red Hat SSO) authorization server and the PostgreSQL database require extra RAM. CodeReady Workspaces uses RAM in the following distribution:
- The CodeReady Workspaces server: Approximately 750 MB
- Red Hat SSO: Approximately 1 GB
- PostgreSQL: Approximately 515 MB
- Workspaces: 2 GB of RAM per workspace. The total workspace RAM depends on the size of the workspace runtime(s) and the number of concurrent workspace pods.

Software requirements

CodeReady Workspaces deployment script and configuration file
Container images required for deployment:
- registry.access.redhat.com/codeready-workspaces/server:1.1
- registry.access.redhat.com/codeready-workspaces/server-operator:1.1
- registry.access.redhat.com/rhscl/postgresql-96-rhel7:1-25
- registry.access.redhat.com/redhat-sso-7/sso72-openshift:1.2-8
- registry.access.redhat.com/rhel7-minimal:7.6-154
Container images with preconfigured stacks for creating workspaces:
- registry.access.redhat.com/codeready-workspaces/stacks-java:latest
- registry.access.redhat.com/codeready-workspaces/stacks-node:latest
- registry.access.redhat.com/codeready-workspaces/stacks-php:latest
- registry.access.redhat.com/codeready-workspaces/stacks-python:latest
- registry.access.redhat.com/codeready-workspaces/stacks-dotnet:latest
- registry.access.redhat.com/codeready-workspaces/stacks-golang:latest
- registry.access.redhat.com/codeready-workspaces/stacks-java-rhel8:latest
- registry.access.redhat.com/codeready-workspaces/stacks-cpp:latest

Note

It is not necessary to download any of the referenced images manually.

All container images required for deployment are automatically downloaded by the CodeReady Workspaces deployment script.
Stack images are automatically downloaded by CodeReady Workspaces when new workspaces are created.

Other

In order to be able to download the CodeReady Workspaces deployment script, Red Hat asks that you register for the free Red Hat Developer Program. This allows you to agree to license conditions of the product. For instructions on how to obtain the deployment script, see Section 2.1, “Downloading the CodeReady Workspaces deployment script”.

2.1. Downloading the CodeReady Workspaces deployment script

This procedure describes how to obtain and unpack the archive with the CodeReady Workspaces deployment shell script.

The CodeReady Workspaces deployment script uses the OpenShift Operator to deploy Red Hat Single Sign-On, the PostgreSQL database, and the CodeReady Workspaces server container images on an instance of Red Hat OpenShift Container Platform. The images are available in the Red Hat Container Catalog.

Procedure

Change to a temporary directory. Create it if necessary. For example:
```
$ mkdir ~/tmp
$ cd ~/tmp
```
Download the archive with the deployment script and the custom-resource.yaml file using the browser with which you logged into the Red Hat Developer Portal: codeready-workspaces-1.1.0.GA-operator-installer.tar.gz.

Unpack the downloaded archive and change to the created directory:

$ tar xvf codeready-workspaces-1.1.0.GA-operator-installer.tar.gz \
  && cd codeready-workspaces-operator-installer/

Next steps

Continue by configuring and running the deployment script. See Section 2.2, “Running the CodeReady Workspaces deployment script”.

2.2. Running the CodeReady Workspaces deployment script

The CodeReady Workspaces deployment script uses command-line arguments and the custom-resource.yaml file to populate a set of configuration environment variables for the OpenShift Operator used for the actual deployment.

Prerequisites

Downloaded and unpacked deployment script and the configuration file. See Section 2.1, “Downloading the CodeReady Workspaces deployment script”.
A running instance of Red Hat OpenShift Container Platform 3.11 or OpenShift Dedicated 3.11. To install OpenShift Container Platform, see the Getting Started with OpenShift Container Platform guide.
The OpenShift command-line client tool, oc, is in the path.
The user is logged in to the OpenShift instance (using, for example, oc login).
CodeReady Workspaces is supported for use with Google Chrome 70.0.3538.110 (Official Build) (64bit).

cluster-admin rights to successfully deploy CodeReady Workspaces using the deploy script. The following table lists the objects and the required permissions:

Type of object	Name of the object that the installer creates	Description	Permission required
CRD	-	Custom Resource Definition - CheCluster	`cluster-admin`
CR	`codeready`	Custom Resource of the CheCluster type of object	`cluster-admin`. Alternatively, you can create a `clusterrole`.
ServiceAccount	`codeready-operator`	Operator uses this service account to reconcile CodeReady Workspaces objects	The edit role in a target namespace.
Role	`codeready-operator`	Scope of permissions for the operator-service account	`cluster-admin`
RoleBinding	`codeready-operator`	Assignment of a role to the service account	The edit role in a target namespace.
Deployment	`codeready-operator`	Deployment with operator image in the template specification	The edit role in a target namespace.
ClusterRole	`codeready-operator`	`ClusterRole` allows you to create, update, delete oAuthClients	`cluster-admin`
ClusterRoleBinding	`${NAMESPACE}-codeready-operator`	`ClusterRoleBinding` allows you to create, update, delete oAuthClients	`cluster-admin`
Role	`secret-reader`	`Role` allows you to read secrets in the router namespace	`cluster-admin`
RoleBinding	`${NAMESPACE}-codeready-operator`	`RoleBinding` allows you to read secrets in router namespace	`cluster-admin`

By default, the operator-service account gets privileges to list, get, watch, create, update, and delete ingresses, routes, service accounts, roles, rolebindings, PVCs, deployments, configMaps, secrets. It also has privileges to run execs into pods, watch events, and read pod logs in a target namespace.

With self-signed certificates support enabled, the operator-service account gets privileges to read secrets in an OpenShift router namespace.

With OpenShift oAuth enabled, the operator-service account gets privileges to get, list, create, update, and delete oAuthclients at a cluster scope.

Important

When using OpenShift Dedicated, contact Red Hat support and request the deployment of the application.

2.2.1. Deploying CodeReady Workspaces with default settings

Run the following command:

$ ./deploy.sh --deploy

Note

Run the ./deploy.sh --help command to get a list of all available arguments. For a description of all the options, see Section 2.5, “CodeReady Workspaces deployment script parameters”.

The following messages indicates that CodeReady Workspaces is getting installed:

[INFO]: Welcome to CodeReady Workspaces Installer
[INFO]: Found oc client in PATH
[INFO]: Checking if you are currently logged in...
[INFO]: Active session found. Your current context is: myproject/192-168-42-114:8443/developer
[WARNING]: Namespace 'workspaces' not found, or current user does not have access to it. Installer will try to create namespace 'workspaces'
[INFO]: Creating namespace "workspaces"
[INFO]: Namespace "workspaces" successfully created
[INFO]: Creating operator service account
[INFO]: Create service account roles
[INFO]: Creating Role Binding
[INFO]: Self-signed certificate support enabled
[INFO]: Adding extra privileges for an operator service account
[INFO]: Creating secret-reader role and rolebinding in namespace default
[INFO]: Creating role binding to let operator get secrets in namespace default
[INFO]: Creating custom resource definition
[INFO]: Creating Operator Deployment
[INFO]: Waiting for the Operator deployment to be scaled to 1
[INFO]: Codeready Operator successfully deployed
[INFO]: Creating Custom resource. This will initiate CodeReady Workspaces deployment
[INFO]: CodeReady is going to be deployed with the following settings:
[INFO]: TLS support:       false
[INFO]: OpenShift oAuth:   false
[INFO]: Self-signed certs: true
[INFO]: Waiting for CodeReady to boot. Timeout: 1200 seconds
[INFO]: CodeReady Workspaces successfully deployed and is available at http://codeready-workspaces.192.168.42.114.nip.io

The CodeReady Workspaces successfully deployed and available at <URL> message confirms that the deployment is successful.

Open the OpenShift web console.
In the My Projects pane, click workspaces.
Click Applications > Pods. The pods are shown running.
Figure 2.1. Pods for codeready shown running

2.2.2. Deploying CodeReady Workspaces with a self-signed certificate and OpenShift oAuth

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

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

Note

If you use the TLS mode with a self-signed certificate, ensure that your browser trusts the certificate. If it does not trust the certificate, the Authorization token is missed error is displayed on the login page and the running workspace may not work as intended.

2.2.3. Deploying CodeReady Workspaces with a public certificate

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

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

2.2.4. Deploying CodeReady Workspaces with external Red Hat Single Sign-On

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

Update the following values in the custom-resource.yaml file:
```
auth:
  externalKeycloak:  'true'                        1
  keycloakURL:       'https://my-red-hat-sso.com'  2
  keycloakRealm:     'myrealm'                     3
  keycloakClientId:  'myClient'                    4
```
1
Instructs the operator on whether or not to deploy the Red Hat SSO instance. When set to true, provisions the connection details.
2
Retrieved from the respective route or ingress unless explicitly specified in CR (when the externalKeycloak variable is true).
3
Name of a Red Hat SSO realm. This realm is created when the externalKeycloak variable is true. Otherwise, it is passed to the CodeReady Workspaces server.
4
The ID of a Red Hat SSO client. This client is created when the externalKeycloak variable is false. Otherwise, it is passed to the CodeReady Workspaces server.
Run the deploy script:
```
$ ./deploy.sh --deploy
```

2.2.5. Deploying CodeReady Workspaces with external Red Hat SSO and PostgreSQL

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

PostgreSQL and Red Hat SSO
Red Hat SSO only

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:

Update the following PostgreSQL database-related values in the custom-resource.yaml file:
```
database:
  externalDb:            'true'             1
  chePostgresHostname:   'http://postgres'  2
  chePostgresPort:       '5432'             3
  chePostgresUser:       'myuser'           4
  chePostgresPassword:   'mypass'           5
  chePostgresDb:         'mydb'             6
```
1
When set to true the operator skips deploying PostgreSQL and passes the connection details of the existing database to the CodeReady Workspaces server. Otherwise, a PostgreSQL deployment is created.
2
The PostgreSQL database hostname that the CodeReady Workspaces server uses to connect to. Defaults to postgres.
3
The PostgreSQL database port that the CodeReady Workspaces server uses to connect to. Defaults to 5432.
4
The PostgreSQL user that the CodeReady Workspaces server when making a database connection. Defaults to pgche.
5
The password of a PostgreSQL user. Auto-generated when left blank.
6
The PostgreSQL database name that the CodeReady Workspaces server uses to connect to. Defaults to dbche.
Update the following Red Hat SSO-related values in the custom-resource.yaml file:
```
auth:
  externalKeycloak:  'true'                        1
  keycloakURL:       'https://my-red-hat-sso.com'  2
  keycloakRealm:     'myrealm'                     3
  keycloakClientId:  'myClient'                    4
```
1
Instructs the operator on whether or not to deploy Red Hat SSO instance. When set to true, provisions the connection details.
2
Retrieved from the respective route or ingress unless explicitly specified in CodeReady Workspaces (when externalKeycloak is true).
3
Name of a Red Hat SSO realm. This realm is created when externalKeycloak is true. Otherwise, passed to the CodeReady Workspaces server.
4
ID of a Red Hat SSO client. This client is created when externalKeycloak is false. Otherwise, passed to the CodeReady Workspaces server.
Run the deploy script:
```
$ ./deploy.sh --deploy
```

Additional resources

See Section 2.5, “CodeReady Workspaces deployment script parameters” for definitions of the deployment script parameters.

2.3. Viewing CodeReady Workspaces installation logs

You can view the installation logs in the terminal or from the OpenShift console.

2.3.1. Viewing CodeReady Workspaces installation logs in the terminal

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

To obtain the names of the pods you must switch to project where CodeReady Workspaces is installed:

$ oc get pods -n=<OpenShift-project-name>

Following is an example output.

NAME                                 READY  STATUS    RESTARTS  AGE
codeready-operator-56bc9599cc-pkqkn  1/1    Running   0         25m
keycloak-666c5f9f4b-zz88z            1/1    Running   0         24m
postgres-96875bcbd-tfxr4             1/1    Running   0         25m
codeready-6b4876f56c-qdlll           1/1    Running   0         24m

To view the logs for the pod, run:

$ oc logs <log-name>

The following is an example output:

time="2019-03-29T12:22:31Z" level=info msg="Custom resource codeready updated"
time="2019-03-29T12:22:31Z" level=info msg="Updating codeready CR with status: CodeReady Workspaces server: Available"
time="2019-03-29T12:22:31Z" level=info msg="Custom resource codeready updated"
time="2019-03-29T12:22:31Z" level=info msg="Updating codeready CR with CodeReady Workspaces server URL: http://codeready-workspaces.192.168.42.114.nip.io"
time="2019-03-29T12:22:31Z" level=info msg="Custom resource codeready updated"
time="2019-03-29T12:22:31Z" level=info msg="CodeReady Workspaces is now available at: http://codeready-workspaces.192.168.42.114.nip.io"
time="2019-03-29T12:22:31Z" level=info msg="Updating codeready CR with version: 1.1-52"
time="2019-03-29T12:22:31Z" level=info msg="Custom resource codeready updated"

2.3.2. Viewing CodeReady Workspaces installation logs in the OpenShift console

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

Navigate to the OpenShift web console`.
In the My Projects pane, click workspaces.
Click Applications > Pods. Click the name of the pod for which you want to view the logs.

Click Logs and click Follow.

time="2019-03-29T12:22:31Z" level=info msg="Updating codeready CR with Keycloak URL status: http://keycloak-workspaces.192.168.42.114.nip.io "
time="2019-03-29T12:22:31Z" level=info msg="Custom resource codeready updated"
time="2019-03-29T12:22:31Z" level=info msg="Updating codeready CR with status: CodeReady Workspaces server: Available"
time="2019-03-29T12:22:31Z" level=info msg="Custom resource codeready updated"
time="2019-03-29T12:22:31Z" level=info msg="Updating codeready CR with CodeReady Workspaces server URL: http://codeready-workspaces.192.168.42.114.nip.io "
time="2019-03-29T12:22:31Z" level=info msg="Custom resource codeready updated"
time="2019-03-29T12:22:31Z" level=info msg="CodeReady Workspaces is now available at: http://codeready-workspaces.192.168.42.114.nip.io "
time="2019-03-29T12:22:31Z" level=info msg="Updating codeready CR with version: 1.1-52"
time="2019-03-29T12:22:31Z" level=info msg="Custom resource codeready updated"

2.4. Configuring CodeReady Workspaces to work behind an HTTPS proxy server

This procedure describes how to configure CodeReady Workspaces for use in a deployment behind a proxy server. To access external resources (for example, to download Maven artifacts to build Java projects), change the workspace configuration.

Prerequisites

OpenShift with logged-in oc client
Operator installer that you can obtain from https://github.com/redhat-developer/codeready-workspaces-deprecated/tree/6.19.x/operator-installer
Deployment parameters in the custom-resource.yaml reflecting the proxy setup

Procedure

Update the following values in the custom-resource.yaml file:

apiVersion: org.eclipse.che/v1
  kind: CheCluster
  metadata:
    name: codeready
  spec:
    server:
      cheFlavor: codeready
      cheImage: ${SERVER_IMAGE_NAME}
      cheImageTag: ${SERVER_IMAGE_TAG}
      tlsSupport: ${{TLS_SUPPORT}}
      selfSignedCert: ${{SELF_SIGNED_CERT}}
      proxyURL: 'http://172.19.20.128'
      proxyPort: '3128'
      nonProxyHosts: 'localhost|*.172.19.20.240.nip.io'
      proxyUser: ''
      proxyPassword: ''

Important

Ensure to use correct indentation as shown above.
Substitute http://172.19.20.128 for the protocol and hostname of your proxy server.
You may have to add a custom nonProxyHosts value as required by your network. In the preceding example this value is *.<routing-suffix> of an OpenShift Container Platform installation.
Substitute 3128 for the port of your proxy server.

Run the following command:
```
$ ./deploy.sh --deploy
```

2.5. CodeReady Workspaces deployment script parameters

The custom-resource.yaml file contains default values for the installation parameters. Those parameters that take environment variables as values can be overridden from a command line. Not all installation parameters are available as flags.

Before running the deployment script in a fast mode, review the custom-resource.yaml file. Run the ./deploy.sh --help command to get a list of all available arguments.

The following is an annotated example of the custom-resource.yaml file with all available parameters:

Server settings:

server:
      cheFlavor:        'codeready'              1
      cheImage:         '${SERVER_IMAGE_NAME}'   2
      cheImageTag:      '${SERVER_IMAGE_TAG}'    3
      tlsSupport:       '${{TLS_SUPPORT}}'       4
      selfSignedCert:   '${{SELF_SIGNED_CERT}}'  5
      proxyURL:         ''                       6
      proxyPort:        ''                       7
      nonProxyHosts:    ''                       8
      proxyUser:        ''                       9
      proxyPassword:    ''                      10

1: Defaults to che. When set to codeready, CodeReady Workspaces is deployed. The difference is in images, labels, and in exec commands.
2: The server image used in the Che deployment.
3: The tag of an image used in the Che deployment.
4: TLS mode for Che. Ensure that you either have public certificate or set the selfSignedCert environment variable to true. If you use the TLS mode with a self-signed certificate, ensure that your browser trusts the certificate. If it does not trust the certificate, the Authorization token is missed error is displayed on the login page and the running workspace may not work as intended.
5: When set to true, the operator attempts to get a secret in the OpenShift router namespace to add it to the ava trust store of the CodeReady Workspaces server. Requires cluster-administrator privileges for the operator service account.
6: The protocol and hostname of a proxy server. Automatically added as JAVA_OPTS variable and https(s)_proxy to the CodeReady Workspaces server and workspaces containers.
7: The port of a proxy server.
8: A list of non-proxy hosts. Use | as a delimiter. Example: localhost|my.host.com|123.42.12.32.
9: The username for a proxy server.
10: The password for a proxy user.

Storage settings:

storage:
      pvcStrategy:      'common'        1
      pvcClaimSize:     '1Gi'           2

1: The persistent volume claim strategy for the CodeReady Workspaces server. Can be common (all workspaces PVCs in one volume), per-workspace (one PVC per workspace for all the declared volumes), or unique (one PVC per declared volume). Defaults to common.
2: The size of a persistent volume claim for workspaces. Defaults to 1Gi.

Database settings:

database:
      externalDb:               'false'     1
      chePostgresHostName:      ''          2
      chePostgresPort:          ''          3
      chePostgresUser:          ''          4
      chePostgresPassword:      ''          5
      chePostgresDb:            ''          6

1: When set to true, the operator skips deploying PostgreSQL and passes the connection details of the existing database to the CodeReady Workspaces server. Otherwise, a PostgreSQL deployment is created.
2: The PostgreSQL database hostname that the CodeReady Workspaces server uses to connect to. Defaults to postgres.
3: The PostgreSQL database port that the CodeReady Workspaces server uses to connect to. Defaults to 5432.
4: The Postgres user that the CodeReady Workspaces server when making a databse connection. Defaults to pgche.
5: The password of a PostgreSQL user. Auto-generated when left blank.
6: The PostgreSQL database name that the CodeReady Workspaces server uses to connect to. Defaults to dbche.

auth settings:

auth:
      openShiftoAuth:          '${{ENABLE_OPENSHIFT_OAUTH}}'   1
      externalKeycloak:        'false'                         2
      keycloakAdminUserName:   'admin'                         3
      keycloakAdminPassword:   'admin'                         4
      keycloakURL:             ''                              5
      keycloakRealm:           ''                              6
      keycloakClientId:        ''                              7

1: Instructs an operator to enable the OpenShift v3 identity provider in Red Hat SSO and create the respective oAuthClient and configure the Che configMap accordingly.
2: Instructs the operator on whether or not to deploy the RH SSO instance. When set to true, it provisions the connection details.
3: The desired administrator username of the Red Hat SSO administrator (applicable only when the externalKeycloak variable is false).
4: The desired password of the Red Hat SSO administrator (applicable only when the externalKeycloak variable is false).
5: Retrieved from the respective route or ingress unless explicitly specified in CR (when the externalKeycloak variable is true).
6: The name of a Red Hat SSO realm. This realm is created when the externalKeycloak variable is true. Otherwise, it is passed to the CodeReady Workspaces server.
7: The ID of a Red Hat SSO client. This client is created when the externalKeycloak variable is false. Otherwise, it is passed to the CodeReady Workspaces server.

Chapter 2. Installing CodeReady Workspaces on OpenShift v3

2.1. Downloading the CodeReady Workspaces deployment script

2.2. Running the CodeReady Workspaces deployment script

2.2.1. Deploying CodeReady Workspaces with default settings

2.2.2. Deploying CodeReady Workspaces with a self-signed certificate and OpenShift oAuth

2.2.3. Deploying CodeReady Workspaces with a public certificate

2.2.4. Deploying CodeReady Workspaces with external Red Hat Single Sign-On

2.2.5. Deploying CodeReady Workspaces with external Red Hat SSO and PostgreSQL

2.3. Viewing CodeReady Workspaces installation logs

2.3.1. Viewing CodeReady Workspaces installation logs in the terminal

2.3.2. Viewing CodeReady Workspaces installation logs in the OpenShift console

2.4. Configuring CodeReady Workspaces to work behind an HTTPS proxy server

2.5. CodeReady Workspaces deployment script parameters

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

Making open source more inclusive

About Red Hat

Red Hat legal and privacy links

Red Hat legal and privacy links