Update Quickstart Guides with Podman support (#7016)

* Add section explaining that users can use Podman without a cluster * Update sample output of `npx express-generator` in Node.JS guide * Add section for preparing the target platform with tabs for Podman, Kubernetes and OpenShift On Podman, this means checking the prerequisites (e.g., min. version of odo, checking that Podman is detected with `odo version`). On Kubernetes and OpenShift, this is about creating a namespace or project, as before. * Update sample output for `odo dev` on cluster to reflect the current output * Add Podman as new tab when running `odo dev` and include sample outputs * Revert "Update sample output for `odo dev` on cluster to reflect the current output" This reverts commit 96fb449. * Fix typo in Quickstart intro
redhat-developer · Aug 4, 2023 · 1c6767e · 1c6767e
1 parent 84bfb22
commit 1c6767e
Show file tree

Hide file tree

Showing 11 changed files with 195 additions and 26 deletions.
diff --git a/...te/docs/user-guides/quickstart/docs-mdx/dotnet/dotnet_odo_dev_podman_output.mdx b/...te/docs/user-guides/quickstart/docs-mdx/dotnet/dotnet_odo_dev_podman_output.mdx
@@ -0,0 +1,24 @@
+```console
+$ odo dev --platform podman
+  __
+ /  \__     Developing using the "my-dotnet-app" Devfile
+ \__/  \    Platform: podman
+ /  \__/    odo version: v3.13.0
+ \__/
+
+↪ Running on podman in Dev mode
+ ✓  Deploying pod [14s]
+ ✓  Syncing files into the container [312ms]
+ ✓  Building your application in container (command: build) [7s]
+ •  Executing the application (command: run)  ...
+ ✓  Waiting for the application to be ready [1s]
+ -  Forwarding from 127.0.0.1:20001 -> 3000
+
+↪ Dev mode
+ Status:
+ Watching for changes in the current directory /home/user/quickstart-demo
+
+ Keyboard Commands:
+[Ctrl+c] - Exit and delete resources from podman
+     [p] - Manually apply local changes to the application on podman
+```
diff --git a/docs/website/docs/user-guides/quickstart/docs-mdx/go/go_odo_dev_podman_output.mdx b/docs/website/docs/user-guides/quickstart/docs-mdx/go/go_odo_dev_podman_output.mdx
@@ -0,0 +1,24 @@
+```console
+$ odo dev --platform podman
+  __
+ /  \__     Developing using the "my-go-app" Devfile
+ \__/  \    Platform: podman
+ /  \__/    odo version: v3.13.0
+ \__/
+
+↪ Running on podman in Dev mode
+ ✓  Deploying pod [14s]
+ ✓  Syncing files into the container [312ms]
+ ✓  Building your application in container (command: build) [422ms]
+ •  Executing the application (command: run)  ...
+ ✓  Waiting for the application to be ready [1s]
+ -  Forwarding from 127.0.0.1:20001 -> 3000
+
+↪ Dev mode
+ Status:
+ Watching for changes in the current directory /home/user/quickstart-demo
+
+ Keyboard Commands:
+[Ctrl+c] - Exit and delete resources from podman
+     [p] - Manually apply local changes to the application on podman
+```
diff --git a/...ebsite/docs/user-guides/quickstart/docs-mdx/java/java_odo_dev_podman_output.mdx b/...ebsite/docs/user-guides/quickstart/docs-mdx/java/java_odo_dev_podman_output.mdx
@@ -0,0 +1,24 @@
+```console
+$ odo dev --platform podman
+  __
+ /  \__     Developing using the "my-java-app" Devfile
+ \__/  \    Platform: podman
+ /  \__/    odo version: v3.13.0
+ \__/
+
+↪ Running on podman in Dev mode
+ ✓  Deploying pod [6s]
+ ✓  Syncing files into the container [234ms]
+ ✓  Building your application in container (command: build) [43s]
+ •  Executing the application (command: run)  ...
+ ✓  Waiting for the application to be ready [1s]
+ -  Forwarding from 127.0.0.1:20001 -> 8080
+
+↪ Dev mode
+ Status:
+ Watching for changes in the current directory /home/user/quickstart-demo
+
+ Keyboard Commands:
+[Ctrl+c] - Exit and delete resources from podman
+     [p] - Manually apply local changes to the application on podman
+```
diff --git a/...te/docs/user-guides/quickstart/docs-mdx/nodejs/nodejs_odo_dev_podman_output.mdx b/...te/docs/user-guides/quickstart/docs-mdx/nodejs/nodejs_odo_dev_podman_output.mdx
@@ -0,0 +1,24 @@
+```console
+$ odo dev --platform podman
+  __
+ /  \__     Developing using the "my-nodejs-app" Devfile
+ \__/  \    Platform: podman
+ /  \__/    odo version: v3.13.0
+ \__/
+
+↪ Running on podman in Dev mode
+ ✓  Deploying pod [14s]
+ ✓  Syncing files into the container [312ms]
+ ✓  Building your application in container (command: install) [6s]
+ •  Executing the application (command: run)  ...
+ ✓  Waiting for the application to be ready [1s]
+ -  Forwarding from 127.0.0.1:20001 -> 3000
+
+↪ Dev mode
+ Status:
+ Watching for changes in the current directory /home/user/quickstart-demo
+
+ Keyboard Commands:
+[Ctrl+c] - Exit and delete resources from podman
+     [p] - Manually apply local changes to the application on podman
+```
diff --git a/docs/website/docs/user-guides/quickstart/docs-mdx/odo_dev_description.mdx b/docs/website/docs/user-guides/quickstart/docs-mdx/odo_dev_description.mdx
@@ -1,3 +1,6 @@
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
 Now that we've generated our code as well as our Devfile, let's start on development.
 
 `odo` uses [inner loop development](/docs/introduction#what-is-inner-loop-and-outer-loop) and allows you to code,
@@ -7,16 +10,47 @@ Once you run `odo dev`, you can freely edit code in your favourite IDE and watch
 
 <p>Let's run <code>odo dev</code> to start development on your <span>{props.framework}</span> application:</p>
 
-```console
-odo dev
-```
+<Tabs groupId="quickstart">
 
-Then wait a few seconds until `odo dev` displays `Forwarding from 127.0.0.1:...` in its output,
-meaning that `odo` has successfully set up the port forwarding to reach the application running in the container.
+  <TabItem value="podman" label="Podman">
+
+  ```console
+  odo dev --platform podman
+  ```
+<details>
+    <summary>Sample Output</summary>
+    {props.devpodmanout}
+</details>
+
+  </TabItem>
+
+  <TabItem value="kubernetes" label="Kubernetes">
+
+  ```console
+  odo dev
+  ```
+<details>
+    <summary>Sample Output</summary>
+    {props.devout}
+</details>
+
+  </TabItem>
 
+  <TabItem value="openshift" label="OpenShift">
+
+  ```console
+  odo dev
+  ```
 <details>
     <summary>Sample Output</summary>
     {props.devout}
 </details>
 
-You can now access the application via the local port displayed by `odo dev` ([127.0.0.1:20001](http://127.0.0.1:20001) in the sample output above) and start your development loop. `odo` will watch for changes and push the code for real-time updates.
+  </TabItem>
+</Tabs>
+
+Then wait a few seconds until `odo dev` displays `Forwarding from 127.0.0.1:...` in its output,
+meaning that `odo` has successfully set up port forwarding to reach the application running in the container.
+
+You can now access the application via the local port displayed by `odo dev` ([127.0.0.1:20001](http://127.0.0.1:20001) in the sample output above) and start your development loop.
+`odo` will watch for changes and push the code for real-time updates.
diff --git a/...connecting_to_the_cluster_description.mdx → ...ocs-mdx/preparing_the_target_platform.mdx b/...connecting_to_the_cluster_description.mdx → ...ocs-mdx/preparing_the_target_platform.mdx
@@ -5,9 +5,38 @@ import CreateProjectOutput from './create_project_output.mdx';
 
 
 <Tabs groupId="quickstart">
+
+  <TabItem value="podman" label="Podman">
+
+Before starting on Podman, you should have Podman installed and configured properly on your machine.
+See [Podman installation instructions](https://podman.io/docs/installation) for further details.
+
+You also need `odo` [3.8.0](/blog/odo-v3.8.0#odo-on-podman-out-of-experimental-mode) or later.
+
+To make sure that `odo` has the appropriate version and detects your local Podman,
+run the command below and check that it reports the Podman Client version.
+
+```console
+odo version
+```
+<details>
+    <summary>Sample Output</summary>
+
+```console
+$ odo version
+ ⚠  unable to fetch the cluster server version
+odo v3.13.0 (6c1c8b2a1)
+
+Podman Client: 4.6.0
+```
+
+</details>
+
+  </TabItem>
+
   <TabItem value="kubernetes" label="Kubernetes">
 
-Before starting you should make sure that odo is connected to your cluster and that you have created a new namespace.
+Before starting, you should make sure that odo is connected to your cluster and that you have created a new namespace.
 
 ### Creating a new namespace
 
@@ -26,7 +55,7 @@ odo create namespace odo-dev
   </TabItem>
   <TabItem value="openshift" label="OpenShift">
 
-Before starting you should make sure that odo is connected to your cluster and that you have created a new project.
+Before starting, you should make sure that odo is connected to your cluster and that you have created a new project.
 
 ### Login to OpenShift Cluster
 

diff --git a/docs/website/docs/user-guides/quickstart/dotnet.md b/docs/website/docs/user-guides/quickstart/dotnet.md
@@ -44,11 +44,11 @@ Restore succeeded.
 Your source code has now been generated and created in the directory.
 
 
-## Step 1. Connect to your cluster and create a new namespace or project
+## Step 1. Preparing the target platform
 
-import ConnectingToCluster from './docs-mdx/connecting_to_the_cluster_description.mdx';
+import PreparingTargetPlatform from './docs-mdx/preparing_the_target_platform.mdx';
 
-<ConnectingToCluster/>
+<PreparingTargetPlatform/>
 
 ## Step 2. Initializing your application (`odo init`)
 
@@ -64,10 +64,11 @@ When you first run `odo init`, it will detect the required devfile to be 'dotnet
 ## Step 3. Developing your application continuously (`odo dev`)
 
 import DevSampleOutput from './docs-mdx/dotnet/dotnet_odo_dev_output.mdx';
+import DevPodmanSampleOutput from './docs-mdx/dotnet/dotnet_odo_dev_podman_output.mdx';
 
 import DevDescription from './docs-mdx/odo_dev_description.mdx';
 
-<DevDescription framework=".NET" devout=<DevSampleOutput/> />
+<DevDescription framework=".NET" devout=<DevSampleOutput/> devpodmanout=<DevPodmanSampleOutput/> />
 
 
 _You can now follow the [advanced guide](../advanced/deploy/dotnet.md) to deploy the application to production._
diff --git a/docs/website/docs/user-guides/quickstart/go.md b/docs/website/docs/user-guides/quickstart/go.md
@@ -49,11 +49,11 @@ go: to add module requirements and sums:
 
 Your source code has now been generated and created in the directory.
 
-## Step 1. Connect to your cluster and create a new namespace or project
+## Step 1. Preparing the target platform
 
-import ConnectingToCluster from './docs-mdx/connecting_to_the_cluster_description.mdx';
+import PreparingTargetPlatform from './docs-mdx/preparing_the_target_platform.mdx';
 
-<ConnectingToCluster/>
+<PreparingTargetPlatform/>
 
 ## Step 2. Initializing your application (`odo init`)
 
@@ -65,10 +65,11 @@ import InitDescription from './docs-mdx/odo_init_description.mdx';
 ## Step 3. Developing your application continuously (`odo dev`)
 
 import DevSampleOutput from './docs-mdx/go/go_odo_dev_output.mdx';
+import DevPodmanSampleOutput from './docs-mdx/go/go_odo_dev_podman_output.mdx';
 
 import DevDescription from './docs-mdx/odo_dev_description.mdx';
 
-<DevDescription framework="Go" devout=<DevSampleOutput/> />
+<DevDescription framework="Go" devout=<DevSampleOutput/> devpodmanout=<DevPodmanSampleOutput/> />
 
 
 _You can now follow the [advanced guide](../advanced/deploy/go.md) to deploy the application to production._
diff --git a/docs/website/docs/user-guides/quickstart/java.md b/docs/website/docs/user-guides/quickstart/java.md
@@ -26,11 +26,11 @@ Finally, extract the downloaded source code archive in the 'quickstart-demo' dir
 
 Your source code has now been generated and created in the directory.
 
-## Step 1. Connect to your cluster and create a new namespace or project
+## Step 1. Preparing the target platform
 
-import ConnectingToCluster from './docs-mdx/connecting_to_the_cluster_description.mdx';
+import PreparingTargetPlatform from './docs-mdx/preparing_the_target_platform.mdx';
 
-<ConnectingToCluster/>
+<PreparingTargetPlatform/>
 
 ## Step 2. Initializing your application (`odo init`)
 
@@ -43,9 +43,10 @@ import InitDescription from './docs-mdx/odo_init_description.mdx';
 ## Step 3. Developing your application continuously (`odo dev`)
 
 import DevSampleOutput from './docs-mdx/java/java_odo_dev_output.mdx';
+import DevPodmanSampleOutput from './docs-mdx/java/java_odo_dev_podman_output.mdx';
 
 import DevDescription from './docs-mdx/odo_dev_description.mdx';
 
-<DevDescription framework="Java (Spring Boot)" devout=<DevSampleOutput/> />
+<DevDescription framework="Java (Spring Boot)" devout=<DevSampleOutput/> devpodmanout=<DevPodmanSampleOutput/> />
 
 _You can now follow the [advanced guide](../advanced/deploy/java.md) to deploy the application to production._
diff --git a/docs/website/docs/user-guides/quickstart/nodejs.md b/docs/website/docs/user-guides/quickstart/nodejs.md
@@ -43,6 +43,7 @@ $ npx express-generator
   warning: the default view engine will not be jade in future releases
   warning: use `--view=jade' or `--help' for additional options
 
+destination is not empty, continue? [y/N] y
 
    create : public/
    create : public/javascripts/
@@ -71,11 +72,11 @@ $ npx express-generator
 
 Your source code has now been generated and created in the directory.
 
-## Step 1. Connect to your cluster and create a new namespace or project
+## Step 1. Preparing the target platform
 
-import ConnectingToCluster from './docs-mdx/connecting_to_the_cluster_description.mdx';
+import PreparingTargetPlatform from './docs-mdx/preparing_the_target_platform.mdx';
 
-<ConnectingToCluster/>
+<PreparingTargetPlatform/>
 
 ## Step 2. Initializing your application (`odo init`)
 
@@ -87,10 +88,11 @@ import InitDescription from './docs-mdx/odo_init_description.mdx';
 ## Step 3. Developing your application continuously (`odo dev`)
 
 import DevSampleOutput from './docs-mdx/nodejs/nodejs_odo_dev_output.mdx';
+import DevPodmanSampleOutput from './docs-mdx/nodejs/nodejs_odo_dev_podman_output.mdx';
 
 import DevDescription from './docs-mdx/odo_dev_description.mdx';
 
-<DevDescription framework="Node.JS" devout=<DevSampleOutput/> />
+<DevDescription framework="Node.JS" devout=<DevSampleOutput/> devpodmanout=<DevPodmanSampleOutput/> />
 
 
 _You can now follow the [advanced guide](../advanced/deploy/nodejs.md) to deploy the application to production._
diff --git a/docs/website/docs/user-guides/quickstart/quickstart.md b/docs/website/docs/user-guides/quickstart/quickstart.md
@@ -4,9 +4,14 @@ title: Quickstart Guide
 
 # Quickstart Guide
 
-In this guide, we will be using `odo` to create a "Hello World" application.
+In this guide, we will be using `odo` to create a "Hello World" application, and then start a container-based development session using `odo`.
 
-You have the option of choosing from the following frameworks for the quickstart guide:
+You have the option of developing and iterating locally against local [Podman](https://podman.io/) containers or any Kubernetes or OpenShift cluster.
+
+A recommended way to get started with `odo` is to iterate on the application locally with Podman, as it does not require any additional clusters to be setup or available.
+Later on, you can seamlessly run and iterate on the same application against a Kubernetes or OpenShift cluster.
+
+This quickstart guide will show you how easy it can be to get started with `odo`. You have the option of choosing from the following frameworks:
 * [Node.js](nodejs)
 * [.NET](dotnet)
 * [Java (Spring Boot)](java)