Getting Started Guide

Procedure

1. Download the latest release of CodeReady Containers for your platform.
2. On Microsoft Windows, extract the contents of the archive.

3. On macOS or Microsoft Windows, run the guided installer and follow the instructions.

   Note

   On Microsoft Windows, you must install CodeReady Containers to your local C:\ drive. You cannot run CodeReady Containers from a network drive.

   On Red Hat Enterprise Linux, assuming the archive is in the ~/Downloads directory, follow these steps:

   1. Extract the contents of the archive:

      $ cd ~/Downloads
      $ tar xvf crc-linux-amd64.tar.xz

   2. Create the ~/bin directory if it does not exist and copy the crc executable to it:

      $ mkdir -p ~/bin
      $ cp ~/Downloads/crc-linux-*-amd64/crc ~/bin

   3. Add the ~/bin directory to your $PATH:

      $ export PATH=$PATH:$HOME/bin
      $ echo 'export PATH=$PATH:$HOME/bin' >> ~/.bashrc

Procedure

1. Download the latest release of CodeReady Containers.

2. Delete the existing CodeReady Containers virtual machine:

   $ crc delete

   Warning

   The crc delete command results in the loss of data stored in the CodeReady Containers virtual machine. Save any desired information stored in the virtual machine before running this command.

3. Replace the earlier crc executable with the executable of the latest release. Verify that the new crc executable is in use by checking its version:

   $ crc version

4. Set up the new CodeReady Containers release:

   $ crc setup

5. Start the new CodeReady Containers virtual machine:

   $ crc start

Procedure

1. Set up your host machine for CodeReady Containers:

   $ crc setup

Procedure

1. Start the CodeReady Containers virtual machine:

   $ crc start

2. When prompted, supply your user pull secret.

   Note

   The cluster takes a minimum of four minutes to start the necessary containers and Operators before serving a request.

Procedure

1. Log in to the running CodeReady Containers OpenShift cluster as the developer user:

   $ odo login -u developer -p developer

2. Create a project for your application:

   $ odo project create sample-app

3. Create a directory for your components:

   $ mkdir sample-app
   $ cd sample-app

4. Create a component from a sample application on GitHub:

   $ odo create nodejs --s2i --git https://github.com/openshift/nodejs-ex

   Note

   Creating a component from a remote Git repository will rebuild the application each time you run the odo push command. To create a component from a local Git repository, see Creating a single-component application with odo in the odo documentation.

5. Create a URL and add an entry to the local configuration file:

   $ odo url create --port 8080

6. Push the changes:

   $ odo push

   Your component is now deployed to the cluster with an accessible URL.

7. List the URLs and check the desired URL for the component:

   $ odo url list

8. View the deployed application using the generated URL.

Procedure

1. Define a proxy using the http_proxy and https_proxy environment variables or using the crc config set command as follows:

   $ crc config set http-proxy http://proxy.example.com:<port>
   $ crc config set https-proxy http://proxy.example.com:<port>
   $ crc config set no-proxy <comma-separated-no-proxy-entries>

2. If the proxy uses a custom CA certificate file, set it as follows:

   $ crc config set proxy-ca-file <path-to-custom-ca-file>

Procedure

1. Start the cluster:

   $ crc start

   Ensure that the cluster remains running during this procedure.

2. Install the haproxy package and other utilities:

   $ sudo dnf install haproxy /usr/sbin/semanage

3. Modify the firewall to allow communication with the cluster:

   $ sudo systemctl start firewalld
   $ sudo firewall-cmd --add-port=80/tcp --permanent
   $ sudo firewall-cmd --add-port=6443/tcp --permanent
   $ sudo firewall-cmd --add-port=443/tcp --permanent
   $ sudo systemctl restart firewalld

4. For SELinux, allow listening to TCP port 6443:

   $ sudo semanage port -a -t http_port_t -p tcp 6443

5. Create a backup of the default haproxy configuration:

   $ sudo cp /etc/haproxy/haproxy.cfg{,.bak}

