Configuring your environment - CORS in Action: Creating and consuming cross-origin APIs (2015)

CORS in Action: Creating and consuming cross-origin APIs (2015)

Appendix B. Configuring your environment

This appendix shows you how to install and configure tools used throughout this book. Some of these tools make extensive use of the command line. For a crash course on how to use the command line, visithttp://learnpythonthehardway.org/book/appendixa.html.

B.1. Setting up for the sample application

Chapter 3 introduced a sample application that’s used throughout the book. The prerequisites for running the sample are

· Node.js

· NPM

· Express

The rest of this section explains what these prerequisites are and how to set them up. Note that these instructions may change in the future. If you’re having trouble installing these tools, you can always visit their respective websites to get the latest installation instructions.

B.1.1. Node.js and NPM

The sample runs in Node.js, a development platform for writing server apps. Node.js apps can be written in JavaScript, which is convenient because the client code is also written in JavaScript. Node.js can be downloaded and installed from http://nodejs.org. This page has a giant Install button right on the front that you can click to download the Node.js installer, as shown in figure B.1.

Figure B.1. Node.js homepage with an Install button.

The following subsections look at installing Node.js on different operating systems. In addition to installing Node.js, the installer will install the Node Package Manager (NPM), which is a helper app used to download and install Node.js libraries. You’ll use NPM later on to download and install Express and other modules.

Installing Node.js on Windows

Windows will download a MSI installer file. Double-click this file to begin the installation process. Feel free to accept the default values for the options presented during the installation.

There are a few things to note when installing Node.js on Windows. First, you may be presented with a security dialog during the installation process, as shown in figure B.2 (in fact, you may see this security dialog for all apps you install on Windows). It’s safe to click Yes to continue.

Figure B.2. Security warning when installing Node.js on Windows. Click Yes to continue.

Second, Node.js comes with its own command prompt which is preconfigured with all the proper variables for running Node.js. You can find this command prompt by searching for “Node.js command prompt” in the Start menu, as shown in figure B.3.

Figure B.3. Finding and running the Node.js command prompt

Throughout the rest of the samples in this book, when the instructions ask you to use a terminal window, use the Node.js command prompt.

Installing Node.js on Mac OS X

The Mac installer comes as a PKG file. Double-click this file to begin the installation process. As you walk through the installation, use the default values for all the options.

The final step of the installation process asks you to “Make sure /usr/local/bin is in your $PATH”, as shown in figure B.4.

Figure B.4. Installation message about $PATH

You can easily verify this by opening a terminal window and typing echo $PATH. This command will print output similar to figure B.5; you should see /usr/local/bin somewhere in that path.

Figure B.5. Displaying the $PATH environment variable

If for some reason that path doesn’t have that value, you can manually add it with the following command:

export PATH=$PATH:/usr/local/bin

Installing Node.js on Linux

The Node.js website has a .tar.gz file with compiled binaries for Linux. If you have the .tar.gz file, you can install Node.js with the following commands:

> tar xzf node-v0.10.29-linux-x64.tar.gz

> ./configure

> make

> sudo make install

Note

The .tar.gz filename may differ slightly depending on which version of Node.js you downloaded.

An easier way to install Node.js on Linux is to use the package manager. Most Linux distributions have a package manager for installing tools. This can make it a little easier to install Node.js, but the downside is that the version of Node.js is sometimes a little behind the latest version. But the samples in this book should work, even for slightly older versions of Node.js.

Type the following commands into a command prompt to install Node.js from the command line (if you are not using a Debian-based distro the commands may be a little bit different):

> sudo apt-get update

> sudo apt-get install nodejs npm

After typing these commands and following the prompts, Node.js will be installed.

Verifying the installation

You can verify that Node.js and NPM are installed correctly by typing the following two commands:

> node --version

> npm --version

You should see a version number for each tool. The samples in this book were run using Node.js version 0.10.29 and NPM version 1.4.14.

