Appendix A. Installation Guides

This appendix provides an installation guide and setup instructions to support the code examples in this book.

Install JSON Tools in the Browser

This section shows how to install JSON-based tools in the browser.

Install JSONView in Chrome and Firefox

JSONView pretty-prints JSON in Chrome or Firefox. Follow the installation instructions on the JSONView site for your browser.

JSONLint

Use JSONLint to validate JSON documents online. JSONLint doesn’t require an installation.

JSON Editor Online

Use JSON Editor Online to model JSON documents. Since this is a web app, there’s nothing to install.

Install Postman

Postman provides the ability to fully test a RESTful API. It can send HTTP GET, POST, PUT, and DELETE requests and set HTTP headers. You can install Postman as a Chrome extension or as a standalone GUI application on macOS, Linux, or Windows. Visit the Postman site for installation instructions.

Install Node.js

This book uses Node.js version v6.10.2, which is the current latest stable version as of this writing.

Install Node.js on macOS and Linux with NVM

Although you could use the installation package from the Node.js site, it’s difficult to change versions. Instead, let’s use Node Version Manager (NVM). NVM makes it easy to install/uninstall Node.js, and upgrade to newer versions.

Install and configure NVM

First, install NVM by using one of the following methods:

Next, let’s make sure that NVM runs properly. Source it from a shell as follows:

source ~/.nvm/nvm.sh

Now NVM will work properly for the remainder of the installation process.

If you’re running bash, do the following so that NVM is automatically sourced (configured):

  • In $HOME/.bashrc, add these lines:

source ~/.nvm/nvm.sh export NVM_HOME=~/.nvm/v6.10.2
  • In $HOME/.bashrc_profile, add this line:

[[ -s $HOME/.nvm/nvm.sh ]] && . $HOME/.nvm/nvm.sh # This loads NVM

Note that similar steps apply to the Bourne Shell or Korn Shell.

Install Node.js with NVM

Now that NVM is installed, use it to install Node.js:

  1. Type nvm ls-remote to see what remote (not on your local machine) versions of Node.js are available to install.

  2. Install version v6.10.2 with the following command:

    nvm install v6.10.2
    • All Node.js versions are installed in $HOME/.nvm.

  3. Set the default Node.js version to be used in any new shell:

    nvm alias default v6.10.2
    • Without this, neither the node or npm commands will work properly when you exit the current shell.

    • Now, exit your current shell.

From a new shell, upgrade to the latest version of npm:

npm update -g npm

Then, do the following health checks:

  • nvm ls, and you should see ... -> v6.10.2 system default -> v6.10.2

  • node -v, which yields v6.10.2

  • npm -v, and it looks like 4.6.1

To see a full list of NVM’s capabilities, type nvm --help.

When you check out the Node.js Request-Eval-Print-Loop (REPL), you should see this:

json-at-work => node
-> .exit

Avoiding sudo with npm

npm may require you to run as sudo, and this can get cumbersome and annoying. This also can be a security risk because packages can contain scripts, and npm is running with root privilege. To avoid this, do the following:

sudo chown -R $USER ~/.nvm

This works if you installed Node.js with NVM (all Node.js installations go under that directory). This tip was inspired by Isaac Z. Schlueter from How to Node.

Taming the REPL—mynode

Out of the box, the default behavior of the REPL leaves a bit to be desired because you see undefined after most lines of JavaScript, hitting the Enter key, breathing, and so forth. This is because JavaScript functions always return something. If nothing is returned, undefined is returned by default. This behavior can be annoying and unproductive. Here’s a sample session:

json-at-work => node
-> Hit Enter
-> undefined

-> var y = 5
-> undefined
-> .exit

To turn off undefined in the REPL, add the following to .bashrc (or your setup for Bourne or Korn Shell):

source ~/.nvm/nvm.sh

...

alias mynode="node -e \"require('repl').start({ignoreUndefined: true})\""

