Was this helpful?

This topic explains how to create a new proxy that includes a stand-alone Node.js app. Two approaches are discussed: using a command-line tool and using the management UI. 

Introduction

If you are developing Node.js apps locally, Apigee provides two methods for deploying stand-alone Node.js apps. You can use the command-line deployment tool (called apigeetool) or you can import a Node.js file when creating a new proxy through the management UI. 

After you deploy your Node.js app, you can then use the management UI to view the proxy, run it, edit it, add policies, debug it, and so on.

Preparing your development environment

Setup takes just a few minutes. Here are the basic steps:
  1. If you haven't set up an account with Apigee, you need to do that first. It's free and only takes a minute. See Creating an Apigee Edge account
  2. If you want to run and test Node.js code locally before deploying it to Apigee Edge, you need to install Node.js on your system. You've probably done this already, but if not, go to nodejs.org for instructions.
  3. Test your Node.js installation to make sure it is set up properly. Try running the REPL, for example:

    $ node
    > 1+1
    2
    
  4. Clone the API Platform Tools from GitHub. This repository contains the deployment tool we will be using to deploy Node.js apps to Edge.

    $ git clone https://github.com/apigee/api-platform-tools.git
  5. Navigate to where the platform tools repository was saved on your system. It is called api-platform-tools.
     

    $ cd api-platform-tools
    
  6. Install the tools. The following command installs the tools on your machine in a standard location, such as /usr/local/bin.

    $ python setup.py install
    

    On a Macintosh or Linux, you may need to use sudo to run this tool as root. For example:

    $ sudo python setup.py install
  7. Finally, test that the platform tools are installed properly. Be sure you can run the following command (it has to be in your PATH):

    $ apigeetool -h
    
Now you have everything you need to create and deploy Node.js apps to Apigee Edge. Let's try it.

Create a Hello World! Node.js application

Now that the deployment tools are installed, all you need to do is create a home for your Node.js application. We'll show you how to add and deploy a basic Hello World! app written in Node.js. Nothing fancy, but it demonstrates the basics that you can repeat for any other Node.js applications.

  1. Create a folder for your node app. Call it anything you wish. We'll call it nodeapp.
  2. Create a file using your favorite text editor. Call the file server.js
  3. Open the file and paste this code into it. This commonly used "Hello World!" example is familiar to all Node.js developers. It's an HTTP server. When it receives a request, it sends back some text.

    var http = require('http');
    
    var svr = http.createServer(function(req, resp) {
    resp.writeHead(200, { 'Content-Type': 'text/plain' });
    resp.end('Hello, Node!\n');
    });
    
    svr.listen(process.env.PORT || 9000, function() {
    console.log('The server is running.');
    });
    
    

    The listen() method of the http and https modules in Node.js requires that you specify a port number as an argument. This argument is required in Node.js, but Apigee Edge ignores it. Instead, the API proxy in which the Node.js script runs specifies the "virtual host" that it listens on, and the Node.js application uses the virtual host, just like any other Apigee Edge proxy. For more information, see "Understanding HTTP and HTTPS support for Node.js" in Understanding Edge support for Node.js modules.

    Note how the port number is coded as a conditional in the http.listen() method. Coding the listening port in this way, so that it can be obtained from a system variable, if defined, is considered a best practice by Apigee.

  4. Test the app locally if you wish. Execute the code like this:

    $ node server.js
    
  5. In another terminal window, you can call the API using cURL like this. Or, if you don't have cURL installed, you can enter the URL in a browser. 

    $ curl http://localhost:9000/hellonode
    Hello, Node!
    
  6. If "Hello, Node!" comes back, you are ready to deploy to Edge.

Use apigeetool to deploy your Node.js apps to Apigee Edge

