odo/README.adoc

[id="readme"]
= `odo` - Developer-focused CLI for OpenShift and Kubernetes
:toc: macro
:toc-title:
:toclevels: 1

https://github.com/openshift/odo/releases/latest[image:https://img.shields.io/github/v/release/openshift/odo?style=for-the-badge[GitHub release]]
https://travis-ci.com/openshift/odo[image:https://img.shields.io/travis/com/openshift/odo?style=for-the-badge[Build Status]]
image:https://img.shields.io/github/license/openshift/odo?style=for-the-badge[License]


[[overview]]
== Overview

`odo` is a fast, iterative, and straightforward CLI tool for developers who write, build, and deploy applications on OpenShift and Kubernetes.

Existing tools such as `oc` are more operations-focused and require a deep-understanding of Kubernetes and OpenShift concepts. `odo` abstracts away complex Kubernetes and OpenShift concepts for the developer.

[[key-features]]
== Key features

`odo` is designed to be simple and concise with the following key features:

* Simple syntax and design centered around concepts familiar to developers, such as projects, applications, and components.
* Completely client based. No server is required within the cluster for deployment.
* Official support for Node.js and Java components.
* Partial compatibility with languages and frameworks such as Ruby, Perl, PHP, and Python. 
* Detects changes to local code and deploys it to the cluster automatically, giving instant feedback to validate changes in real time.
* Lists all the available components and services from the cluster.

[id="odo-supported-languages-and-images"]
=== Officially supported languages and corresponding container images

.Supported container images
[cols=",,",options="header",]
|===
|Language |Container Image |Supported Package Manager
|*Node.js*
|https://github.com/sclorg/s2i-nodejs-container[centos/nodejs-8-centos7]
|NPM

| |https://access.redhat.com/articles/3376841[rhoar-nodejs/nodejs-8]
|NPM

|
|https://www.github.com/bucharest-gold/centos7-s2i-nodejs[bucharestgold/centos7-s2i-nodejs]
|NPM

|
|https://access.redhat.com/containers/#/registry.access.redhat.com/rhscl/nodejs-8-rhel7[rhscl/nodejs-8-rhel7]
|NPM

|
|https://access.redhat.com/containers/#/registry.access.redhat.com/rhscl/nodejs-10-rhel7[rhscl/nodejs-10-rhel7]
|NPM

|*Java*
|https://access.redhat.com/containers/#/registry.access.redhat.com/redhat-openjdk-18/openjdk18-openshift[redhat-openjdk-18/openjdk18-openshift]
|Maven, Gradle

|
|https://access.redhat.com/containers/#/registry.access.redhat.com/openjdk/openjdk-11-rhel8[openjdk/openjdk-11-rhel8]
|Maven, Gradle

|
|https://access.redhat.com/containers/#/registry.access.redhat.com/openjdk/openjdk-11-rhel7[openjdk/openjdk-11-rhel7]
|Maven, Gradle
|===

[id="odo-listing-available-images"]
==== Listing available container images

[NOTE]
====
The list of available container images is sourced from the cluster's internal container registry and external registries associated with the cluster.
====

To list the available components and associated container images for your cluster:

. Access your cluster. Authentication with `odo login` for Kubernetes clusters is currently not supported. For OpenShift cluster, you can authenticate with `odo login`: 
+
----
$ odo login -u developer -p developer
----

. List the available `odo` supported and unsupported components and corresponding container images:
+
----------------------------------------------------
$ odo catalog list components
Odo Supported OpenShift Components:
NAME        PROJECT      TAGS      
java       openshift     8,latest
nodejs     openshift     10,8,8-RHOAR,latest
Odo Unsupported OpenShift Components:
NAME                      PROJECT       TAGS
dotnet                    openshift     1.0,1.1,2.1,2.2,latest
fuse7-eap-openshift       openshift     1.3
----------------------------------------------------
+
The `TAGS` column represents the available image versions, for example, `10` represents the `rhoar-nodejs/nodejs-10` container image.

[[official-documentation]]
== Official documentation

* link:https://docs.openshift.com/container-platform/latest/cli_reference/openshift_developer_cli/installing-odo.html[Installing odo]
* link:https://docs.openshift.com/container-platform/latest/cli_reference/openshift_developer_cli/odo-architecture.html[Odo architecture]
* link:https://docs.openshift.com/container-platform/latest/cli_reference/openshift_developer_cli/creating-a-single-component-application-with-odo.html[Creating a single-component application with odo]
* link:https://docs.openshift.com/container-platform/latest/cli_reference/openshift_developer_cli/creating-a-multicomponent-application-with-odo.html[Creating a multicomponent application with odo]
* link:https://docs.openshift.com/container-platform/latest/cli_reference/openshift_developer_cli/creating-an-application-with-a-database.html[Creating an application with a database]
* link:https://docs.openshift.com/container-platform/latest/cli_reference/openshift_developer_cli/configuring-the-odo-cli.html[Configuring the odo CLI]
* link:https://docs.openshift.com/container-platform/latest/cli_reference/openshift_developer_cli/odo-cli-reference.html[odo CLI reference]
* link:https://docs.openshift.com/container-platform/latest/cli_reference/openshift_developer_cli/odo-release-notes.html[odo release notes]

