This appendix provides an installation guide and setup instructions to support the code examples in this book.
This section shows how to install JSON-based tools in the browser.
JSONView pretty-prints JSON in Chrome or Firefox. Follow the installation instructions on the JSONView site for your browser.
Use JSONLint to validate JSON documents online. JSONLint doesn’t require an installation.
Use JSON Editor Online to model JSON documents. Since this is a web app, there’s nothing to install.
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.
This book uses Node.js version
v6.10.2, which is the current latest
stable version as of this writing.
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.
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.
Now that NVM is installed, use it to install Node.js:
Type nvm ls-remote to see what remote (not on your local
machine) versions of Node.js are available to install.
Install version v6.10.2 with the following command:
nvm install v6.10.2
All Node.js versions are installed in $HOME/.nvm.
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
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.
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.
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.
Here are the steps:
Visit the
nvm-windows
Downloads page.
Download the latest nvm-setup.zip to your Downloads folder.
Unzip nvm-setup.zip with your favorite zip tool.
Run nvm-setup.exe, which is a wizard. Accept all defaults and the MIT License agreement:
Download to C:\Users{username}\AppData\Roaming\nvm.
Click Finish when the install completes.
This sets up the necessary environment variables to run Node.js on your Windows machine.
Ensure that NVM is on your PATH:
Navigate to Control Panel → System → Advanced System Settings.
Click Environment Variables on the Advanced System Settings pop up.
NVM_HOME should have been added to Env Vars during install: C:\Users{username}\AppData\Roaming\nvm
NVM_SYMLINK should point to C:\Program Files\nodejs
Both NVM_HOME and NVM_SYMLINK should be on the PATH.
Install Node.js with
nvm-windows:
Type nvm list available to get a list of available versions.
Type nvm install v6.10.2
Set the version of Node.js: nvm use v6.10.2
Test the install: node -v
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.
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
Credit for the Linux uninstall instructions goes to Stack Overflow and GitHub. Do the following:
Find the node installation by typing which node. Let’s assume it’s
at /usr/local/bin/node.
cd to /usr/local.
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.*
Credit for the Windows uninstall instructions goes to Team Treehouse. Here are the steps:
Open the Windows Control Panel.
Choose Programs and Features.
Click “Uninstall a program.”
Select Node.js, and click the Uninstall link.
Yeoman consists of the following:
yo (for Scaffolding)
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.
See the generator-webapp GitHub
page. Install the generator as follows:
npm install -g generator-webapp
We use the following npm modules at the command line, so we install them globally:
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
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.
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
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
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
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:
cd to the directory where your other development projects reside.
We’ll call this directory projects:
cd projects
Clone the repository:
git clone git://github.com/Cordazar/crest.git
Navigate to the crest directory:
cd crest
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}
Be sure to install and start MongoDB first.
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
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
There are several ways to install Ruby on Rails:
Ruby Version Manager (RVM) + the rails gem
rbenv + the rails gem
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:
See the available versions of Ruby:
rvm list known
Install Ruby v2.4.0 as follows:
rvm install 2.4.0
Check the Ruby version, and you should see something like this:
ruby -v ruby 2.4.0
After installing Ruby, you can install Rails as follows:
gem install rails
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:
Install a new version of Ruby (2.x for example):
rvm install 2.x
Use the new version:
rvm use 2.x
Install the rails gem as shown previously.
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.
We use the following Ruby gems outside Rails, so we install them globally:
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
Optimized JSON (oj), is considered by
many to be the fastest Ruby-based JSON processor available. Install it
as follows:
gem install oj
awesome_print
pretty-prints a Ruby object and is used for debugging purposes. Install
it as follows:
gem install awesome_print
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
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
See the MongoDB installation documentation and follow the instructions to install and start MongoDB on your platform.
Our Java environment depends on the following:
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)
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.
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:
Right-click the My Computer icon on your desktop and select Properties.
Click the Advanced tab.
Click the Environment Variables button.
Under System Variables, click New.
Enter the variable name as JAVA_HOME.
Enter the variable value as the installation path for the Java Development Kit (see where the installer put the JDK directory).
Click OK.
Click Apply Changes.
Credit for the Java setup on Windows goes to Robert Sindall.
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.
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.
cURL provides the ability to communicate over multiple protocols, including HTTP. Use this to make HTTP calls to RESTful APIs from the command line.
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
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.
To install cURL on Windows, do the following:
Visit the cURL Download Wizard.
Select the type of package: curl executable.
Select the Operating System: either Windows/Win32 or Win64.
Select the Flavor: either Cygwin (if you use
Cygwin) or Generic (if you don’t use
Cygwin).
Select the Win32 version (only if you selected Windows/Win32 previously): Unspecified.
Credit for the cURL Windows installation instructions goes to Stack Overflow.
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).
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 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:
Download Kafka from the Kafka Downloads page.
Extract the TAR file from the GZipped file you downloaded (current/latest Kafka download):
tar -zxf kafka_2.11-0.10.1.1.tgz
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.
Download ZooKeeper from the ZooKeeper Downloads page.
Use your favorite zip tool to unzip the ZooKeeper file to the C:
drive.
Add System Variables as follows:
In Windows, navigate to Control Panel → System → Advanced System Settings → Environment Variables.
Create the following new System Variable (current/latest ZooKeeper download):
ZOOKEEPER_HOME = C:\zookeeper-3.4.9
Add ZooKeeper to your PATH by editing that variable and adding this at the end:
;%ZOOKEEPER_HOME%\bin;
Install Kafka as follows:
Download Kafka from the Kafka Downloads page.
Use your favorite zip tool to unzip the Kafka file to the C: drive.
Add System Variables as follows:
In Windows, navigate to Control Panel → System → Advanced System Settings → Environment Variables.
Create the following new System Variable (current/latest Kafka download):
KAFKA_HOME = C:\kafka_2.11-0.10.1.1
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.
The AsciiDoc version of Appendix A in the book was generated by Pandoc from the original Markdown in the JSON at Work GitHub examples repository.