Installing Che on Minishift

This article explains how to create a single-node OpenShift 3 cluster with Minishift to deploy Che.

Remember that single-node OpenShift clusters are suited only for testing or single-user development. Do NOT use such clusters to run Che for organizations or developer teams.

Using Minishift to set up OpenShift 3

This section describes how to use Minishift to set up OpenShift 3.

Prerequisites
Procedure
  • Start Minishift with at least 4 GB of RAM:

    $ minishift start --memory=4096

When deploying Che on Minishift, it is necessary to manually generate TLS certificates for use by the Che server.

Generating self-signed TLS certificates

This section describes how to prepare self-signed TLS certificates to use with Che on Minishift.

Prerequisites
  • The expected domain name where the Che deployment is planned. Typically, for Minishift, this is $(minishift ip).nip.io

  • The location of the openssl.cnf file on the target machine.

    Table 1. Usual OpenSSL configuration file locations
    Linux distribution File location

    Fedora, Red Hat Enterprise Linux, CentOS

    /etc/pki/tls/openssl.cnf

    Debian, Ubuntu, Mint, Arch Linux

    /etc/ssl/openssl.cnf

Procedure
  1. Set the necessary environment variables:

    $ CA_CN="Local Eclipse Che Signer"
    $ DOMAIN=*.<expected.domain.com>
    $ OPENSSL_CNF=<path_to_openssl.cnf>
    Example (Fedora)
    $ CA_CN="Local Eclipse Che Signer"
    $ DOMAIN=\*.$( minishift ip ).nip.io
    $ OPENSSL_CNF=/etc/pki/tls/openssl.cnf
    Example (macOS)
    $ export CA_CN="Local Eclipse Che Signer"
    $ export DOMAIN=\*.$( minishift ip ).nip.io
    $ export OPENSSL_CNF=/System/Library/OpenSSL/openssl.cnf
  2. Generate the root Certificate Authority (CA) key. Add the -des3 parameter to use a passphrase:

    $ openssl genrsa -out ca.key 4096
  3. Generate the root CA certificate:

    $ openssl req -x509 \
      -new -nodes \
      -key ca.key \
      -sha256 \
      -days 1024 \
      -out ca.crt \
      -subj /CN="${CA_CN}" \
      -reqexts SAN \
      -extensions SAN \
      -config <(cat ${OPENSSL_CNF} \
          <(printf '[SAN]\nbasicConstraints=critical, CA:TRUE\nkeyUsage=keyCertSign, cRLSign, digitalSignature'))
  4. Generate the domain key:

    $ openssl genrsa -out domain.key 2048
  5. Generate the certificate signing request for the domain:

    $ openssl req -new -sha256 \
        -key domain.key \
        -subj "/O=Local Eclipse Che/CN=${DOMAIN}" \
        -reqexts SAN \
        -config <(cat ${OPENSSL_CNF} \
            <(printf "\n[SAN]\nsubjectAltName=DNS:${DOMAIN}\nbasicConstraints=critical, CA:FALSE\nkeyUsage=digitalSignature, keyEncipherment, keyAgreement, dataEncipherment\nextendedKeyUsage=serverAuth")) \
        -out domain.csr
  6. Generate the domain certificate:

    $ openssl x509 \
        -req \
        -sha256 \
        -extfile <(printf "subjectAltName=DNS:${DOMAIN}\nbasicConstraints=critical, CA:FALSE\nkeyUsage=digitalSignature, keyEncipherment, keyAgreement, dataEncipherment\nextendedKeyUsage=serverAuth") \
        -days 365 \
        -in domain.csr \
        -CA ca.crt \
        -CAkey ca.key \
        -CAcreateserial -out domain.crt

This procedure allows to use domain.crt and domain.key for TLS Route and Ingress, and ca.crt for importing into browsers.

Additional resources

Adding self-signed certificates to Minishift

This section describes how to add user-generated certificates to a Minishift cluster.

This method involves reconfiguration of the OpenShift router to use user-provided TLS certificates.
Prerequisites
Procedure
  1. Log in to the default OpenShift project:

    $ oc login -u system:admin --insecure-skip-tls-verify=true
    $ oc project default
  2. Reconfigure the router with the generated certificate:

    $ oc delete secret router-certs
    $ cat domain.crt domain.key > openshift.crt
    $ oc create secret tls router-certs --key=domain.key --cert=openshift.crt
    $ oc rollout latest router
  3. Create a namespace for Che:

    $ oc create namespace che
  4. Create a secret from the CA certificate:

    $ oc create secret generic self-signed-certificate --from-file=ca.crt -n=che
Additional resources

Installing Che on Minishift using chectl

This section describes how to install Che on Minishift using chectl.

Prerequisites
Procedure
  • Run the following command:

    $ chectl server:start --platform minishift --multiuser
    Omit the --multiuser option to install a single-user instance of Che.

Importing certificates to browsers

This section describes how to import a root certificate authority into a web browser to use Che with self-signed TLS certificates.

When a TLS certificate is not trusted, the error message Authorization token is missing. Click here to reload page blocks the login process. To prevent this, add the public part of the self-signed CA certificate into the browser after installing Che.

Adding certificates to Google Chrome on Linux or Windows

Procedure
  1. Navigate to URL where Che is deployed.

  2. Save the certificate:

    1. Click the warning or open lock icon on the left of the address bar.

    2. Click Certificates and navigate to the Details tab.

    3. Select the top-level certificate which is the Root certificate authority and export it:

      • On Linux, click the Export button.

      • On Windows, click the Save to file button.

  3. Go to Google Chrome Settings, then to the Authorities tab

  4. In the left panel, select Advanced and continue to Privacy and security.

  5. At the center of the screen, click Manage certificates and navigate to Authorities tab.

  6. Click the Import button and open the saved certificate file.

  7. Select Trust this certificate for identifying websites and click the OK button.

  8. After adding the Che certificate to the browser, the address bar displays the closed lock icon next to the URL, indicating a secure connection.

Adding certificates to Google Chrome and Safari on macOS

Procedure
  1. Navigate to URL where Che is deployed.

  2. Save the certificate:

    1. Click the lock icon on the left of the address bar.

    2. Click Certificates.

    3. Select the certificate to use and drag and drop its displayed large icon to the desktop.

  3. Open the Keychain Access application.

  4. Select the System keychain and drag and drop the saved certificate file to it.

  5. Double-click the imported CA, then go to Trust and select When using this certificate: Always Trust.

  6. Restart the browser for the added certificated to take effect.

Adding certificates to Firefox

Procedure
  1. Navigate to URL where Che is deployed.

  2. Save the certificate:

    1. Click the lock icon on the left of the address bar.

    2. Click the > button next to the Connection not secure warning.

    3. Click the More information button.

    4. Click the View Certificate button on the Security tab.

    5. Select the second certificate tab. The certificate Common Name should start with ingress-operator

    6. Click the PEM (cert) link and save the certificate.

  3. Navigate to about:preferences, search for certificates, and click View Certificates.

  4. Go to the Authorities tab, click the Import button, and open the saved certificate file.

  5. Check Trust this CA to identify websites and click OK.

  6. Restart Firefox for the added certificated to take effect.

  7. After adding the Che certificate to the browser, the address bar displays the closed lock icon next to the URL, indicating a secure connection.