Now, exit the current shell and start a new shell. Rather than redefining node, it’s safer to define a new alias (in this case, mynode). This way, node will still work properly from the command line and be able to run JavaScript files. Meanwhile, mynode serves as your new REPL command:

json-at-work => mynode
-> var x = 5
-> .exit

You now have a Node.js REPL that does what you want—no more annoying undefined. You’re welcome.

Install Node.js on Windows

NVM also works well on Windows thanks to Corey Butler’s nvm-windows application. This is a port of nvm to a Windows environment. I successfully used nvm-windows on Windows 7.

Install Node.js on Windows with nvm-windows

Here are the steps:

  1. Visit the nvm-windows Downloads page.

  2. Download the latest nvm-setup.zip to your Downloads folder.

  3. Unzip nvm-setup.zip with your favorite zip tool.

  4. Run nvm-setup.exe, which is a wizard. Accept all defaults and the MIT License agreement:

    1. Download to C:\Users{username}\AppData\Roaming\nvm.

    2. Click Finish when the install completes.

    3. This sets up the necessary environment variables to run Node.js on your Windows machine.

  5. Ensure that NVM is on your PATH:

    1. Navigate to Control Panel → System → Advanced System Settings.

    2. Click Environment Variables on the Advanced System Settings pop up.

    3. NVM_HOME should have been added to Env Vars during install: C:\Users{username}\AppData\Roaming\nvm

    4. NVM_SYMLINK should point to C:\Program Files\nodejs

    5. Both NVM_HOME and NVM_SYMLINK should be on the PATH.

  6. Install Node.js with nvm-windows:

    1. Type nvm list available to get a list of available versions.

    2. Type nvm install v6.10.2

    3. Set the version of Node.js: nvm use v6.10.2

    4. Test the install: node -v

Uninstall Node.js

If you have a previous installation of Node.js that isn’t quite working properly anymore, you may need to completely uninstall it from your machine. This includes both the node and npm executables.

Uninstall Node.js on macOS

Uninstalls can be complicated, and credit for the Mac uninstall instructions goes to Clay at Hungred Dot Com. If Homebrew was used to install Node.js, simply type brew uninstall node at the prompt.

If you didn’t use Homebrew, do the following:

  • cd to /usr/local/lib and delete any node executable and node_modules.

  • cd to /usr/local/include and delete any node and the node_modules directory.

  • cd to /usr/local/bin and delete any node executable.

You may also need to do the following:

rm -rf /usr/local/bin/npm
rm -rf /usr/local/share/man/man1/node.1
rm -rf /usr/local/lib/dtrace/node.d
rm -rf $USER/.npm

Uninstall Node.js on Linux

Credit for the Linux uninstall instructions goes to Stack Overflow and GitHub. Do the following:

  1. Find the node installation by typing which node. Let’s assume it’s at /usr/local/bin/node.

  2. cd to /usr/local.

  3. Execute the following:

