OSDOCS-347 Bring forward Creating new applications content

modules/applications-create-using-cli-source-code.adoc

@@ -0,0 +1,173 @@
+// Module included in the following assemblies:
+//
+// * applications/creating-new-applications.adoc
+
+[id="applications-create-using-cli-source-code-{context}"]
+= Creating an application from source code 
+
+With the `new-app` command you can create applications from source code in a
+local or remote Git repository.
+
+The `new-app` command creates a build configuration, which itself creates a new
+application image from your source code. The `new-app` command typically also
+creates a deployment configuration to deploy the new image, and a service to
+provide load-balanced access to the deployment running your image.
+
+{product-title} automatically detects whether the `Pipeline` or `Source`
+build strategy should be used, and in the case of `Source` builds,
+detects an appropriate language builder image.
+
+== Local
+
+To create an application from a Git repository in a local directory:
+
+----
+$ oc new-app /<path to source code>
+----
+
+[NOTE]
+====
+If you use a local Git repository, the repository must have a remote named
+`origin` that points to a URL that is accessible by the {product-title} cluster. If
+there is no recognized remote,  running the `new-app` command will create a binary build.
+====
+
+== Remote
+
+To create an application from a remote Git repository:
+
+----
+$ oc new-app https://github.com/sclorg/cakephp-ex
+----
+
+To create an application from a private remote Git repository:
+
+----
+$ oc new-app https://github.com/youruser/yourprivaterepo --source-secret=yoursecret
+----
+
+[NOTE]
+====
+If you use a private remote Git repository, you can use the `--source-secret` flag
+to specify an existing source clone secret that will get injected into your
+`BuildConfig` to access the repository.
+====
+
+You can use a subdirectory of your source code repository by specifying a
+`--context-dir` flag. To create an application from a remote Git repository and
+a context subdirectory:
+
+----
+$ oc new-app https://github.com/sclorg/s2i-ruby-container.git \
+    --context-dir=2.0/test/puma-test-app
+----
+
+Also, when specifying a remote URL, you can specify a Git branch to use by
+appending `#<branch_name>` to the end of the URL:
+
+----
+$ oc new-app https://github.com/openshift/ruby-hello-world.git#beta4
+----
+
+== Build strategy detection
+
+If a `Jenkinsfile` exists in the root or specified context directory of the
+source repository when creating a new application, {product-title} generates a
+Pipeline build strategy.
+
+Otherwise, it generates a Source build strategy.
+
+Override the build strategy by setting the `--strategy` flag to either
+`pipeline` or `source`.
+
+----
+$ oc new-app /home/user/code/myapp --strategy=docker
+----
+
+[NOTE]
+====
+The `oc` command requires that files containing build sources are available in a
+remote Git repository. For all source builds, you must use `git remote -v`.
+====
+
+== Language Detection
+
+If you use the `Source` build strategy, `new-app` attempts to determine the
+language builder to use by the presence of certain files in the root or
+specified context directory of the repository:
+
+.Languages Detected by `new-app`
+[cols="4,8",options="header"]
+|===
+
+|Language |Files
+ifdef::openshift-enterprise,openshift-dedicated,openshift-aro,openshift-online[]
+|`dotnet`
+|`project.json`, `pass:[*.csproj]`
+endif::[]
+|`jee`
+|`pom.xml`
+
+|`nodejs`
+|`app.json`, `package.json`
+
+|`perl`
+|`cpanfile`, `index.pl`
+
+|`php`
+|`composer.json`, `index.php`
+
+|`python`
+|`requirements.txt`, `setup.py`
+
+|`ruby`
+|`Gemfile`, `Rakefile`, `config.ru`
+
+|`scala`
+|`build.sbt`
+
+|`golang`
+|`Godeps`, `main.go`
+|===
+
+After a language is detected, `new-app` searches the {product-title} server for
+imagestreamtags that have a `supports` annotation matching the detected language,
+or an imagestream that matches the name of the detected language. If a match is
+not found, `new-app` searches the link:https://registry.hub.docker.com[Docker Hub
+registry] for an image that matches the detected language based on name.
+
+You can override the image the builder uses for a particular source
+repository by specifying the image, either an imagestream or container
+specification, and the repository with a `~` as a separator. Note that if this
+is done, build strategy detection and language detection are not carried out.
+
+For example, to use the `myproject/my-ruby` imagestream with the source in a
+remote repository:
+
+----
+$ oc new-app myproject/my-ruby~https://github.com/openshift/ruby-hello-world.git
+----
+
+To use the `openshift/ruby-20-centos7:latest `container imagestream with
+the source in a local repository:
+
+----
+$ oc new-app openshift/ruby-20-centos7:latest~/home/user/code/my-ruby-app
+----
+
+[NOTE]
+====
+Language detection requires the Git client to be locally installed so that your
+repository can be cloned and inspected. If Git is not available, you can avoid
+the language detection step by specifying the builder image to use with your
+repository with the `<image>~<repository>` syntax.
+
+The `-i <image> <repository>` invocation requires that `new-app` attempt
+to clone `repository` in order to determine what type of artifact it is, so this
+will fail if Git is not available.
+
+The `-i <image> --code <repository>` invocation requires
+`new-app` clone `repository` in order to determine whether `image` should be
+used as a builder for the source code, or deployed separately, as in the case of
+a database image.
+====