[[installing-odo]]
== Installing `odo`

To install on Linux / Windows / macOS follow our guide located on link:https://docs.openshift.com/container-platform/latest/cli_reference/openshift_developer_cli/installing-odo.html[docs.openshift.com]. All binaries and tarballs are synced between our link:https://github.com/openshift/odo/releases[GitHub releases] and link:https://mirror.openshift.com/pub/openshift-v4/clients/odo/[OpenShift mirrors].

[[deploying-your-first-application]]
== Deploying your first application

Click on the tutorial below to deploy your first `odo` application:

link:https://docs.openshift.com/container-platform/latest/cli_reference/openshift_developer_cli/creating-a-single-component-application-with-odo.html[Creating a single-component application with odo]

The following demonstration provides an overview of `odo`:

https://asciinema.org/a/wVkVgUrO7PGR5CYBFbHB5fFDn[image:https://asciinema.org/a/wVkVgUrO7PGR5CYBFbHB5fFDn.svg[asciicast]]

[[contributing]]
== Community, discussion, contribution, and support


=== Communication channels

*Discussions:*

* For general help and inquiries, join our link:https://groups.google.com/forum/#!forum/odo-users[odo-users Google group].
* For any developmental discussion, use our link:https://groups.google.com/forum/#!forum/odo-dev[odo-dev Google group].

*Chat:* Join us on link:https://join.slack.com/t/openshiftdo/shared_invite/enQtODUwMjIzMzE2MjYyLWM3YjlkNTViOGNjZGQ5YjFlMzc2N2RhZjVmMDQ5NWY5ZDQ3NzMzZjYxMTE1MjY5OTVmZjgxZWMyMGRmOTc4Y2I[Slack].

*Issues:* If you have an issue with `odo`, please link:https://github.com/openshift/odo/issues[file it].

*Documentation Issues*: If you have any documentation issues related to the link:https://docs.openshift.com[docs.openshift.com] site, file an issue in link:https://bugzilla.redhat.com/[Bugzilla]. Choose the OpenShift Container Platform product type and the Documentation component type.

=== Contributing
Want to become a contributor and submit your code?
Please have a look at our link:https://github.com/openshift/odo/blob/master/docs/dev/development.adoc[Development Guide].

We work in 3-week sprint cycles. On a week when the sprint starts we have two planning calls:

* "Sprint Planning Preparation and Issue Triage" - on Monday
* "Sprint Planning" - on Wednesday

On top of our sprint planning calls, we have our regular "odo contributors call" (biweekly on Tuesdays). This is where we discuss technical challenges and anything related to odo development.

All our calls are open to public. You are welcome to join any of our calls.

You can find the exact dates of all scheduled odo calls together with sprint dates in the link:https://calendar.google.com/calendar/embed?src=gi0s0v5ukfqkjpnn26p6va3jfc%40group.calendar.google.com[odo calendar] (link:https://calendar.google.com/calendar/ical/gi0s0v5ukfqkjpnn26p6va3jfc%40group.calendar.google.com/public/basic.ics[iCal format]).

To participate in the calls, please join link:https://groups.google.com/forum/#!forum/odo-dev[odo-dev Google group]. When you join the group, you will automatically get invites to all odo related calls and get permissions to all necessary documents.


[[projects-using-odo]]
== Projects using odo

These are some of the IDE plugins which use odo:

* link:https://marketplace.visualstudio.com/items?itemName=redhat.vscode-openshift-connector[VS Code Openshift Connector]
* link:http://plugins.jetbrains.com/plugin/12030-openshift-connector-by-red-hat[Openshift Connector for Intellij]
* link:https://www.eclipse.org/codewind[Codewind for Eclipse Che]

[[experimental-mode]]
== Experimental mode

Want to try out the odo experimental mode? Please read the link:https://github.com/openshift/odo/blob/master/docs/dev/experimental-mode.adoc[document] for more information.

[[glossary]]
== Glossary

*Application:* An application consists of multiple microservices or components that work individually to build the entire application.

*Component:* A component is similar to a microservice. Multiple components make up an application. A component has different attributes like storage. `odo` supports multiple component types like nodejs, perl, php, python, and ruby.

*Service:* Typically a service is a database or a service that a
component links to or depends on. For example: MariaDB, Jenkins, MySQL.
This comes from the OpenShift Service Catalog and must be enabled within your cluster.