Hosted Targets tutorials (Beta)

In the following tutorials, we explain how to:

  • deploy a Node.js app to Hosted Targets using the Edge UI.
  • deploy a Node.js app from your local development machine to Hosted Targets.
  • migrate an existing Node.js proxy 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.

Sign in

  1. Go to: apigee.com/edge
  2. Enter your login credentials and sign in.
  3. You must be in the New Edge UI. If not, click Try New Edge in the Classic Edge navigation bar.

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 (Beta).



  4. Click Next.
  5. In the Proxy Name field, enter hello-hosted-targets.
  6. Click Next.
  7. In the Security page, select Pass through (none) for the Authorization.
  8. Click Next.
  9. Click Next.
  10. In the Build page, be sure the test environment is selected. Notice that the Proxy Type is Hosted Targets.
  11. Click Build and Deploy.
  12. After the proxy is successfully deployed, click View hello-hosted-targets proxy in the editor.
  13. 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-03-22T15:59:14.577Z","msg":"Hello, World!"}

Examine the proxy

  1. Click the Develop tab.
  2. In the Navigator, select the default Target Endpoint.
  3. Notice that there is an empty <HostedTarget/> tag in the endpoint XML. 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.

  4. In the Navigator, notice the contents under the Scripts section. The Node.js app files are listed under the hosted label.

  5. Now, look at the Scripts > hosted files:
    • The app.yaml 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. For the complete file listings, see Sample Applications on GitHub.
    • The index.js file is the 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. Click the Develop tab.
  2. To see the build log, click Build Logs.
  3. To see the deployment log, click Runtime Logs.

    See also About log files.

Summary

  • You deployed a simple Node.js application to the Hosted Targets environment and tested it. The details of how the app are deployed to this environment are handled entirely for you by Edge.
  • 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.

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. The Node.js app will be bundled into a new Hosted Targets proxy and deployed on Edge.

Create the Node.js app

To make things easy, we provide the code for a simple Node.js app for you to deploy to Hosted Targets using apigeetool.

  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.
  4.     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)
        })
        
  5. Create a file called package.json, and copy this code into it. Notice that the express module is listed as a dependency.
  6. {
        "name": "hello-world",
        "version": "1.0.0",
        "main": "index.js",
        "scripts": {
            "start": "node index.js --use_strict"
        },
        "author": "",
        "license": "",
        "dependencies": {
            "express": "^4.16.0"
        }
    }
    
  7. Create a file called app.yaml, and copy this code into it:
  8. runtime: node
    runtimeVersion:8
    application:my-express-app
    env:
      - name: NODE_ENV
        value: production
      - name: LOG_LEVEL
        value:3
    
  9. Make sure your directory looks like this:
    ls node-hosted-express
    app.yaml index.js package.json
    

About the directory structure of your Node.js app

To deploy a Node.js app to Hosted Targets, the app must have the same structure as a standard Node.js app. However, please note the following:

  • You must add the required app.yaml manifest file to the root directory of your Node.js app. For details on the structure of this file, see manifest file.
  • You must supply a package.json file.
  • 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.

Installing 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

Deploying the proxy

  1. In a terminal, cd the root directory of your Node.js application.
  2. Execute the apigeetool utility with the deployhostedtarget command:
  3. apigeetool deployhostedtarget -o <org> -e <env> -n <proxy-name> -b /node-hosted-express -u <username>

    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._\-$ %

    For example:

    apigeetool deployhostedtarget -o myorg -e test -n node-hosted-express -b /node-hosted-express -u jdoe@apigee.com

    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, using 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.

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.

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 Edge UI.

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

This section explains how to manually migrate an existing Node.js proxy to a Hosted Targets proxy. It also explains now to deploy the proxy after you've performed the migration steps.

Use case: If you have an existing Edge Node.js proxy (one that uses Trireme), you can "migrate" it to a Hosted Targets proxy by following the steps in this section. This way, the proxy structure, policies, flows, and so on from your original proxy are preserved. You can perform the migration in four steps, outlined below, and then deploy it with apigeetool.

Step 1: Adjust the proxy file structure

In a traditional Edge Node.js proxy, the file structure looks like this, where the root directory of your Node.js app is located under the resources/node directory:

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


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.

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


Here is an example showing the Node.js project structure in the correct location in the proxy:

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

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.

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.

  1. cd to the root directory of your proxy: /apiproxy
  2. Use this command to deploy the proxy:
  3. apigeetool deployproxy -u username -o <your-org> -e <your-env> -n <proxy-name> -d .

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

Testing the proxy

You can test the proxy with a cURL command, using 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/myhelloapp
Hello,World!