The apigeetool utility lets you deploy Node.js applications to Edge. See "Preparing your development environment" for the steps to install apigeetool. When you invoke the apigeetool utility, it does the following:

  • Generates an API proxy configuration bundle to house the Node.js application.
     
  • Packages the Node.js application with any Node.js packages installed with NPM (Node Packaged Modules).
     
  • Imports the API proxy configuration bundle to the specified organization on Apigee Edge using the Edge management API.
     
  • Deploys the API proxy to an environment.
     
  • Executes the Node.js application on Apigee Edge and making it available over the network.

Before you deploy, you'll need to know your organization name, user name, and password for your Apigee Edge account. You need this information to correctly form the deployment tool command.

Here's the command. It assumes that you are in the directory that contains your Node.js app. Be sure to substitute your organization name, username and password into the command:

$ apigeetool deploynodeapp -n hellonode -d . -m server.js -o org_name -e test -b hellonode -u username -p password

Here's a quick summary of the command flags used in this example:

  • -n This flag lets you specify the name of the proxy that will be created when the app is deployed. You'll see this name in the management UI.
  • -d  Specifies the directory in which the Node.js app resides. In this case, we're running the command in the directory that contains the source file.
  • -m The name of the main script. It must be in the /resources/node directory. This is the script file that is executed when the proxy is deployed. 
  • -b The basepath. The default is /. We'll specify /hellonode to prevent conflicts in case you already have a proxy deployed with the default path. 
  • -o, -e, -u, and -p specify the organization name, deployment environment, user name and password.

For information on what each of the command flags mean, do this:
 

$ apigeetool deploynodeapp -h

The output in your terminal window will look something like this:

Importing new application hellonode
Imported new app revision 1
Deploying revision 1
  Deployed.
Proxy: "hellonode" Revision 1
  Environment: test BasePath: /
  Status: deployed

If you see Status: deployed, that's it. Your Node.js app is wrapped in an API proxy, deployed to Edge, and it's running and waiting to handle requests. It's ready to be tested.

Importing a Node.js file through the UI

You can use the management UI to create a new APIi proxy with a Node.js application. The UI lets you select a Node.js file from your local file system. The file is then imported to Edge and wrapped in an API proxy. 

  1. From the API proxy summary page, click +API Proxy
  2. In the New API Proxy dialog, select Existing Node.js.
  3. Use the Choose Files button to select one or more Node.js files to import. 
  4. Give the proxy a name. In this example, we are calling it hellonode
  5. Click Build

 

If you uploaded multiple Node.js files, you need to specify which one is the main file. (The main file is the one that you would invoke from the command line with the node command.)

  1. Click Develop to enter the Develop view. 
  2. Open the TargetEndpoint file for editing. 
  3. Be sure the <ScriptTarget> element specifies the main Node.js file, as follows:
    <ScriptTarget>
            <ResourceURL>node://server.js</ResourceURL>
            <Properties/>
    </ScriptTarget>
  4. Click Save

Test the new API proxy

You have just created an API proxy for your Node.js app on Apigee Edge! To test it, run this cURL command with the proxy URL. Be sure to substitute your organization name for org_name.

$ curl http://org_name-test.apigee.net/hellonode
Hello, Node!

View the new proxy in the management UI

Log in to your your Apigee Edge account and go to the API Proxies page of the management UI. If you followed the steps in this topic, you will see the proxy called "hellonode" listed there, as shown in the following figure:


Click on "hellonode" to view details about the proxy. In the Develop view, you can see the source code you uploaded, add policies, edit flows, and so on, as shown in the following figure:



Next Steps

In the next topic, Adding Node.js to an existing API proxy, we explain how to add a Node.js app to an existing proxy in your filesystem and deploy it to Edge.

Add new comment

Provide your email address if you wish to be contacted offline about your comment.
We will not display your email address as part of your comment.

We'd love your feedback and perspective! Please be as specific as possible.
Type the characters you see in this picture. (verify using audio)

Type the characters you see in the picture above; if you can't read them, submit the form and a new image will be generated. Not case sensitive.