6. Configure haproxy for use with the cluster:

   $ export CRC_IP=$(crc ip)
   $ sudo tee /etc/haproxy/haproxy.cfg &>/dev/null <<EOF
   global
       log /dev/log local0
   
   defaults
       balance roundrobin
       log global
       maxconn 100
       mode tcp
       timeout connect 5s
       timeout client 500s
       timeout server 500s
   
   listen apps
       bind 0.0.0.0:80
       server crcvm $CRC_IP:80 check
   
   listen apps_ssl
       bind 0.0.0.0:443
       server crcvm $CRC_IP:443 check
   
   listen api
       bind 0.0.0.0:6443
       server crcvm $CRC_IP:6443 check
   EOF

7. Start the haproxy service:

   $ sudo systemctl start haproxy

Procedure

1. Install the dnsmasq package:

   $ sudo dnf install dnsmasq

2. Enable the use of dnsmasq for DNS resolution in NetworkManager:

   $ sudo tee /etc/NetworkManager/conf.d/use-dnsmasq.conf &>/dev/null <<EOF
   [main]
   dns=dnsmasq
   EOF

3. Add DNS entries for CodeReady Containers to the dnsmasq configuration:

   $ sudo tee /etc/NetworkManager/dnsmasq.d/external-crc.conf &>/dev/null <<EOF
   address=/apps-crc.testing/SERVER_IP_ADDRESS
   address=/api.crc.testing/SERVER_IP_ADDRESS
   EOF

   Note

   Comment out any existing entries in /etc/NetworkManager/dnsmasq.d/crc.conf. These entries are created by running a local instance of CodeReady Containers and will conflict with the entries for the remote cluster.

4. Reload the NetworkManager service:

   $ sudo systemctl reload NetworkManager

5. Log in to the remote cluster as the developer user with oc:

   $ oc login -u developer -p developer https://api.crc.testing:6443

   The remote OpenShift Web Console is available at https://console-openshift-console.apps-crc.testing.

Procedure

1. Set the enable-cluster-monitoring configurable property to true:

   $ crc config set enable-cluster-monitoring true

2. Start the virtual machine:

   $ crc start

   Warning

   Cluster monitoring cannot be disabled. To remove monitoring, alerting, and telemetry, set the enable-cluster-monitoring configurable property to false and delete the existing CodeReady Containers virtual machine.

Procedure

1. Run the oc get nodes command to identify the desired node. The output will be similar to this:

   $ oc get nodes
   NAME                 STATUS   ROLES           AGE    VERSION
   crc-shdl4-master-0   Ready    master,worker   7d7h   v1.14.6+7e13ab9a7

2. Run oc debug nodes/<node> where <node> is the name of the node printed in the previous step.

1. Download the latest CodeReady Containers release and place the crc executable in your $PATH.

2. Remove the cluster with certificate errors using the crc delete command:

   $ crc delete

   Warning

   The crc delete command results in the loss of data stored in the CodeReady Containers virtual machine. Save any desired information stored in the virtual machine before running this command.

3. Set up the new release:

   $ crc setup

4. Start the new virtual machine:

   $ crc start

Procedure

1. Issue the crc delete command before attempting to start the instance:

   $ crc delete

   Warning

   The crc delete command results in the loss of data stored in the CodeReady Containers virtual machine. Save any desired information stored in the virtual machine before running this command.

1. Stop the CodeReady Containers virtual machine:

   $ crc stop

2. Delete the CodeReady Containers virtual machine:

   $ crc delete

   Warning

   The crc delete command results in the loss of data stored in the CodeReady Containers virtual machine. Save any desired information stored in the virtual machine before running this command.

3. Clean up remaining changes from the crc setup command:

   $ crc cleanup

   Note

   The crc cleanup command removes an existing CodeReady Containers virtual machine and reverts changes to DNS entries created by the crc setup command. On macOS, the crc cleanup command also removes the system tray.

4. Set up your host machine to reapply the changes:

   $ crc setup

5. Start the CodeReady Containers virtual machine:

   $ crc start

   Note

   The cluster takes a minimum of four minutes to start the necessary containers and Operators before serving a request.

1. Search open issues for the issue that you are encountering.
2. If no existing issue addresses the encountered issue, create an issue and attach the ~/.crc/crc.log file to the created issue. The ~/.crc/crc.log file has detailed debugging and troubleshooting information which can help diagnose the problem that you are experiencing.