Previewing apps

You can preview apps that are running in IBM® Cloud Shell just like you would if you were running them locally. The Cloud Shell web preview makes your app UI or endpoint available at a URL that only you can access. This gives you a chance to view changes to your app before you deploy it to a publicly accessible location.

Before you begin

Enable Web preview in the IBM Cloud console. For more information about how to enable web preview, see Enabling or disabling Cloud Shell features for an account.

Web preview ports

You can preview an app by clicking the Web preview icon in the Cloud Shell menu bar. Web preview is available for any app that listens to HTTP requests on the following ports:

3000
8080
8081
8082
8083
8084
9080

As with your local system, only one app can run on each port at any time. If you have multiple apps that are listening on the same port, it results in port conflicts.

Previewing apps running directly in Cloud Shell

Cloud Shell includes lots of plug-ins, tools, and runtimes that you can use to work with apps that you're developing. Because Cloud Shell storage is temporary, the easiest way to work with an app is to first copy or clone it to your Cloud Shell workspace, make any changes, and then preview it.

The following example workflow shows how you can preview a Node.js Express sample app that's hosted in a GitHub repository.

In a Cloud Shell session, clone your app source to your home directory.
```
git clone https://github.com/IBM/nodejs-express-app.git
```
Then, change to the directory where your app was cloned.
```
cd nodejs-express-app
```
At this point, you can make any changes to your app code, such as by using the vim text editor.
Start your app in Cloud Shell.

To start this Node.js sample app, you first need to download any project dependencies.
```
npm install
```
Then, you can start the app so that it's running on a web server in Cloud Shell.
```
npm run start
```
After the app starts, note the port where your web server is listening. The port must be one of the available ports to be able to preview it in Cloud Shell. When this sample app starts, it outputs the following information, which shows that it's listening on port 3000.
```
> nodejsexpressapp@1.0.0 start /home/my-user-name/nodejs-express-app
> node server/server.js

App UI available http://localhost:3000
Swagger UI available http://localhost:3000/swagger/api-docs
```
In the Cloud Shell menu bar, click the Web preview icon , and select the port where your server is listening. For the Node.js sample app, select 3000.

Your web preview opens in a new browser window and shows the equivalent of http://localhost:3000. You should see the first screen of your app's UI.

If you see a message that says there's nothing to preview in Cloud Shell, the server where your app is running isn't listening on the selected port. Verify that your server is listening on the port that you're previewing, and refresh the preview page.

Now that you're previewing your app, you can see any changes you make by restarting the app if needed and refreshing the page. Be sure to commit any changes back to your GitHub repo or otherwise download your changes because your workspace storage is temporary.

Previewing apps running in a Kubernetes pod

You can also use Cloud Shell to preview apps that are running in Kubernetes, such as a Prometheus dashboard or your typical web app. Because apps that are running in a pod in a Kubernetes cluster use an internal port, you need to expose the pod's port either by creating a service or setting up port forwarding.

If you create a service, you need to expose the service publicly, set up authentication to secure access, and set up an application load balancer (ALB) for the service. For more information, see Connecting applications with services.

If you're doing app development and testing, port forwarding is a simpler way to be able to quickly preview apps in your cluster. It requires much less up-front configuration, but you also have to reconfigure it whenever the pod restarts. The following steps walk you through setting up port forwarding and previewing an app that's running in a IBM Cloud Kubernetes Service cluster.

In a Cloud Shell session, set the cluster where your app is running as the context. This enables you to use kubectl commands to work with your cluster. For more information, see Installing the CLI.
Find the name of the pod where your app is running.
```
kubectl get pods
```
The pod name is listed under the NAME column, for example my-pod-123abc.
```
NAME            READY   STATUS    RESTARTS   AGE
my-pod-123abc   1/1     Running   0          9d
```

Find the port in the pod that you want to expose by running the kubectl describe command on the pod.

kubectl describe pod my-pod-123abc

Under the Containers section, the local port is listed as the Port value, such as 6000 in the following example.

Containers:
  cluster-agent:
  Container ID:   containerd://1234abcd5678efab90cde603e4ba6986fdaf26daae94c4f309
  Image:          us.icr.io/my-registry/my-image:0.5.0-dev.0.1234
  Image ID:       us.icr.io/my-registry/my-image@sha256:abc123def456abc789def012
  Port:           6000/TCP
  Host Port:      0/TCP

Set up port forwarding by running the kubectl port-forward command. Be sure to select one of the available ports for web preview in Cloud Shell.

For example, the following command listens on port 8080 locally and forwards it to port 6000 within the pod.
```
kubectl port-forward pod/my-pod-123abc 8080:6000
```
Now that port forwarding is set up, you can preview your app.
In the Cloud Shell menu bar, click the Web preview icon , and select the port that's being forwarded to your pod.

Your web preview opens in a new browser window. You should see the first screen of your app's UI.

If you see a message that says there's nothing to preview in Cloud Shell, the server where your app is running isn't listening on the selected port. Verify that your server is listening on the pod's internal port and that you're forwarding the port that you're previewing to the correct internal port.

Previewing other endpoints on a port

After you open the web preview, you can view any other endpoints that your server is listening for on the same port. The web preview opens at a URL that's the equivalent to http://localhost:<port>. To view another endpoint, add the path to the web preview URL.

For example, the Node.js sample app outputs the following URLs:

App UI available http://localhost:3000
Swagger UI available http://localhost:3000/swagger/api-docs

To view the Swagger UI, add /swagger/api-docs to the web preview URL:

https://p3000-abcd1234-ef56-a1b2-b122-a122560ba24f.dp3.us-south.shell.cloud.ibm.com/swagger/api-docs