11436 SSO

Tutorial: Apigee-127, Node.js, and Npm - Setting up Your Environment

Nov 07, 2014

Apigee-127 is a great platform for building APIs. You can quickly go from idea to concept to production-grade API using the Swagger Editor and Apigee-127 tools.  

We’ve already covered a fair amount of ground on Apigee-127 on the Apigee blog, and we’ve created a Quick Start to show you how to quickly and easily get a simple API up and running: https://github.com/apigee-127/a127-documentation/wiki/Quick-start.  Let’s continue with a tutorial about installing Apigee-127.

For the uninitiated, npm is considered the default package manager for Node.js apps. Node.js apps rely heavily on external packages for functionality; there are many of these that solve the problems you’re likely to encounter when developing applications with Node.js. Npm gives you easy access to these packages, and Apigee-127 depends on several of them.

Installing packages from npm

When you install packages from npm, they’re stored by default in the ./node_modules/{package_name} directory. You can install npm packages in two ways:

  • Manually by typing npm install {package_name}

  • By specifying one or more dependencies in a file named package.json in the root folder of your project and running “npm install” from that directory.  

    • If you’re publishing and/or sharing your project this is likely the best approach. This also allows you specify versions for each dependency so you can test with specific versions and ensure that your project works when shared.

    • This is also how dependencies are typically resolved when deploying to a PaaS that supports Node.js apps such as Apigee, Heroku, or Amazon Elastic Beanstalk.

Package types

For the purpose of this guide, we’ll refer to two types of packages:

  • global packages, which are typically installed manually, at a system level. Many npm modules offer a CLI and it’s usually necessary to install these packages at the system level, thereby placing the executables for the CLI on your environment PATH. “Apigee-127” is an example of a global package.

  • local packages, which are typically stored in node_modules in a project directory (or the directory where “npm install” is executed).  These are typically declared in a package.json file.

Installing global packages

Global packages are installed using the -g option when executing “npm install.”  For example: npm install -g apigee-127.  When this package is installed, it will be placed in {npm_prefix}/lib/node_modules with any executables being placed in {npm_prefix}/bin.  The default npm prefix is /usr/local. Therefore, using a default/initial npm configuration you’d need to use ‘sudo’ on POSIX systems so the current user has the appropriate permissions to write in this location. You should generally be aware of things requesting root permissions on your machine, and use an alternative approach where possible.

Using the npm prefix

The best alternative is to configure the npm prefix to be in a place that is writable by users other than the root user.  npm has the capability to customize the prefix for the directories where global packages are installed e.g. a directory that is writable without root permissions.

For example, you can set the npm prefix to be ~/.npm. In this case, executables will be installed in ~/.npm/bin and libraries will be installed in ~/.npm/lib/node_modules. In order to have the executables on your $PATH you will need to add ~/.npm/bin to your PATH.  

Depending on what shell you use this may be as simple as executing the command below (Bash shell).  Otherwise you can manually edit your environment settings to add {npm_prefix}/bin to your path.

$ echo export PATH=$PATH:~/.npm/bin >> ~/.bash_profile.  

Installing a127 with sudo

When you use the default npm configuration and sudo npm install -g apigee-127 then Apigee-127 will be installed in /usr/local/lib/node_modules/apigee-127 with executable scripts installed in /usr/local/bin:

  • /usr/local/bin/a127

  • /usr/local/bin/a127-account

  • /usr/local/bin/a127-project

  • /usr/local/bin/a127-usergrid

Using the npm prefix

Once you have your npm prefix configured and the {npm_prefix}/bin included in your path you can run npm install -g apigee-127 and find the files mentioned above in {npm_prefix}/lib/node_modules and {npm_prefix}/bin.

Confirming Installation

Once this is complete, you should be able to run a127 from the command line and see output like the following:

$ a127

 Usage: a127 [options] [command]



   account <action>

      manage deployment accounts


   project <action>

      manage a project


   usergrid <action>

      manage Usergrid process



      print config



      load the apigee-127 wiki


   help [cmd]

      display help for [cmd]



   -h, --help  output usage information


At this point you should have your environment set up and be ready to go!


Scaling Microservices