Search
SupportConsoleDevelopersStart a trialContact

Chapter 2. Installing CodeReady Workspaces on OpenShift v3

download PDF

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

  1. Change to a temporary directory. Create it if necessary. For example: 

    $ mkdir ~/tmp
$ cd ~/tmp
  2. 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.

  3. 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 objectName of the object that the installer createsDescriptionPermission 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

  1. 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.

  2. Open the OpenShift web console.
  3. In the My Projects pane, click workspaces.

  4. Click Applications > Pods. The pods are shown running.

    Figure 2.1. Pods for codeready shown running

    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:

  1. 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.

  2. 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:

  1. 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.

  2. 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.

  3. Run the deploy script: 

    $ ./deploy.sh --deploy

Additional resources

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:

  1. 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

  2. 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:

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

  4. 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

Procedure

  1. 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.

  2. 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.
Red Hat logoGithubRedditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.