You're viewing **Apigee Edge** documentation.  
[Go to the
**Apigee X** documentation](http://cloud.google.com/apigee/docs/api-platform/get-started/tutorials). info

> [!NOTE]
> Apigee Hosted Targets are available to Apigee Edge Cloud Enterprise customers in the Edge UI. Hosted Targets are not available in the Classic Edge UI.

The following tutorials explain how to deploy Node.js applications to Edge using
[Hosted Targets](https://docs.apigee.com/api-platform/hosted-targets/hosted-targets-overview),
a native Node.js runtime environment hosted by Apigee.

The tutorials walk through the following tasks:

- Deploying a Node.js app to Hosted Targets using the Edge UI.
- Deploying a Node.js app to Hosted Targets from your local development machine.
- Migrating an existing proxy with a [traditional
  Edge Node.js target implementation](https://docs.apigee.com/api-platform/nodejs/overview-nodejs-apigee-edge) to Hosted Targets.

## Deploy a Node.js app to Hosted Targets using the Edge UI

In this tutorial, you will deploy a simple Node.js app to Hosted Targets using the Edge
UI. When you complete the tutorial, you will understand the basic structure and contents of
a Hosted Targets proxy and how to access deployment and build log files.

### Sign in

1. Go to: [apigee.com/edge](http://apigee.com/edge)
2. Enter your Apigee login credentials to sign in.

### Create a new proxy

1. In the side navigation menu, select **Develop \> API Proxies**.
2. Click **+ Proxy**.
3. In the Create Proxy page, select **Hosted Target**.
4. Click **Next**.
5. In the Proxy Name field, enter **`hello-hosted-targets`** .

   > [!NOTE]
   > Proxy names must not contain spaces.

6. Be sure **"Hello World" Sample** is selected.
7. Click **Next**.
8. In the Security page, select **Pass through (none)** for the Authorization.
9. Click **Next**.
10. Click **Next**.
11. In the Build page, be sure the **test** environment is selected. Notice that the Proxy Type is **Hosted Targets**.
12. Click **Build and Deploy**. It may take a few moments for the proxy deployment to complete.
13. After the proxy is successfully deployed, click **View hello-hosted-targets proxy** at the bottom of the page.
14. Call the API proxy. The easiest way to do this is to go to the **Trace** tab, start a Trace session, and click **Send** . You should receive a 200 status with the following response:

    ```
    {"date":"2018-09-26T14:23:04.550Z","msg":"Hello, World!"}
    ```

### Examine the proxy

1. In the Edge UI, click the **Develop** tab.
2. In the Navigator, select **default** under Target Endpoints.
3. In the code editor, notice that there is an empty `<HostedTarget/>` child element under the `<TargetEndpoint>` element. This empty tag is required. It tells Edge that the target of the proxy is an application that is deployed to the Hosted Targets environment.

   ![](https://docs.apigee.com/static/api-platform/images/HF-IMG-1.png)
4. In the Navigator, notice the contents under the **Scripts** section. The Node.js app files are listed under the **hosted** label.

   ![](https://docs.apigee.com/static/api-platform/images/HF-IMG-6.png)

> [!NOTE]
> If you were to download the proxy to your local filesytem and examine the file structure, the **hosted** label in the UI corresponds to the **resources/hosted** directory.
>
> ![](https://docs.apigee.com/static/api-platform/images/HF-IMG-5.png)

5. In the Edge UI, examine the files listed under **hosted** in the **Scripts**:
   - The [app.yaml file](https://docs.apigee.com/api-platform/hosted-targets/hosted-targets-reference#the-manifest-file) contains configuration information. For example, you can add environment variables that will be available to the Node.js application at runtime. You do not need to modify this file for this example.

     > [!NOTE]
     > There is no **node_modules** folder in the project. A **node_modules** folder is not required. Edge runs **npm install** for you when the Node.js app is deployed. It gets the dependencies from **package.json** . The only time you would need to explicitly provide **node_modules** is if you have custom modules that are not available through **npm**.

   - The **index.js** file is the Node.js app's main file.
   - If your app has any module dependencies, they must be listed in **package.json**.

### View log files

Application log files can be useful for debugging problems that occur during the build phase
and also at runtime.

1. In the Edge UI, click the **Develop** tab.
2. To see the build log, click **Build Logs**.
3. To see the deployment log, click **Runtime Logs** .   

   See also [Accessing log files](https://docs.apigee.com/api-platform/hosted-targets/hosted-targets-tasks#accessing-log-files).

### Summary

- You deployed a simple Node.js application to the Hosted Targets environment and tested it in the Edge UI.
- You learned that a Hosted Targets proxy requires a special empty tag in the Target Endpoint called `<HostedTarget/>`.
- You learned that Edge loads module dependencies for you automatically, and that dependencies must be listed in the `package.json` file.
- You also learned how to check build and runtime log files.

## Deploy Node.js from your system to Edge

This section explains how to deploy a standalone Node.js application from your local system to
Hosted Targets using [apigeetool](https://www.npmjs.com/package/apigeetool). The `apigeetool`
utility bundles the Node.js app into a new Hosted Targets proxy and deploys it to Edge.

> [!NOTE]
> Node.js apps running in Hosted Targets must expose an HTTP API listening on **process.env.PORT** . See also [Environment
> variables set in the application runtime](https://docs.apigee.com/api-platform/hosted-targets/hosted-targets-reference#environment-variables-set-in-the-application-runtime).

### Install apigeetool

Using **apigeetool** is the recommended way for developers to deploy proxy
code to Edge. To install **apigeetool** run the following NPM command:

```
npm install -g apigeetool
```

### Create the Node.js app

To make things easy, the code for a simple Node.js app is provided for you.

1. Create a directory for the Node.js app. Call the directory **node-hosted-express**.
2. **cd** to the new directory.
3. Create a file called **index.js** and copy this code into it.

   > [!NOTE]
   > Notice that the app requires the **express module** . When you deploy, Hosted Targets runs **npm install** to import this external module. You do not need to include the `node_modules` directory as part of the deployment to Edge. The only time you would need to explicitly provide node_modules is if you have custom modules that are not available through npm.

```
var express = require('express')
var app = express()

app.get('/', function(req, res) {
    res.json({
        hello: "Hello World!"
    })
})

app.get('/hello/:name', function(req, res) {
    var name = req.params.name
    res.json({
        hello: "hello " + name
    })
})

var server = app.listen(process.env.PORT || 9000, function() {
    console.log('Listening on port %d', server.address().port)
})
```
4. Create a file called **package.json**, and copy this code into it. Notice that the express module is listed as a dependency.

```
{
    "name": "hello-world",
    "version": "1.0.0",
    "main": "index.js",
    "scripts": {
        "start": "node index.js --use_strict"
    },
    "author": "",
    "license": "",
    "dependencies": {
        "express": "^4.16.0"
    }
}
```
5. Create a file called **app.yaml**, and copy this code into it:

```
runtime: node
runtimeVersion: 8
application: my-express-app
env:
  - name: NODE_ENV
    value: production
  - name: LOG_LEVEL
    value: 3
```
6. Make sure your directory looks like this:

   ```
   ls
   app.yaml index.js package.json
   ```

### Review of the required directory structure for the app code

Your Node.js app must have the
same structure as a standard Node.js app. However, be sure that you have followed these
requirements before deploying with `apigeetool` to Edge:

- The **app.yaml** manifest file is required and must exist in the root directory of your app. To learn more about this file, see [manifest file](https://docs.apigee.com/api-platform/hosted-targets/hosted-targets-reference#about-the-manifest-file).
- A **package.json** file is required. It must list any dependencies that your app requires.
- A **node_modules** folder is **not** **required** . Edge runs **npm install** for you when the Node.js app is deployed. It gets the dependencies from **package.json** . The only time you would need to explicitly provide **node_modules** is if you have custom modules that are not available through **npm**.

### Deploying the proxy

1. In a terminal, **cd** to the root directory of your Node.js application.
2. Execute **apigeetool** with the **deployhostedtarget** command:

> [!NOTE]
> `apigeetool` automatically bundles the Node.js application into an API proxy and deploys it to the Hosted Targets environment on Apigee Edge. **The deployment may take a few minutes to
> complete**.

```
apigeetool deployhostedtarget -o org -e env -n proxy-name -b /node-hosted-express -u username
```
3. where **-n** is the name you want to give to the new proxy. It must be unique within the organization. The characters you are allowed to use in the name are restricted to the following: `a-z0-9._\-$%`

> [!NOTE]
> Proxy names must not contain spaces.

4. For example:

```
apigeetool deployhostedtarget -o myorg -e test -n node-hosted-express -b /node-hosted-express -u jdoe@apigee.com
```
5. For more information on using **apigeetool** see <https://github.com/apigee/apigeetool-node>.

### Testing the proxy

You can test the proxy with a cURL command, with a REST client like Postman, or in the Edge UI
in the Trace tool. Here's an example cURL command.

```
curl http://myorg-test.apigee.net/node-hosted-express
     {"date":1506992197427,"msg":"hello-world"}
```

### Getting the Build Logs

Build logs show you output related to deploying and building the Node.js app. See also [Log files](https://docs.apigee.com/api-platform/hosted-targets/hosted-targets-reference#about-log-files).

```
apigeetool getlogs -u username -o org -e env --hosted-build -n proxy-name
```

For example:

```
apigeetool getlogs -u jdoe@apigee.com -o myorg -e test --hosted-build -n node-hosted-express
```

### Getting the Runtime Logs

Runtime logs show output related to the running app. Runtime logs are scoped to the environment
and return logs for the currently deployed proxy revision. See also [Log files](https://docs.apigee.com/api-platform/hosted-targets/hosted-targets-reference#about-log-files).

```
apigeetool getlogs -u username -o org -e env --hosted-runtime -n proxy-name
```

For example:

```
apigeetool getlogs -u jdoe@apigee.com -o myorg -e test --hosted-runtime -n node-hosted-express
```

### Viewing the proxy in the Edge UI

After a successful deployment, you can view and edit your proxy in the API Proxies part of the
Edge UI.

## Migrating an existing Node.js proxy to a Hosted Targets proxy

This section explains how to manually migrate an existing Edge API proxy that employs the
[traditional
Node.js target implementation](https://docs.apigee.com/api-platform/nodejs/overview-nodejs-apigee-edge) to Hosted Targets. It also explains how to deploy the proxy after
you've performed the migration steps.

The migration steps preserve the API proxy structure, policies, flows, and other configuration elements.
You can perform the migration in **four steps** , as outlined below, and then deploy
the migrated proxy with [apigeetool](https://www.npmjs.com/package/apigeetool).

> [!NOTE]
> You cannot directly migrate an app that uses **apigee-access** . See [Is it possible to work around the lack of apigee-access?](https://docs.apigee.com/api-platform/hosted-targets/hosted-targets-faq#how-should-we-work-around-the-lack-of-apigee-access).

### Step 1: Adjust the proxy file structure

To adjust the file structure, the API proxy must be on your local filesystem. If the proxy is
deployed on Edge, you must [download it](https://docs.apigee.com/api-platform/fundamentals/download-api-proxies)
before continuing. In the traditional configuration, and Edge proxy "bundle" that includes Node.js code follows this file structure.
The Node.js application code is placed in the `resources/node` directory:

```
apiproxy/
    policies/
    proxies/
    targets/
    resources/
      node/
        Your application code
```

<br />

For Hosted Targets, you must place the root directory of your Node.js app under a
directory called `resources/hosted`. Simply create a new directory called
**resources/hosted** and move the contents of `resources/node`
into it. Then, you can delete the `resources/node` directory.

```
apiproxy/
     policies/
     proxies/
     targets/
     resources/
       hosted/
         Your application code
```

### Step 2: Add the manifest file

Create a manifest file called `app.yaml` and place it in the
`apiproxy/resources/hosted` directory.

Following is an example `app.yaml` file. It specifies that the runtime is
Node.js (required). It also creates an environment variable in the execution environment
(a variable that could be accessed by the Node.js app). The environment variable is optional
and is only shown here as an example. For more details and examples, see [The manifest file](https://docs.apigee.com/api-platform/hosted-targets/hosted-targets-reference#about-the-manifest-file).

```
runtime: node
  env:
    - name: NODE_ENV
      value: production
```

<br />

The following example shows a Node.js project structure that is in the correct location in the
proxy for Hosted Targets deployment:

```
apiproxy/
   resources/
      hosted/
        index.js
        node_modules/
        app.yaml
        package.json
```

> [!NOTE]
> The `node_modules` directory is **not required** . Edge will perform an `npm install` when the app is deployed. However, if your app uses private or custom modules not available through **npm** , then you can include them in the **node_modules** directory and they will be deployed along with the app.

### Step 3: Make sure you have a package.json file

In traditional Edge Node.js proxies, the `package.json` was
optional. However, for Hosted Targets, you must supply one in the `apiproxy/resources/hosted` directory. Be sure
to specify any required dependencies for your app in this file.

### Step 4: Modify the target endpoint of the proxy

A traditional Node.js proxy requires that a tag called `<ScriptTarget>`
be present in the target endpoint file (typically `/apiproxy/targets/default.xml`).
For Hosted Targets, you need to add an empty tag called **\<HostedTarget/\>** .
If there's a `ScriptTarget` tag in the file, you can simply remove it.
For example:

```
    <?xml version="1.0" encoding="UTF-8"?>
    <TargetEndpoint name="default">
       <Description />
       <FaultRules />
       <PreFlow name="PreFlow">
          <Request />
          <Response />
       </PreFlow>
       <PostFlow name="PostFlow">
          <Request />
          <Response />
       </PostFlow>
       <Flows />
       <HostedTarget />
    </TargetEndpoint>
    
```

### Deploying the proxy

You can now deploy the proxy using the `apigeetool deployproxy` command.

> [!NOTE]
> You do not need to run **npm install** before deploying your proxy. Edge will run an install on your project when it is deployed.

1. **cd** to the root directory of your proxy: **/apiproxy**
2. Use this command to deploy the proxy:

   > [!NOTE]
   > If you are replacing a currently "traditional" Edge Node.js proxy, be sure to use the same proxy name in the following command (the **-n** parameter) as the deployed proxy. The `apigeetool` utility will undeploy the existing proxy and deploy the new Hosted Targets proxy.

```
apigeetool deployproxy -u username -o org -e env -n proxy-name -d .
```

> [!NOTE]
> Proxy names must not contain spaces.

3. For example:

```
apigeetool deployproxy -u jdoe -o docs -e test -n hello-world -d .
```

For more information on using `apigeetool` see:
[https://github.com/apigee/apigeetool-node/blob/master/README.md](https://github.com/apigee/apigeetool-node).

### Testing the proxy

You can test the proxy with a cURL command, with a REST client like Postman, or in the Edge UI
in the Trace tool. Here's an example cURL command:

```
curl http://myorg-test.apigee.net/hello-world
Hello,World!
```

> [!NOTE]
> For more examples to help you get started, see [Sample
> applications on GitHub](https://docs.apigee.com/api-platform/hosted-targets/hosted-targets-reference#sample-hosted-targets-applications-on-github).