Skip to content

Commit

Permalink
Update docs for aio app dev (#333)
Browse files Browse the repository at this point in the history 
* initial-commit todos

* updated refs to wsk-dbg with dev command

* cleanup. some debug titles become wskdebug

* add dev page

* remove todo

* fixed nit

---------

Co-authored-by: Shazron Abdullah <[email protected]>
  • Loading branch information
@purplecabbage @shazron
purplecabbage and shazron authored Jun 25, 2024
1 parent 100c6b4 commit f3ea034
Show file tree
Hide file tree
Showing 13 changed files with 186 additions and 106 deletions.
2 changes: 1 addition & 1 deletion gatsby-config.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -519,7 +519,7 @@ module.exports = {
}]
},
{
title: 'Debugging App Builder Apps',
title: 'Debugging App Builder Apps With Wskdebug',
path: 'resources/debugging/index.md',
pages: [{
"title": "Requirements",
Expand Down
15 changes: 8 additions & 7 deletions src/pages/getting_started/common_troubleshooting.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,11 +14,11 @@ Here are troubleshooting guides for some of the most common issues as you develo
## Before you proceed

- Check your Node version and tool versions to ensure they are supported by App Builder and up-to-date. You can find the latest supported version [here](index.md).
- Check if your application is on Dropbox or OneDrive as file watchers sometimes cause unexpected errors.
- Check if your application is on Dropbox or OneDrive as file watchers sometimes cause unexpected errors.

## General debugging

When your action code doesn't work as expected, you may want to investigate into what exactly went wrong. App Builder provides the [Logging SDK](https://github.com/adobe/aio-lib-core-logging), please check out [App Builder's Application Logging](../guides/application_logging.md) for more details.
When your action code doesn't work as expected, you may want to investigate into what exactly went wrong. App Builder provides the [Logging SDK](https://github.com/adobe/aio-lib-core-logging), please check out [App Builder's Application Logging](../guides/application_logging.md) for more details.

To see the latest activations of your project, run this command:
```bash
Expand All @@ -30,7 +30,8 @@ It lists the most recent activations and summary (ID, start / end time, duration
* `application error`: this error is usually due to some issues at runtime, such as thrown exceptions, getting value of an `undefined` variable. With appropriate try-catch blocks and logging, you can see what goes wrong from the logs `aio runtime activation logs activationID`
* `internal error`: this could be an error caused by an external factor unrelated to the action itself, e.g. not enough resources to run the action. I/O Runtime is a scalable platform, so you would never see it with default action settings. If you do, please let us know by [email](mailto:[email protected]) so that we can help to troubleshoot what causes it.

You could also try [openwhisk-wskdebug](https://github.com/apache/openwhisk-wskdebug) which offers extensive capabilities to develop and debug the I/O Runtime actions of your App Builder applications.
You could also try running your actions locally with the `aio app dev` command. This is very similar to `aio app run` except that it will run your action code on localhost in a node process. Not all api calls will work in this context because of cors restrictions, but this is still useful in catching syntax errors, logic errors and enables step debugging of your actions without timeouts.


## Action logs

Expand All @@ -47,16 +48,16 @@ When Adobe authentication and authorization checks are enabled for an action wit
1. `request is invalid, failed authorization. Please use a valid user token for this SPA.`
2. `request is invalid, failed authorization. Please use a valid JWT or user access token for this headless application.`

An SPA is an application with web UI components (located in the `web-src/` folder). Headless app are back-end microservices without web UI.
For authentication and authorization checks, the back-end actions of an SPA are validated against a valid user token which is passed directly from Adobe Experience Cloud (ExC) Shell.
An SPA is an application with web UI components (located in the `web-src/` folder). Headless app are back-end microservices without web UI.
For authentication and authorization checks, the back-end actions of an SPA are validated against a valid user token which is passed directly from Adobe Experience Cloud (ExC) Shell.

On the other hand, the actions of a headless app can be validated against a valid user token from ExC Shell or a valid access token generated with the [JWT (Service Account) Authentication](/authentication/auth-methods#!AdobeDocs/adobeio-auth/master/JWT/JWT.md). Please go through the [App Builder Security Overview](../guides/security/index.md) for more details about SPA vs. headless app authentication.
On the other hand, the actions of a headless app can be validated against a valid user token from ExC Shell or a valid access token generated with the [JWT (Service Account) Authentication](/authentication/auth-methods#!AdobeDocs/adobeio-auth/master/JWT/JWT.md). Please go through the [App Builder Security Overview](../guides/security/index.md) for more details about SPA vs. headless app authentication.

If you are developing a headless app but accidentally have the `web-src/` folder added during the app initialization process, you could remove it by executing the command `aio app delete web-assets` at the root of your application source code folder. This will also assure that your actions are validated against the appropriate JWT auth.

## Debugging errors with State and Files SDK

If your code uses App Builder [State](https://github.com/adobe/aio-lib-state) or [Files](https://github.com/adobe/aio-lib-files) SDKs, you cannot use [wskdebug](https://github.com/apache/openwhisk-wskdebug) to debug it. The reason is that `wskdebug` forwards the debugged action from the I/O Runtime system to a local container on your machine and executes it there. This local container is not authorized to access the out-of-the-box cloud storage behind State and Files SDKs, as this would be the case with an action deployed to I/O Runtime.
If your code uses App Builder [State](https://github.com/adobe/aio-lib-state) or [Files](https://github.com/adobe/aio-lib-files) SDKs, you cannot use `aio app dev` to debug it. The reason is that State and Files services have additional security which limits calls from outside of Adobe Runtime actions. Your action code is run on localhost which is not authorized to access the out-of-the-box cloud storage behind State and Files SDKs.

*Note: This is not a problem if you configure the State or Files SDKs to connect to your own cloud storage (e.g. Cosmos DB).*

Expand Down
49 changes: 19 additions & 30 deletions src/pages/getting_started/first_app.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -78,7 +78,7 @@ Once your project is set up in [Adobe Developer Console](/console), let's move o

```bash
$ aio login
Visit this url to log in:
Visit this url to log in:
https://aio-login.adobeioruntime.net/api/v1/web/default/applogin?xxxxxxxx
```

Expand All @@ -88,7 +88,7 @@ Once your project is set up in [Adobe Developer Console](/console), let's move o
eyJ4NXUiOixxxxxxxxxxxxxxxxxxx
```
1. Now you can start building App Builder Applications with the [CLI](https://github.com/adobe/aio-cli)!
1. Now you can start building App Builder Applications with the [CLI](https://github.com/adobe/aio-cli)!
## 4. Bootstrapping new App using the CLI
Expand Down Expand Up @@ -136,11 +136,11 @@ There are a few sample flows listed below. Some developers may not have access t
create app.config.yaml
create .aio
create README.md
.......
found 0 vulnerabilities
✔ App initialization finished!
```
Expand Down Expand Up @@ -257,7 +257,7 @@ Note that you may not see all the options listed below on your command line, bec
? We are about to create a new sample action that interacts with the Adobe Experience Platform: Realtime Customer Profile
how would you like to name this action? customer-profile
? We are about to create a new sample action that showcases how to access an external API
how would you like to name this action? (generic)
how would you like to name this action? (generic)
```
1. Once you complete this select, you should see the build process kicking off with necessary npm dependencies are getting installed.
Expand All @@ -267,11 +267,11 @@ Note that you may not see all the options listed below on your command line, bec
create app.config.yaml
create .aio
create README.md
.......
found 0 vulnerabilities
✔ App initialization finished!
```
Expand Down Expand Up @@ -465,34 +465,23 @@ The other sample actions require futher paramaters to be invoked. For instance,
### 6.3 Debugging the Application
Our [CLI](https://github.com/adobe/aio-cli) is integrated with an open source project [wskdebug](https://github.com/apache/openwhisk-wskdebug) to support debug functionalities. You can develop and debug OpenWhisk actions in your favorite IDE or debugger with a fast feedback loop. It features:
The [CLI](https://github.com/adobe/aio-cli) has a _dev_ command (`aio app dev`) to support debug functionalities. You can develop and debug your Adobe Runtime actions in your favorite IDE or debugger with a fast feedback loop. It features:
- Full debugging of actions of the respective language runtime
- Automatic code reloading
- Step through debugging with lengthy timeouts _(previously you could only stop at a breakpoint for 60 seconds)_
- LiveReload for web actions
- Auto-invoking of actions on code changes
- Or running any shell command such as a curl request on code changes
- Instant logging output to terminal
Please visit [Debugging App Builder Apps Codelab](../resources/debugging/index.md) to set up your local environment and go through step-by-step instructions.
If the local development is run without the `--local` option, the action you are debugging is running directly on [Adobe I/O Runtime](/runtime). When the `--local` option is used, the actions are debugged in the standalone OpenWhisk instance running locally. In both cases, Docker is required on your local machine so that the remote or locally mounted actions get proxied in the local Docker container. Learn more about what you can do in [debug mode](https://www.npmjs.com/package/@openwhisk/wskdebug).
#### Targeting local actions with `aio runtime`
To target local actions with `aio runtime`, you will have to populate the project's `.env` with the local Runtime credentials.
These credentials are always the following when using `aio`:
```
AIO_runtime_auth=23bc46b1-71f6-4ed5-8c54-816aa4f8c502:123zO3xZCLrMN6v2BKK1dXYFpXlPkccOFqm12CdAsMgRU4VrNZ9lyGVCGuMDGIwP
AIO_runtime_namespace=guest
AIO_runtime_apihost=http://localhost:3233
```
Once the project's `.env` has been populated with the local Runtime credentials, commands executed with `aio runtime` in the root project directory will target the locally deployed instance of Runtime.
If the local development is run (`aio app run`), the actions you are calling are run directly on [Adobe I/O Runtime](/runtime). When you use `aio app dev`, the actions are run/debugged in node directly. In both cases your frontend is run on localhost.
### 6.4 Retrieving Logs for the Application
To see your application logs, use the command `aio app logs`. By default, only the logs of the latest activation is fetched. If you want to see a more extensive list of logs, use the `--limit` flag to define the number of recent activations to be fetched.
#### Dev
When using `aio app dev` logs are immediately output to the terminal and are not kept in an activation record.
#### Run or Deploy
To see your application logs after running `aio app run` or after running your deployed app (`aio app deploy`), use the command `aio app logs`. By default, only the logs of the latest activation is fetched. If you want to see a more extensive list of logs, use the `--limit` flag to define the number of recent activations to be fetched.
Read more at [Managing Application Logs](../guides/application_logging.md)
Expand Down Expand Up @@ -541,7 +530,7 @@ The [CLI](https://github.com/adobe/aio-cli) output details this process:
...
Your deployed actions:
-> demoproject-0.0.1/__secured_analytics
-> demoproject-0.0.1/__secured_analytics
...
To view your deployed application:
Expand Down
9 changes: 2 additions & 7 deletions src/pages/getting_started/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -59,21 +59,16 @@ Our [CLI](https://github.com/adobe/aio-cli) and its plugins are automatically te

#### Supported Terminals for the CLI

Our [CLI](https://github.com/adobe/aio-cli) uses the popular [inquirer](https://www.npmjs.com/package/inquirer) package for all its interactive functionalities, such as the application generators.
The [CLI](https://github.com/adobe/aio-cli) uses the popular [inquirer](https://www.npmjs.com/package/inquirer) package for all its interactive functionalities, such as the application generators.

See [inquirer's Support section](https://www.npmjs.com/package/inquirer#support-os-terminals) and [its known issues](https://www.npmjs.com/package/inquirer#know-issues) for up-to-date details.

### Optional Tools

The following is required if you intend to use local development features provided by the [CLI](https://github.com/adobe/aio-cli):
The following is required if you intend to use local development (`aio app dev`) features provided by the [CLI](https://github.com/adobe/aio-cli):

- [Visual Studio Code](https://code.visualstudio.com/download) (VS Code) as the supported IDE for editor, debuggger, etc. You can use any other IDE as a code editor, but advanced usage (e.g. debugger) is not yet supported.
- [Java Development Kit (JDK)](https://www.oracle.com/technetwork/java/javase/overview/index.html) (at least Java 11)
- [Chrome debugger extension in VSCode](https://github.com/Microsoft/vscode-chrome-debug)
- [Docker Desktop](https://www.docker.com/get-started)

**Note:** Developers on Windows machines should make sure that they are using Linux containers for the images above.
The steps to switch to Linux containers are described in the [Docker for Windows documentation](https://docs.docker.com/docker-for-windows/).

## Next Step

Expand Down
28 changes: 11 additions & 17 deletions src/pages/guides/deployment/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ In the following chapters of this documentation, it will be assumed that:

- **AIO_RUNTIME_AUTH**, which holds the credentials for the Runtime namespace to use
- **AIO_RUNTIME_NAMESPACE**, which holds the name of the Runtime namespace to use

If you do not own a [Runtime](/runtime) namespace, please [request trial access](https://developer.adobe.com/app-builder/trial/).

The [Setup Requirements](../../getting_started/index.md) documentation should also be checked before trying out the deployment scenarios described below.
Expand All @@ -29,13 +29,13 @@ The [CLI](https://github.com/adobe/aio-cli) offers three types of deployment to

## Local Deployment

Local deployment capabilities are offered to developers who want to test and debug their application before this one gets deployed to the out-of-the-box Content Delivery Network.
Local deployment capabilities are offered to developers who want to test and debug their application before it is deployed to the out-of-the-box Content Delivery Network.

### Local Runtime actions and UI

#### Use-Case

This local deployment feature is useful for developers who want to easily get an initial preview of their Custom Application before deploying it to [Runtime](/runtime) and to the out-of-the-box Content Delivery Network. They will also benefit from local [Runtime](/runtime) actions and UI debugging capabilities.
This local deployment feature is useful for developers who want to easily get an initial preview of their Custom Application before deploying it to [Runtime](/runtime) and to the out-of-the-box Content Delivery Network. They will also benefit from local [Runtime](/runtime) actions and UI debugging capabilities.

It also helps developers who want to work on their Custom Application implementation without an appropriate Internet connection. Of course, in that case you are not able to interact with [Adobe APIs](/apis) or with remote 3rd party systems.

Expand All @@ -45,25 +45,19 @@ This deployment scenario doesn't require any specific credentials, as both [Runt

#### CLI Command

This deployment is triggered when running `aio app run --local` at the root of the Custom Application source code directory.
This deployment is triggered when running `aio app dev` at the root of the Custom Application source code directory.

#### Architecture

![Local Runtime Actions and UI](../../images/local-actions-local-ui.png)

In this scenario, the [CLI](https://github.com/adobe/aio-cli) will download a [standalone instance](https://github.com/apache/openwhisk/tree/master/core/standalone) of [Apache OpenWhisk](https://openwhisk.apache.org/), which is the open source serverless platform behind [Runtime](/runtime), on the developer's machine.
![Local Runtime Actions and UI](../../images/cli-dev.jpg)

The [Runtime](/runtime) actions of the application will be deployed to this local [Apache OpenWhisk](https://openwhisk.apache.org/) instance, and executed in NodeJS docker containers spinned up locally from the Docker images that are documented in the **Technical Prerequisites** section above.

The local [Apache OpenWhisk](https://openwhisk.apache.org/) instance runs on port 3233 by default, and the deployed actions will be accessible at:
The [Runtime](/runtime) actions of the application will be run in NodeJS.

```
http://localhost:3233/api/v1/web/guest/<appname-appversion>/<action-name>
http://localhost:9080/api/v1/web/<namespace>/<pkg-name>/<action-name>
```

**appname** and **appversion** are both application name and version, which are maintained in the package.json file at the root of the Custom Application source code folder.

**action-name** is the name of the action, which has been chosen by the developer when bootstrapping the application from the generator that was executed with `aio app init <appname>`.
**pkg-name** and **action-name** is the name of the package and action, which has been chosen by the developer when bootstrapping the application from the generator that was executed with `aio app init <appname>`.

In case of a headful Custom Application, the UI will be served locally from [ParcelJS](https://parceljs.org/features/cli), which is the underlying framework used by the [CLI](https://github.com/adobe/aio-cli) to build the front-end source code.

Expand All @@ -75,7 +69,7 @@ This deployment scenario requires [Runtime](/runtime) credentials in a .env file

#### Use-Case

This feature is useful for developers who want to test and debug locally their Custom Application in a live environment fully integrated to Adobe's ecosystem, with minimal deployment time and efforts.
This feature is useful for developers who want to test and debug locally their Custom Application in a live environment fully integrated to Adobe's ecosystem, with minimal deployment time and efforts.

#### CLI Command

Expand All @@ -95,7 +89,7 @@ This deployment scenario requires [Runtime](/runtime) credentials in a .env file

#### Use-Case

This feature is useful for developers who want to test and preview their Custom Application fully integrated to Adobe's ecosystem, in conditions that are similar to a production deployment.
This feature is useful for developers who want to test and preview their Custom Application fully integrated to Adobe's ecosystem, in conditions that are similar to a production deployment.

#### CLI Command

Expand All @@ -111,4 +105,4 @@ The out-of-the-box [Token-Vending Machine](https://github.com/adobe/aio-tvm) is

If the credentials are valid, the Token-Vending Machine provides an access token to the CLI, which will authorize the CLI to deploy the static files of the Custom Application to the Content Delivery Network.

The deployed Custom Application will then be available at `https://<namespace>.adobeio-static.net/<appname>-<appversion>/index.html`, where **namespace** is the developer's namespace, **appname** and **appversion** are respectively the Custom Application name and version, which are maintained in the package.json file at the root of the Custom Application source code folder.
The deployed Custom Application will then be available at `https://<namespace>.adobeio-static.net/index.html`
Loading

0 comments on commit f3ea034

Please sign in to comment.