sudo rm -rf bin/node
sudo rm -rf bin/npm
sudo rm -rf lib/node_modules/npm
sudo rm -rf lib/node
sudo rm -rf share/man/*/node.*

Uninstall Node.js on Windows

Credit for the Windows uninstall instructions goes to Team Treehouse. Here are the steps:

  1. Open the Windows Control Panel.

  2. Choose Programs and Features.

  3. Click “Uninstall a program.”

  4. Select Node.js, and click the Uninstall link.

Install Yeoman

Yeoman consists of the following:

  • yo (for Scaffolding)

  • Either npm or bower (for Package Management)

  • Either gulp or grunt (for the Build System)

For the code examples in this book, you’ll need both gulp and grunt-cli for the Build System. Although gulp is used as the primary build tool, you still need grunt-cli to run some of the gulp tasks.

I chose bower for Package Management.

Here are the installation steps:

  • Install yo:

    • npm install -g yo

    • Test the yo installation: yo --version

  • Install bower:

    • npm install -g bower

    • Test the bower installation: bower --version

  • Install gulp:

    • npm install -g gulp-cli

    • Test the gulp installation: gulp --version

  • Install grunt-cli:

    • npm install -g grunt-cli

    • Test the grunt-cli installation: grunt --version

Refer to the Yeoman setup page for more information.

Install the generator-webapp Yeoman generator

See the generator-webapp GitHub page. Install the generator as follows:

npm install -g generator-webapp

Install npm Modules

We use the following npm modules at the command line, so we install them globally:

Install jsonlint

This is the npm equivalent of the JSONLint site used to validate a JSON document. You can find jsonlint in the GitHub repository.

To install:

npm install -g jsonlint

To validate a JSON document:

jsonlint basic.json

Install json

json provides the ability to work with JSON (e.g., pretty-printing) from the command line. It’s similar to jq, but not as powerful.

To install:

npm install -g json

Visit the json GitHub repository for usage instructions. json is available as an npm module.

Install ujs-jsonvalidate

This is the npm equivalent of the JSON Validate site used to validate a JSON document against a JSON Schema. ujs-jsonvalidate can be found in the GitHub repository.

To install:

npm install -g ujs-jsonvalidate

To validate a JSON document:

validate basic.json basic-schema.json

Install http-server

http-server is a simple Web Server that serves up files in the current directory structure on the local host system as static content. I like http-server because it has solid documentation, and the command-line options and shutdown are intuitive. Here’s the http-server in the GitHub Repository and http-server in the npm repository.

To install:

npm install -g http-server

To run:

http-server -p 8081

To access:

http://localhost:8081

To shut down: press Ctrl-C

Install json-server

json-server is a Stub REST server that takes a JSON file and exposes it as a RESTful service. You can find json-server in the GitHub repository.

To install:

npm install -g json-server

To run:

json-server -p 5000 ./speakers.json

To access:

http://localhost:5000/speakers

Install Crest

Crest is a small REST server that provides a RESTful wrapper for MongoDB. You can find Crest in the GitHub Repository. The global npm installation would be the simplest way to install Crest, but this is broken. Instead, do a git clone as follows:

  1. cd to the directory where your other development projects reside. We’ll call this directory projects:

    cd projects
  2. Clone the repository:

    git clone git://github.com/Cordazar/crest.git
  3. Navigate to the crest directory:

    cd crest
  4. Update the config.json file to remove the username and password. Of course, this isn’t secure, but you can re-add these fields and set them to proper values later; just make sure that the settings match your MongoDB password. We just want to get started quickly. The config.json file should now look like this:

    {
      "db": { "port": 27017, "host": "localhost" },
      "server": { "port": 3500, "address": "0.0.0.0" },
      "flavor": "normal",
      "debug": true
    }
  5. Be sure to install and start MongoDB first.

  6. In a separate tab or command shell, start Crest by typing node server on the command line. You should see the following:

    node server
    
    DEBUG: util.js is loaded
    DEBUG: rest.js is loaded
    crest listening at http://:::3500

Install jq-tutorial

jq-tutorial is an npm module that provides a nice jq tutorial from the command line. Install it as follows:

npm install -g jq-tutorial

Then run it from the command line:

jq-tutorial

Install Ruby on Rails

There are several ways to install Ruby on Rails:

Install Rails on macOS and Linux

I prefer RVM for macOS and Linux because it’s easy to upgrade to switch between Ruby versions. Install RVM by visiting the RVM site and following the installation instructions.

Use RVM to install Ruby as follows:

  1. See the available versions of Ruby:

    rvm list known
  2. Install Ruby v2.4.0 as follows:

    rvm install 2.4.0
  3. Check the Ruby version, and you should see something like this:

    ruby -v
    ruby 2.4.0
  4. After installing Ruby, you can install Rails as follows:

    gem install rails
  5. Check the Rails version, and it should look like this:

    rails -v
    Rails Rails 5.0.2

And you’re done.

You can easily upgrade to new versions of Ruby and Rails by following these steps:

  1. Install a new version of Ruby (2.x for example):

    rvm install 2.x
  2. Use the new version:

    rvm use 2.x
  3. Install the rails gem as shown previously.

Install Rails on Windows

Use Rails Installer for a Windows environment, and do the following:

  • Download the installer for Windows.

  • Run the installer and follow the defaults.

I’ve used Rails Installer on Windows 7, and it worked properly. The Rails Installer page has excellent information on RoR tutorials and how to get help with installation issues.

Install Ruby Gems

We use the following Ruby gems outside Rails, so we install them globally:

Install multi_json

multi_json provides a wrapper that invokes the most common JSON gems on behalf of the caller by choosing the fastest JSON gem that has been loaded in an application’s environment. Install it as follows:

gem install multi_json

Install oj

Optimized JSON (oj), is considered by many to be the fastest Ruby-based JSON processor available. Install it as follows:

gem install oj

Install awesome_print

awesome_print pretty-prints a Ruby object and is used for debugging purposes. Install it as follows:

gem install awesome_print

Install activesupport

activesupport provides functionality that has been extracted from Rails. ActiveSupport’s JSON module provides the ability to convert keys between camel case and snake case. Install it as follows:

gem install activesupport

Install mailcatcher

mailcatcher is a simple mail (SMTP) server. It’s a great tool for testing emails without forcing you to send a real email. Install it as follows:

gem install mailcatcher

Install MongoDB

See the MongoDB installation documentation and follow the instructions to install and start MongoDB on your platform.

Install the Java Environment

Our Java environment depends on the following:

Install Java SE

We’re using Java Standard Edition (SE) 8 for this book, so visit the Oracle Java SE 8 download site.

You’ll see the term JDK (for Java Developer Kit) on that page. JDK is the old name for Java SE. Just look for Java SE Development Kit, accept the license agreement, and do the proper download for your operating system. After you’ve downloaded and run the installer, you’ll want to set up your Java command-line environment for your operating system.

Follow the instructions that follow for you system. Then run this:

java -version

You should see something similar to this

java version "1.8.0_72"
Java(TM) SE Runtime Environment (build 1.8.0_72-b15)
Java HotSpot(TM) 64-Bit Server VM (build 25.72-b15, mixed mode)

Java setup on macOS

In .bashrc, do the following to set up JAVA_HOME and add it to your PATH:

...

export
JAVA_HOME=/Library/Java/JavaVirtualMachines/jdk1.x.y.jdk/Contents/Home #
x and y are the minor and patch versions

...

export PATH=...:$\{JAVA_HOME}/bin:...

Java setup on Linux

In .bashrc, do the following to set up JAVA_HOME and add it to your PATH:

...

export JAVA_HOME=/usr/java/jdk1.x.y/bin/java # x and y are the minor and
patch versions

...

export PATH=...:$\{JAVA_HOME}/bin:...

Then, refresh your environment:

source ~/.bashrc

Credit for Java setup on Linux goes to nixCraft.

Java setup on Windows

The Java Windows Installer usually puts the JDK in one of the following directories: C:\Program Files\Java or C:\Program Files (x86)\Java.

Then, do the following:

  1. Right-click the My Computer icon on your desktop and select Properties.

  2. Click the Advanced tab.

  3. Click the Environment Variables button.

  4. Under System Variables, click New.

  5. Enter the variable name as JAVA_HOME.

  6. Enter the variable value as the installation path for the Java Development Kit (see where the installer put the JDK directory).

  7. Click OK.

  8. Click Apply Changes.

Credit for the Java setup on Windows goes to Robert Sindall.

Install Gradle

Gradle is used for building source and test code. Visit the Gradle Installation Guide and follow the instructions for your operating system. After you’ve completed the installation, run gradle -v from the command line and you should see something like this:

gradle -v

------------------------------------------------------------
Gradle 3.4.1
------------------------------------------------------------

On macOS, I succesfully used Homebrew to install Gradle.

Install jq

jq provides JSON-based command-line processing. To install it, just follow the download instructions on the jq GitHub repository.

jq works with and depends on cURL.

Install cURL

cURL provides the ability to communicate over multiple protocols, including HTTP. Use this to make HTTP calls to RESTful APIs from the command line.

Install cURL on macOS

Just as with Linux, cURL may already be installed on your Mac. Check it as follows:

curl --version

If it’s already there, there’s nothing else to do. Otherwise, you’ll need to install it. I use Homebrew as my package installer on macOS, so use the following command to install cURL on a Mac:

brew install curl

Install cURL on Linux

Check whether cURL is already installed by entering the following command:

curl --version

If it isn’t there, do the following from the command line:

sudo apt-get install curl

This should work on Ubuntu or Debian.

Install cURL on Windows

To install cURL on Windows, do the following:

  1. Visit the cURL Download Wizard.

  2. Select the type of package: curl executable.

  3. Select the Operating System: either Windows/Win32 or Win64.

  4. Select the Flavor: either Cygwin (if you use Cygwin) or Generic (if you don’t use Cygwin).

  5. Select the Win32 version (only if you selected Windows/Win32 previously): Unspecified.

Credit for the cURL Windows installation instructions goes to Stack Overflow.

Install Apache Kafka

We use Apache Kafka in Chapter 10 for JSON-based messaging. Kafka depends on Apache ZooKeeper so you’ll need to install ZooKeeper, too. Before going any further, be sure to install the Java Environment on your machine (because Kafka is based on Java).

Install Kafka on macOS

Homebrew is the easiest way to install Kafka on macOS. Do the following from the command line:

brew install kafka

This installs both Kafka and ZooKeeper. You’re done.

Install Kafka on UNIX

Install ZooKeeper as follows:

  • Download ZooKeeper from the ZooKeeper Releases page.

  • Extract the TAR file from the GZipped file you downloaded (current/latest ZooKeeper download):

tar -zxf ZooKeeper-3.4.9.tar.gz
  • Add system environment variables in ~/.bashrc:

export ZooKeeper_HOME = <Zookeeper-Install-Path>/zookeeper-3.4.9
export PATH=$PATH:$ZOOKEEPER_HOME/bin

Install Kafka as follows:

  1. Download Kafka from the Kafka Downloads page.

  2. Extract the TAR file from the GZipped file you downloaded (current/latest Kafka download):

    tar -zxf  kafka_2.11-0.10.1.1.tgz
  3. Add system environment variables in ~/.bashrc:

export KAFKA_HOME = <Kafka-Install-Path>/zookeeper-3.4.9
export PATH=$PATH:$KAFKA_HOME/bin

Credit for the Apache Kafka installation on UNIX instructions goes to TutorialsPoint.

Install Kafka on Windows

Install ZooKeeper as follows:

  1. Download ZooKeeper from the ZooKeeper Downloads page.

  2. Use your favorite zip tool to unzip the ZooKeeper file to the C: drive.

  3. Add System Variables as follows:

    1. In Windows, navigate to Control Panel → System → Advanced System Settings → Environment Variables.

    2. Create the following new System Variable (current/latest ZooKeeper download):

      ZOOKEEPER_HOME = C:\zookeeper-3.4.9
    3. Add ZooKeeper to your PATH by editing that variable and adding this at the end:

      ;%ZOOKEEPER_HOME%\bin;

Install Kafka as follows:

  1. Download Kafka from the Kafka Downloads page.

  2. Use your favorite zip tool to unzip the Kafka file to the C: drive.

  3. Add System Variables as follows:

    1. In Windows, navigate to Control Panel → System → Advanced System Settings → Environment Variables.

    2. Create the following new System Variable (current/latest Kafka download):

      KAFKA_HOME = C:\kafka_2.11-0.10.1.1
    3. Add Kafka to your PATH by editing that variable and adding this at the end:

      ;%KAFKA_HOME%\bin;

Credit for the Apache Kafka installation on Windows instructions goes to Gopal Tiwari’s article on DZone.

References