Note

Some Linux versions have a program called node. If you type node --version and nothing happens, you’re probably running into this conflict. In this case, Node.js should be mapped to nodejs. Try typing nodejs --versioninstead.

If there is an issue with your install, visit the support at the Node.js homepage at http://nodejs.org. You can also learn more about installing Node.js on various platforms at https://github.com/joyent/node/wiki/Installing-Node.js-via-package-manager.

B.1.2. Express

The sample server is implemented using a web application framework called Express. Express simplifies the process of building web servers on Node.js by providing middleware that handles common web server operations.Middleware is a term used to describe functions inserted into the web server–processing pipeline that can act on the HTTP request or HTTP response. These functions are termed middleware because they sit in the middle of the incoming request and the actual code that processes the request. For example, Express has middleware pieces to handle common web server functionality such as authentication, compression, and cookie sessions. figure B.6 shows how a request passes through pieces of middleware in Express.

Figure B.6. An Express server with three middleware components

You certainly don’t have to use Express (or any web application framework for that matter), but it makes things easier by taking care of the grunt work of setting up a web server. This allows you to focus on the details of adding CORS support to the server. You can learn more about Express at http://expressjs.com.

You can use NPM (which was installed previously) to install Express. The installation instructions are the same for all OSes. To install Express, open up a terminal window in the location you wish to install to and type npm install express. That should be all you have to do! You can verify that Node.js and Express are installed properly by opening up a terminal window and typing node, followed by pressing the Return key. This brings you into the Node.js development environment, where you can type in JavaScript code and have it immediately interpreted by Node.js. For example, type var e = require('express'); and press the Return key. If Node.js and Express are installed properly, you shouldn’t see any errors (though you may see the word undefined; that’s okay). figure B.7 shows what the result of these two commands looks like.

Figure B.7. Working installation of Node.js and Express

The samples in this book were built using Express version 4.6.1, but any version greater than 4 should work. Note that Express 4 introduced breaking changes, so if you’re using Express 3 or earlier, the sample code won’t work. Now that you’ve installed all the tools, you can return to chapter 3 and continue with the sample code.

B.2. Debugging tools

Chapter 7 introduced tools to help debug CORS requests. This section covers how to install these tools.

B.2.1. Wireshark

Wireshark (www.wireshark.org) is a packet analyzer that can help view CORS request and response headers. You can download the tool from www.wireshark.org/download.html. When you visit the Wireshark download page, the correct installer for your system will be highlighted. Download and run the installer to begin the process.

Installing Wireshark on Windows

