Add quick start guides for new adopters (#87)

* hello world example guide for odo added. Signed-off-by: Michael Valdron <mvaldron@redhat.com> * hello world example guide for che added. Signed-off-by: Michael Valdron <mvaldron@redhat.com> * refactored navigation to place 'Get started' under each version. Signed-off-by: Michael Valdron <mvaldron@redhat.com> * fix odo docs link Signed-off-by: Michael Valdron <mvaldron@redhat.com> * remove command groups reference from hello world guides to make version neutral Signed-off-by: Michael Valdron <mvaldron@redhat.com> * remove authoring overview from additional resources of hello world examples to be version neutral Signed-off-by: Michael Valdron <mvaldron@redhat.com> * hotReloadCapable description updated. Signed-off-by: Michael Valdron <mvaldron@redhat.com> * Add directions to hello world starter guides on setting up the devtools as the first steps. Signed-off-by: Michael Valdron <mvaldron@redhat.com> * Update libs/docs/src/docs/2.1.0/helloworld-example-che.md Correct Prerequisites spelling mistake Co-authored-by: Michael Hoang <35011707+mike-hoang@users.noreply.github.com> Signed-off-by: Michael Valdron <mvaldron@redhat.com> * Update libs/docs/src/docs/no-version/helloworld-example-odo.md Correct Prerequisites spelling mistake Co-authored-by: Michael Hoang <35011707+mike-hoang@users.noreply.github.com> Signed-off-by: Michael Valdron <mvaldron@redhat.com> * fix Express.js title in starter references. Signed-off-by: Michael Valdron <mvaldron@redhat.com> * fix 'EXPLORER' spelling mistake. Signed-off-by: Michael Valdron <mvaldron@redhat.com> * Hello world example title changed to Quick start with odo and Quick start with Eclipse Che. Signed-off-by: Michael Valdron <mvaldron@redhat.com> * fences reflecting changes converted to diff fences. Signed-off-by: Michael Valdron <mvaldron@redhat.com> * Add optional step to quick start guides for setting up minikube as a local cluster. Signed-off-by: Michael Valdron <mvaldron@redhat.com> * remove kubectl and oc requirements from 'Quick start with odo v3' guide as odo has its own login and logout commands. Signed-off-by: Michael Valdron <mvaldron@redhat.com> * docker removed as a requirement from quick start guides as image building is not present and cluster using docker is optional. Signed-off-by: Michael Valdron <mvaldron@redhat.com> * increase visibility of optional but recommended step to use 'odo init' in quick start guide. Signed-off-by: Michael Valdron <mvaldron@redhat.com> * Update libs/docs/src/docs/2.1.0/quickstart-che.md Correct developer sandbox title. Co-authored-by: Angel Misevski <amisevsk@redhat.com> Signed-off-by: Michael Valdron <mvaldron@redhat.com> * correct Eclipse Che version for 2.1.0 version of the 'Quick start with Eclipse Che' guide. Signed-off-by: Michael Valdron <mvaldron@redhat.com> * remove line that states Eclipse Che currently supports 2.1.0 in 'Quick start with Eclipse Che' guide. Signed-off-by: Michael Valdron <mvaldron@redhat.com> * explaination of 'metadata.name' field added to 'Quick start with Eclipse Che'. Signed-off-by: Michael Valdron <mvaldron@redhat.com> * 2.1.0 'Quick start with Eclipse Che' converted into 'Quick start with OpenShift Dev Spaces' Signed-off-by: Michael Valdron <mvaldron@redhat.com> * new 2.2.0 'Quick start with Eclipse Che' added. Signed-off-by: Michael Valdron <mvaldron@redhat.com> * rewrite for using a local devfile within Eclipse Che Signed-off-by: Michael Valdron <mvaldron@redhat.com> * Update libs/docs/src/docs/2.2.0/quickstart-che.md container component revisions: * rename 'runtime' to 'dev-tooling' * change image tag 'ubi8-latest' to 'latest' Co-authored-by: Mario Loriedo <mario.loriedo@gmail.com> Signed-off-by: Michael Valdron <mvaldron@redhat.com> * Update libs/docs/src/docs/2.2.0/quickstart-che.md expand description of `universal-developer-image` to add more context to why Eclipse Che uses it Co-authored-by: Mario Loriedo <mario.loriedo@gmail.com> Signed-off-by: Michael Valdron <mvaldron@redhat.com> * Update libs/docs/src/docs/2.2.0/quickstart-che.md reword opening to defining commands in Eclipse Che to improve clarity of why it is done Co-authored-by: Mario Loriedo <mario.loriedo@gmail.com> Signed-off-by: Michael Valdron <mvaldron@redhat.com> * Update libs/docs/src/docs/2.2.0/quickstart-che.md revise 'id' description to not refer to it as a 'label' to avoid confusion with the 'label' field Co-authored-by: Mario Loriedo <mario.loriedo@gmail.com> Signed-off-by: Michael Valdron <mvaldron@redhat.com> * Update libs/docs/src/docs/2.2.0/quickstart-che.md remove incorrect note about execution order of commands, Eclipse Che executes commands individually with the user manually triggering them Co-authored-by: Mario Loriedo <mario.loriedo@gmail.com> Signed-off-by: Michael Valdron <mvaldron@redhat.com> * reword the item instructing schema version use for Eclipse Che Signed-off-by: Michael Valdron <mvaldron@redhat.com> * removes quick start guide for OpenShift Dev Spaces and references of it replaced with a guide from the Eclipse Che documentation for getting started with 'Eclipse Che hosted by Red Hat' Signed-off-by: Michael Valdron <mvaldron@redhat.com> * add Quick start with Eclipse Che guide under all versions. Signed-off-by: Michael Valdron <mvaldron@redhat.com> * references to the quick start guides added to other pages related to the new developer persona. Signed-off-by: Michael Valdron <mvaldron@redhat.com> --------- Signed-off-by: Michael Valdron <mvaldron@redhat.com> Co-authored-by: Michael Hoang <35011707+mike-hoang@users.noreply.github.com> Co-authored-by: Angel Misevski <amisevsk@redhat.com> Co-authored-by: Mario Loriedo <mario.loriedo@gmail.com>
devfile · May 26, 2023 · ca17714 · ca17714
1 parent fa72999
commit ca17714
Show file tree

Hide file tree

Showing 7 changed files with 463 additions and 17 deletions.
diff --git a/libs/core/src/types/devfile-spec.ts b/libs/core/src/types/devfile-spec.ts
@@ -221,9 +221,12 @@ export interface PurpleExec {
      */
     group?: TentacledGroup;
     /**
-     * Whether the command is capable to reload itself when source code changes. If set to
-     * `true` the command won't be restarted and it is expected to handle file changes on its
-     * own.
+     * Specify whether the command is restarted or not when the source code changes. If set to
+     * `true` the command won't be restarted. A *hotReloadCapable* `run` or `debug` command is
+     * expected to handle file changes on its own and won't be restarted. A *hotReloadCapable*
+     * `build` command is expected to be executed only once and won't be executed again. This
+     * field is taken into account only for commands `build`, `run` and `debug` with `isDefault`
+     * set to `true`.
      *
      * Default value is `false`
      */
@@ -1104,9 +1107,12 @@ export interface FluffyExec {
      */
     group?: IndecentGroup;
     /**
-     * Whether the command is capable to reload itself when source code changes. If set to
-     * `true` the command won't be restarted and it is expected to handle file changes on its
-     * own.
+     * Specify whether the command is restarted or not when the source code changes. If set to
+     * `true` the command won't be restarted. A *hotReloadCapable* `run` or `debug` command is
+     * expected to handle file changes on its own and won't be restarted. A *hotReloadCapable*
+     * `build` command is expected to be executed only once and won't be executed again. This
+     * field is taken into account only for commands `build`, `run` and `debug` with `isDefault`
+     * set to `true`.
      *
      * Default value is `false`
      */

diff --git a/libs/docs/src/docs/no-version/application-developer.md b/libs/docs/src/docs/no-version/application-developer.md
@@ -28,3 +28,7 @@ The inner-loop and outer-loop instructions defined in the devfile allow you to t
 - [API reference](./devfile-schema)
 
 - [Community registry viewer](https://registry.devfile.io/viewer)
+
+- [Quick start with odo v3](./quickstart-odo)
+
+- [Quick start with Eclipse Che](./quickstart-che)
diff --git a/libs/docs/src/docs/no-version/developing-with-devfiles.md b/libs/docs/src/docs/no-version/developing-with-devfiles.md
@@ -15,20 +15,15 @@ To get a better understanding of what devfiles can help build, take a look at a
 - Use the devfile specification to develop a Node.js “Hello World”
 application using `odo`. Developing this application introduces you to how a devfile
 automates and simplifies your development process.
-
-Get started with [odo](https://odo.dev/docs/user-guides/quickstart/nodejs).
-
+    - [Quick start with odo v3](./quickstart-odo)
+    - Get started with [odo](https://odo.dev/docs/user-guides/quickstart/nodejs).
 - Create a workspace in `Eclipse Che` with a community sample backed by the devfile specification to start building your application in the language of your choice.
-
-Get started with [Eclipse Che](https://www.eclipse.org/che/).
-
+    - [Quick start with Eclipse Che](./quickstart-che)
+    - Get started with [Eclipse Che](https://www.eclipse.org/che/).
 - Use blueprints in `Amazon CodeCatalyst` to quickly build a "Modern three-tier web application". Start working on the source code with a Dev Environment that uses a devfile to pre-determine and install the required project tools and application libraries.
-
-Get started with [Amazon CodeCatalyst](https://docs.aws.amazon.com/codecatalyst/latest/userguide/getting-started-template-project.html).
-
+    - Get started with [Amazon CodeCatalyst](https://docs.aws.amazon.com/codecatalyst/latest/userguide/getting-started-template-project.html).
 - Set up a remote development environment that links to your Git repository using `JetBrains Space Cloud Dev` and the devfile specification.
-
-Get started with [JetBrains Space Cloud Dev Environments](https://blog.jetbrains.com/space/2022/10/26/get-started-with-space-dev-environments/).
+    - Get started with [JetBrains Space Cloud Dev Environments](https://blog.jetbrains.com/space/2022/10/26/get-started-with-space-dev-environments/).
 
 
 ## Tools that provide devfile support

diff --git a/libs/docs/src/docs/no-version/enterprise-architect-and-runtime-provider.md b/libs/docs/src/docs/no-version/enterprise-architect-and-runtime-provider.md
@@ -25,6 +25,10 @@ Add the necessary policy settings and compliance policies as part of the devfile
 
 - [Overview](./overview)
 
+- [Quick start with odo v3](./quickstart-odo)
+
+- [Quick start with Eclipse Che](./quickstart-che)
+
 - [Onboarding process and requirements of the community registry](https://github.com/devfile/registry/blob/main/CONTRIBUTING.md)
 
 - [Community registry viewer](https://registry.devfile.io/viewer)
diff --git a/libs/docs/src/docs/no-version/quickstart-che.md b/libs/docs/src/docs/no-version/quickstart-che.md
@@ -0,0 +1,209 @@
+---
+title: "Quick start with Eclipse Che"
+description: "Quick start with Eclipse Che"
+---
+
+This guide will run through creating a simple hello world devfile project using Eclipse Che. The purpose of this guide is to provide a practical introduction to those just starting out with devfiles.
+
+## Prerequisites
+
+- Eclipse Che 7.65.x
+- `kubectl` or `oc`
+- Access to a Kubernetes or OpenShift cluster
+
+## Procedure
+
+1. Obtain access to Eclipse Che if you do not already have it, as an individual this can be done by setting up a [local instance of Eclipse Che](https://www.eclipse.org/che/docs/stable/administration-guide/installing-che-locally/)
+    - You can use `minikube` to run your cluster locally, follow [these](https://minikube.sigs.k8s.io/docs/start/) steps to get started
+    - An alternative is to use the [Eclipse Che hosted by Red Hat](https://developers.redhat.com/developer-sandbox/ide), see 
+    [the corresponding guide](https://www.eclipse.org/che/docs/stable/hosted-che/hosted-che/) in Eclipse Che documentation if this method is used
+
+2. For this quick start guide, we will create a simple [hello world Express.js](https://expressjs.com/en/starter/hello-world.html) application
+
+3. In Eclipse Che, create an empty workspace
+
+4. Create the files which make up the simple [hello world Express.js](https://expressjs.com/en/starter/hello-world.html) application
+
+    ```json {% title="package.json file" filename="package.json" %}
+    {
+        "name": "helloworld-devfile",
+        "version": "1.0.0",
+        "description": "",
+        "main": "app.js",
+        "type": "module",
+        "dependencies": {
+            "@types/express": "^4.17.17",
+            "express": "^4.18.2"
+        }
+    }
+    ```
+
+    ```js {% title="Application source code" filename="app.js" %}
+    import express from "express"
+
+    const PORT = 3000
+    const app = express()
+
+    app.get("/", (req, res) => {
+        res.send("Hello world!")
+    })
+
+    app.listen(PORT, () => {
+        console.log(`Listening on port ${PORT}..`)
+    })
+    ```
+
+5. Create a devfile with the filename `.devfile.yaml`. The devfile should be populated with content similar to the following
+    - The `schemaVersion` of the devfile can to set to the desired devfile specification version to use
+        - It is recommended to use the latest release, currently `2.2.0`
+    - The `metadata.name` field is the name of the workspace for the project
+
+        ```yaml {% filename=".devfile.yaml" %}
+        schemaVersion: <version>
+        metadata:
+          name: helloworld-example
+        ```
+
+6. Next, create the first component to serve as the dev environment for the project, for this use the [`container`](./devfile-schema#components-container) component with the name `dev-tooling` and the `quay.io/devfile/universal-developer-image:latest` image
+    - `name` is the identifier used to refer to the component
+    - `image` is the container image to use for the component, `quay.io/devfile/universal-developer-image` is the default development tooling image used by Eclipse Che with multiple programming languages supports (including Node.js).
+
+        ```diff {% filename=".devfile.yaml" %}
+         schemaVersion: <version>
+         metadata:
+           name: helloworld-example
+        +components:
+        +  - name: dev-tooling
+        +    container:
+        +      image: quay.io/devfile/universal-developer-image:ubi8-latest
+        ```
+
+7. The `dev-tooling` container will host the expressjs app which listens on port `3000`, define this port in the component by specifying an entry 
+under [`endpoints`](./devfile-schema#components-container-endpoints)
+    - Each endpoint has at least a `name` to identify them and the `targetPort` to specify the port number to forward
+
+        ```diff {% filename=".devfile.yaml" %}
+         schemaVersion: <version>
+         metadata:
+           name: helloworld-example
+         components:
+           - name: dev-tooling
+             container:
+               image: quay.io/devfile/universal-developer-image:ubi8-latest
+        +      endpoints:
+        +        - name: http-3000
+        +          targetPort: 3000
+        ```
+
+8. Now that the `dev-tooling` container is defined, [`commands`](./devfile-schema#commands) are useful to add in the IDE (the default is VS Code) some UI elements to guide developers during the development cycle. Define the command to install the dependencies needed to run the application (`npm install`)
+    - The `id` field identifies the command so that it can be referenced in events or composite commands.
+    - An [`exec`](./devfile-schema#commands-exec) command specifies explicit shell command(s) to run on a given `component`
+    - `commandLine` defines the shell command(s) to execute as part of that devfile command
+    - The `group` specifies what `kind` of command it is or if it is the default of its kind, `isDefault`
+
+        ```yaml {% title="Install command" %}
+        commands:
+          - id: install
+            exec:
+              commandLine: npm install
+              component: dev-tooling
+              workingDir: ${PROJECT_SOURCE}
+              group:
+                isDefault: true
+                kind: build
+        ```
+
+9. Next, define the command to run the application (`node app.js`)
+
+    ```yaml {% title="Run command" %}
+    commands:
+      - id: run
+        exec:
+          commandLine: node app.js
+          component: dev-tooling
+          workingDir: ${PROJECT_SOURCE}
+          group:
+            isDefault: true
+            kind: run
+    ```
+
+10. Now the devfile is ready to be used to run the application with Eclipse Che
+
+    ```yaml {% title="Complete Workspace Devfile" filename=".devfile.yaml"  %}
+    schemaVersion: <version>
+    metadata:
+      name: helloworld-example
+    components:
+      - name: dev-tooling
+        container:
+          image: quay.io/devfile/universal-developer-image:ubi8-latest
+          endpoints:
+            - name: http-3000
+              targetPort: 3000
+    commands:
+      - id: install
+        exec:
+          commandLine: npm install
+          component: dev-tooling
+          workingDir: ${PROJECT_SOURCE}
+          group:
+            isDefault: true
+            kind: build
+      - id: run
+        exec:
+          commandLine: node app.js
+          component: dev-tooling
+          workingDir: ${PROJECT_SOURCE}
+          group:
+            isDefault: true
+            kind: run
+    ```
+
+11. Click 'Eclipse Che' in the bottom left corner, then select 'Eclipse Che: Restart Workspace from Local Devfile' to reload the workspace
+with the new devfile
+
+12. Once the workspace has finished restarting, run the `install` command by opening the menu, open 'Terminal/Run Task', under the 'Run Task' menu open 'devfile/devfile: install', the task should open
+a terminal with the following
+
+    ``` {% title="Output of running the 'install' command in Che" %}
+     *  Executing task: devfile: install 
+
+
+    added 67 packages, and audited 68 packages in 8s
+
+    7 packages are looking for funding
+      run `npm fund` for details
+
+    found 0 vulnerabilities
+    npm notice 
+    npm notice New major version of npm available! 8.3.1 -> 9.6.5
+    npm notice Changelog: https://github.com/npm/cli/releases/tag/v9.6.5
+    npm notice Run npm install -g npm@9.6.5 to update!
+    npm notice 
+     *  Terminal will be reused by tasks, press any key to close it. 
+    ```
+
+13. Run the application with the `run` command by going through the same steps as `install` but under the 'Run Task' menu open 'devfile/devfile: run', the task should open
+    - The `run` command will execute until the user interrupts it, such as killing it with *Ctrl-C*
+
+    ``` {% title="Output of running the 'run' command in Che" %}
+     *  Executing task: devfile: run 
+
+    Listening on port 3000..
+    ```
+
+14. Under the 'EXPLORER', expand the 'ENDPOINTS' panel and copy the `http-3000` endpoint URL
+
+15. Paste the endpoint URL in a new tab and the response should just show "Hello World!"
+
+16. (Optional) Normally when creating a workspace it is recommended to use a sample under 'Select a Sample' from the embedded devfile registry to 
+start your project, a similar devfile project workspace can be created using the 'Node.js Express Web Application' sample
+
+17. Congratulations! You have written your first devfile project with Eclipse Che!
+
+## Additional Resources
+
+- [Devfile Schema](./devfile-schema)
+- [Adding components](./adding-components)
+- [Adding commands](./adding-commands)
+- [Eclipse Che docs](https://www.eclipse.org/che/docs/stable/overview/introduction-to-eclipse-che/)