odo

README

+++
<img align="right" role="right" width="180" src="/docs/img/openshift.png?raw=true"/>
+++
[id="readme"]
= `odo` - Developer-focused CLI for OpenShift
:toc: macro
:toc-title:
:toclevels: 1

toc::[]

https://travis-ci.org/openshift/odo[image:https://travis-ci.org/openshift/odo.svg?branch=master[Build
Status]]
https://codecov.io/gh/openshift/odo[image:https://codecov.io/gh/openshift/odo/branch/master/graph/badge.svg[codecov]]
https://circleci.com/gh/openshift/odo/tree/master[image:https://circleci.com/gh/openshift/odo/tree/master.svg?style=svg[CircleCI]]


[[overview]]
== Overview

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

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, thus allowing developers to focus on what is most important to them: code.

[[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 project, application, and component.
* Completely client based. No server is required within the OpenShift cluster for deployment.
* Supports multiple languages and frameworks such as Node.js, Java, 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 available components and services from the OpenShift cluster.

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

=== Prerequisites:

OpenShift 3.10.0 or above is required.

=== Procedure:

==== Mac and Linux

===== OS-independent automated installation for Mac and Linux systems

Use this link:./scripts/installer.sh[bash script] to quickly install `odo`. It will automatically detect your operating system and install `odo` accordingly.

----
$ curl -L https://github.com/openshift/odo/raw/master/scripts/installer.sh | bash
----

===== Binary installation for Mac OS

----
# curl -L https://github.com/openshift/odo/releases/latest/download/odo-darwin-amd64 -o /usr/local/bin/odo && chmod +x /usr/local/bin/odo
----

===== Binary installation for Linux

----
# curl -L https://github.com/openshift/odo/releases/latest/download/odo-linux-amd64 -o /usr/local/bin/odo && chmod +x /usr/local/bin/odo
----

For more installation options please refer the link:docs/installation.adoc[installation page].

==== Windows

In order to correctly use `odo` you must download it and add it
to your `PATH` environment variable:

. Download the `odo-windows-amd64.exe.gz` file from the
link:https://github.com/openshift/odo/releases[GitHub releases page].
. Extract the file.
. Add the location of extracted binary to your `PATH` environment
variable by following the steps listed in this link:https://github.com/openshift/odo/wiki/Setting-PATH-variable-on-Windows[Wiki page].

Visit the link:docs/installation.adoc#windows[installation page] for instructions to set the `PATH` environment variable on Windows 7, 8 or 10.

[[demonstration]]
== Demonstration

The following demonstration provides an overview of `odo`:

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

[[deploying-an-application]]
== Deploying an application using `odo`

After installing `odo`, follow these steps to build, push, and
deploy a Node.js application. Examples for other supported languages and runtimes can be found link:https://github.com/openshift/odo/blob/master/docs/examples.adoc[here].

These steps recommend using link:https://github.com/minishift/minishift[Minishift] for running an OpenShift 3.10.0 or above cluster locally. More information on how to install and use `Minishift` can be found link:https://docs.okd.io/latest/minishift/getting-started/index.html[here].

. Start a local OpenShift development cluster by using `Minishift`.
+
----
$ minishift start
----
. Log into the OpenShift cluster.
+
----
$ odo login -u developer -p developer
----
. Download the Node.js sample code and change directory to the
location of the sample code.
+
----
$ git clone https://github.com/openshift/nodejs-ex
$ cd nodejs-ex
----
. Add a component of type `nodejs` to your application.
+
----
$ odo create nodejs
----
. Deploy your application.
+
----
$ odo push
----
. Create a URL to access the application and visit it to test it.
+
----
$ odo url create --port <application port>
$ curl <generated URL>
----
. When finished, remove your component from `Minishift` and stop your `Minishift` cluster.
+
----
$ odo delete <component>
$ minishift stop
----

For more in-depth information and advanced use-cases such as adding storage to a component or linking components, see the
link:https://learn.openshift.com/introduction/developing-with-odo/[interactive tutorial] or the link:/docs/getting-started.adoc[Getting Started Guide].

[[additional-documentation]]
== Additional documentation

Additional documentation can be found below:

* link:https://github.com/openshift/odo/blob/master/docs/installation.adoc[Detailed
Installation Guide]
* link:https://github.com/openshift/odo/blob/master/docs/getting-started.adoc[Getting
Started Guide]
* link:https://github.com/openshift/odo/blob/master/docs/examples.adoc[Usage
Examples for Other Languages and Runtimes]
* link:https://github.com/openshift/odo/blob/master/docs/cli-reference.adoc[CLI
Reference]
* link:https://github.com/openshift/odo/blob/master/docs/development.adoc[Development
Guide]

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

*Discussions:* For any discussions or help with `odo`, open a link:https://github.com/openshift/odo/issues[GitHub issue].

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

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

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