As mentioned in chapter 7, Wireshark has issues with debugging the sample on Windows because Windows has trouble capturing traffic over localhost (learn more about this issue athttp://wiki.wireshark.org/CaptureSetup/Loopback). Windows users should use Fiddler to debug the sample app. Installing Fiddler is covered in the next section.

But Wireshark can still be installed on Windows to debug traffic to servers outside your local computer. To install Wireshark, just run the Wireshark installer and follow the instructions. During the installation process, you’ll be asked to install WinPcap (if you don’t have WinPcap installed already). WinPcap offers an API for capturing network traffic for Windows. After the WinPcap installer runs and finishes, you’ll be taken back to the Wireshark installation process. Learn more about WinPcap at www.winpcap.org/.

Installing Wireshark on Mac OS X

Installing Wireshark on OS X requires that you first install XQuartz, a version of X server, which is a windowing system common in Unix systems. Think of X server (commonly called X11) as the thing that displays the Wireshark UI.

The XQuartz installer can be downloaded from http://xquartz.macosforge.org/. Download and run the installer. After XQuartz is installed, it’s a good idea to reboot your system. (I was unable to get Wireshark to work without a reboot.)

Once XQuartz is installed, you can download and run the Wireshark installer. When you first run Wireshark, you may be greeted with the dialog box shown in figure B.8.

Figure B.8. Wireshark asks where XQuartz is installed the first time it runs.

This dialog is asking for the location of XQuartz. You can find XQuartz by selecting Browse..., navigating to the Application > Utilities > XQuartz app, and then clicking Choose. Wireshark should ask you this only the first time it runs; after that, Wireshark should start right up. Note that the first time Wireshark runs, it may take a long time to appear while it refreshes its fonts.

Installing Wireshark on Linux

Wireshark can be installed on Debian-based Linux simply by running

> sudo apt-get install wireshark

Once this finishes running, Wireshark will be installed. To be able to run Wireshark without it requiring root permissions, you need to run the following commands:

> sudo dpkg-reconfigure wireshark-common

> sudo adduser $USER wireshark

These commands will give your user account the proper permissions for running Wireshark. Once that is done, you’ll need to restart your system. After the restart, you can run Wireshark simply by typing wireshark.

B.2.2. Fiddler

Fiddler is a Windows-only app with a ton of networking-related features, including capturing network traffic. Fiddler can be downloaded from www.telerik.com/fiddler. The download page allows you to choose between Fiddler4 and Fiddler2. If you know you have .NET 4 installed or have Windows 8+, choose Fiddler4, otherwise choose Fiddler2.

Installing Fiddler is as simple as running the installer and following the instructions.

Note

There is also a relatively new port of Fiddler for Mac OS X and Linux. You can find it at http://fiddler.wikidot.com/mono.

B.2.3. Curl

The curl website is at http://curl.haxx.se/. To help you download the correct version of curl for your OS, there is also a handy download wizard at http://curl.haxx.se/dlwiz/?type=bin.

Installing curl on Windows

Some versions of PowerShell already have a tool called “curl”. But this tool is not the curl you’re looking for. You can check which curl you have by running curl --version. If you receive an error like that shown in figure B.9, you don’t have the correct curl tool.

Figure B.9. PowerShell’s curl tool

You can use the curl download wizard to download the curl installer for Windows. I recommend using an MSI file, which can be downloaded at www.confusedbycode.com/curl/#downloads. Run the installer to install curl. The installer installs curl to the C:\Program Files\cURL\bin directory.

You can verify that curl is installed properly simply by typing curl --version. If curl still doesn’t work, it could be that Windows doesn’t know where to find the tool. This can be fixed by adding the curl directory to your $PATHvariable. You can do that with the following steps:

1. Right-click your computer and choose Properties to enter the System Properties dialog. (If you don’t see a window with tabs, click Advanced System Settings.)

2. Choose the Advanced tab.

3. Choose the Environment Variables button.

4. In the User Variables window, select the PATH variable and click the Edit button. If there’s no such variable, add it using the New... button.

5. Add the value "C:\Program Files\cURL\bin" (including the quotes) to the path. If there is already a value in this box, you can add a new one by adding a semicolon followed by the path.

After doing this, curl should work from the command line (although you may have to reopen your command prompt for the changes to take effect).

Installing curl on Mac OS X

Curl comes preinstalled on OS X, so you shouldn’t need to install it. If curl isn’t available on your system, you can download and install it from the curl download wizard.

Installing curl on Linux

Curl may be preinstalled on some Linux systems; you can check by typing curl --version. If curl is not installed, you can install it by typing sudo apt-get install curl.

B.3. Resources

This appendix introduces a lot of tools. If you’d like to learn more about any of these tools, here are pointers to their websites:

· Node.js/NPM, http://nodejs.org

· Express, http://expressjs.com

· Wireshark, http://wireshark.org

· Fiddler, www.telerik.com/fiddler

· Curl, http://curl.haxx.se/

In addition, here are a couple books that dive into more details about Node.js and Express:

· Node.js in Action (Cantelon et al., Manning, 2013)

· Express.js in Action by Evan Hahn, to be published by Manning (http://manning.com/hahn/).