Table of content

• The traditional way to run a node app

• Dockerizing Node.js app

The traditional way to run a node app

It is not required to know to code to get started with Docker. But you need to know how to run the application that you are intending to dockerize. Let’s consider one of the node apps that I build during learning node.js and express. Before jumping into Docker, I would like to show you how you can run this node app in your local machine. The steps are:

• Step 1: Install git

• Step 2: Install Node and NPM

• Step 3: Clone Git repository

• Step 4: Run web app

Step 1: Install Git

You will find great guidelines from here about installing git for your local machine ( Linux, Mac, or Windows).

Step 2: Install Nodejs and NPM

Download and install node.js from the official site. Versions should be at least 10 or higher 10. Once you are done, open a terminal, and verify the installation:

$ node -v
$ npm -v

Step 3: Clone the git repository

Open your terminal or PowerShell. Run down the following command to clone the git repository.

$ git clone https://github.com/humayun-rashid/covid-19-node-app.git

Step 4: Run the web app

Let’s install our npm dependencies that are listed in package.json. You will find the package file in the repository. Run the following command in your terminal to install the dependencies.

$ npm install

Once you are done with the dependencies installation, the app can be started with the following line of command and you can see that the server will start running in port 3000.

$ node server.jsServer is running in port 3000

Open your favourite browser and visit the following link to access the application.

http://localhost:3000

You should see something like the following:

Write down some country’s name and it should give output. To stop the server, you need to press ctrl + c.

Dockerizing Node.js app

The steps to create an image and push it to a registry using docker are listed below:

• Step 1: Install Docker

• Step 2: Create Dockerfile

• Step 3: Build and run the image

• Step 4: Tag an image and push it to the registry

• Step 5: Stop the container and cleanup

Step 1: Install Docker

I will recommend installing a docker desktop for Mac and Windows users from here. Ubuntu users can run the following commands to install Docker.

$ sudo apt-get update
$ sudo apt-get remove docker docker-engine docker.io
$ sudo apt install docker.io
$ sudo systemctl start docker
$ sudo systemctl enable docker

You should test if the docker is working fine after installation. Open your terminal and run the following command:

$ docker --version
$ docker run hello-word

I also run a base image and echo a message to verify if the docker is functioning properly.

$ docker run alpine:latest "echo" "Hello, World"

Step 2: Create Dockerfile

Create a file in the same directory named “Dockerfile” without any extension. I am using Visual Studio Code to edit my Dockerfile. If you are in Ubuntu or Mac, you can create a new Docker configuration file from the terminal within the same directory by running:

$ touch Dockerfile

Add the following configuration first, It might not make any sense right now if you are new to this but I am going to explain what’s happening here later.

# Base Image
FROM node:10# Create app directory
WORKDIR /usr/src/app# Install app dependencies
COPY package*.json ./# Install dependencies
RUN npm install# Bundle app source
COPY . .#Expose port to 3000
EXPOSE 3000# Add command to run
CMD [ "node", "server.js" ]

Base Image: The first line defines a base image that we are going to use to build our app. We have chosen a base image that has already node and npm, so we don’t need to install it additionally.

# Base Image
FROM node:10

Work directly: The next line is for creating a working directory for our app in the base image.

# Create app directory
WORKDIR /usr/src/app

Dependency install: In the next step, app dependencies will be installed. First, the package.json file will be copied to the directory, and then the npm install command will be executed to install essential packages.

# Install app dependencies
COPY package*.json ./# Install dependencies
RUN npm install

Copy to work directory: In the next step, COPY will be used to copy all the content of the app directory to the container’s working directory.

# Bundle app source
COPY . .

Port expose: The app needs to be exposed to the port 3000 using the EXPOSE instruction.

EXPOSE 3000

Command: To start our server CMD will be used. Commands need to be separated by a comma.

CMD [ "node", "server.js" ]

Step 3: Build and run the image

Once Dockerfile is written and placed in the same directory, the following command can build the image.

$ docker build -t covid-19:latest .

Now, run the following command to check if the image has been created properly.

$ docker images

It should list all the images. To run the image, use the following command.

$ docker run --rm --name covid-19 -it -p 3000:3000 covid-19:latest

--rm: The container is removed when it exits or when the daemon exits.

--name: Define a name for the container. If it is not used, then the daemon generates a random string name.

-it: To be able to do interactive processes (e.g. bash/shell)

-p: It is used for port forwarding.

Now, open your browser and visit HTTP://localhost:3000 and you should see that your app is running.

Stop the container

You can not stop a container by pressing ctrl + cc from the same terminal. To stop a running container, you need to first open a new terminal and then run the following command to get the container ID.

docker ps

Now perform the following docker stop command with container ID to stop the running container.

docker stop [ID]

Run in detached mode

The container we were running previously was running in the attached mode. To start a container in detached mode, we need to provide -d . Run the following command, and you will notice that the container has started in detached mode.

$ docker run --rm --name covid-19 -d -it -p 3000:3000 covid-19:latest

If you want to attach again, list the running container, and run the command attach with your container name.

docker container ls
docker container attach covid-19

Bash shell in a terminal

To start using a bash shell inside of the container, the following command needs to be performed.

docker exec --rm --name covid-19 -it -p 3000:3000 covid-19:latest /bin/bash

• Another approach is to use the command at the end. The following command will list down all the files inside the container.

docker exec --rm --name covid-19 -it -p 3000:3000 covid-19:latest ls

Step 4: Tag an image and push to the registry

To push the image to the Docker registry, you need to create an account for the docker registry here. First, tag the image with the repository name and then push it using the following commands:

docker tag covid-19:latest (repo-name)/covid-19:latest
docker push (repo-name)/covid-19:latest

Step 5: Cleanup

To delete the image, first list all the images with image ID. Then use rmi the command with image ID to remove the image. You can use -f in the case of force image removal is needed.

$ docker imagesREPOSITORY                TAG                 IMAGE ID            CREATED             SIZE
test1                     latest              fd484f19954f        23 seconds ago      7 B (virtual 4.964 MB)
test                      latest              fd484f19954f        23 seconds ago      7 B (virtual 4.964 MB)
test2                     latest              fd484f19954f        23 seconds ago      7 B (virtual 4.964 MB)$ docker rmi fd484f19954f

Clean up all resources

It is possible to clean up all dangling resources (images, containers, volumes, and networks ) with one single command. Flag -a can be added to remove stopped containers and all unused images.

$ docker system prune
$ docker system prune -a

https://github.com/humayun-rashid/first-rest-api-medium.git

https://github.com/humayun-rashid/first-rest-api-medium.git

We will start by creating a new directory with a preferred name. In my case, I am naming it “first-rest-API”. Open the terminal and type the following command to create a new directory and navigate to the newly-created directory.

$ sudo mkdir rest-API-project
$ cd rest-API-project

After navigating to the directory, you can open visual studio code by writing the following command to your directory.

$ code .

Alternatively, you can create a repository in GitHub with your preferred project name such as “first-rest-api”. If you have already installed git by following the previous article, you should be able to clone the repository by the following command.

$ git clone "git repo url"

Then navigate to the directory and start visual studio code by running the following command.

$ cd rest-API-project
$ code .

Generate Package.json by NPM init

We will now start developing our RESTful API by generating the “package.json” file which is going to contain all the dependencies. This file will be updated when adding further dependencies during the development process. To generate “package.json”, run the following command in the terminal that will request some answers to questions to generate the file. To autofill, the question, “-y” can be added at the end of the command.

$ npm init
$ npm init -y

A “package.json” file will be created similar to the following in the project’s root directory.

{
  "name": "first-rest-api-medium",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "repository": {
    "type": "git",
    "url": "git+https://github.com/humayun-rashid/first-rest-api-medium.git"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "bugs": {
    "url": "https://github.com/humayun-rashid/first-rest-api-medium/issues"
  },
  "homepage": "https://github.com/humayun-rashid/first-rest-api-medium#readme"
}

Install Express Framework and Nodemon

for the next step, we are required to install Express to our project directory as well as save it in the dependencies list of “package.json”. The dependency can also be saved as “development dependency” in case it is required to be used only for development. The purpose of installing dependency as a development dependency is that package users will not be required to install it in production.

$ npm install express — save

To install Express temporarily and not add it to the dependencies list:

$ npm install express — no-save

Now, we are going to install a very cool tool known as no demon that allows a node.js application restarts automatically every time there is a change. Write the following command with “-g” that will allow installing the package as global so that it can be used from anywhere. The problem associated with the local installation of nodemon is that no demon will not be available in your system path and the local installation of nodemon can be run by calling it from within an npm script.

$ npm install -g nodemon

Nodemon can also be installed as a development dependency with the following command in the terminal.

$ npm install — save-dev nodemon

Create a Basic Server

Let’s start coding! First, we are going to create a file and name it as “server.js” in the project root directory. Run the following command in the terminal or create it from visual studio code.

$ sudo touch server.js

Now, we will start writing our code in “server.js”. First, we are going to import the “express” module. For the importing module, we are going to use the “require” function.

require(“express”)

The imported module is required to be in a variable. Variable can be declared as var, let or const. You can find details about variable declaration here :

https://dev.to/sarah_chima/var-let-and-const--whats-the-difference-69e

Variables declared with the const maintain constant values but variables with var can be updated. We are going to import “express” to a const variable. Then an instance of the imported module will be created through the “app” variable. the “app” is an instance of express. you can set the environment variable “PORT” to tell your web server what port to listen on. So process.env.PORT || 3000 means: whatever is in the environment variable PORT, or 3000 if there’s nothing there. So you pass that app.listen, or to app.set(‘port’, …), and that makes your server able to accept a parameter from the environment what port to listen on. If you pass 3000 hard-coded to app.listen(), you’re always listening on port 3000, which might be just for you, or not, depending on your requirements and the requirements of the environment in which you’re running your server.

const express = require(‘express’); // importing Express
const app = express(); // instance of express
const port = process.env.PORT || 3000; // Defining port by environmental parameter or 3000// Create a routing 
app.get(‘/’,function(req,res){
 res.send(‘Server is running.’)
})// App is listening to user-defined port or 300 and printing the information to the console.
app.listen(port, function(req,res){
 console.log(`Server is listening on port ${port}!`)
})

Run the server using the command :

$ node server.js

Now, go to the following URL to access the server.

http://localhost:3000

By going to this URL, we are sending a GET request through our web client. This is the concept of routing. We are going to discuss this later in this section. Now if we are going to make changes, we have to stop the server by pressing ctrl + c and then start the server again by using the above command. To avoid running the server again and again by running the same command, we are going to use the nodemon.

Go to the package.json and replace test in the script with the following:

"scripts": {
"devStart": "nodemon server.js"
}

Then you can start the server using nodemon by using the following command.

$ npm start devStart

Alternatively, you can directly start your server by running following command:

$ nodemon server.js

Now, whenever you make a code change, the server will automatically restart. Currently, our server is running in port 3000. We can also define our port through set or exporting the port parameter through env. If you want to run it just once, run the following command.

$ PORT=1234 node server.js

You don't have to restart the server as nodemon will do it automatically. To set the PORT More permanently, use the following command.

$ export PORT=3000
$ node server.js

For Windows, use the following command.

$ set PORT=3000

For Windows PowerShell:

$ env:PORT = 3000

Another method to set the env parameter is though dotenv package.

npm install dotenv

Add this line to the start of the server.

require(‘dotenv’).config()

Create a .env file in the root directory of your project. Add

PORT = 3000

create .gitignore because you don’t want to import .env to git.

So, our basic server is running. But currently, there is not routing that is configured. We are going to discuss the routing and configure some endpoints.

Routing

Routing refers to determining how an application responds to a client request to a particular endpoint, which is a URI (or path) and a specific HTTP request method (GET, POST, and so on). Each route can have one or more handler functions, which are executed when the route is matched. Route definition takes the following structure:

Route definition takes the following structure:

app.METHOD(PATH, HANDLER)

METHOD is an HTTP request method, in lowercase. PATH is a path on the server. HANDLER is the function executed when the route is matched. Write down the following code to create routing using GET, POST, PUT and DELETE methods.

require('dotenv').config()
const express = require('express'); 
const app = express(); // instance of express
const port = process.env.PORT || 3000; // GET requestapp.get('/', function (req, res) {
res.status(200).send('Server is up and running.')
})// POST requestapp.post('/', function (req, res) {
res.status(200).send('This is a POST request')
})// PUT Requestapp.put('/', function (req, res) {
res.status(200).send('This is a PUT request')
})// PATCH Requestapp.patch('/', function (req, res) {
res.status(200).send('This is a PATCH request')
})// DELETE Requestapp.delete('/', function (req, res) {
res.status(200).send('This is a DELETE request')
})// App is listening to user-defined port or 300 and printing the information to the console.app.listen(port, function (req, res) {
console.log(`Server is listening on port ${port}!`)
})

To test your routing, you need to have POSTMAN or any other API endpoint testing tool. But for simplicity, I am going to use REST Client, an extension in visual studio code to test endpoints. You can install it in your VS editor by Quick doing open (Ctrl+P) and paste the following command:

ext install humao.rest-client

Let's create a new file with extension rest. I am creating a test.rest to test endpoints. Now write down the following to start testing.

### GET Request
GET http://localhost:3000### POST Request
POST http://localhost:3000### DELETE Request
DELETE http://localhost:3000### PUT Request
PUT http://localhost:3000### PATCH Request
PATCH http://localhost:3000

There should be a 'Send Request' just above the request. You need to press it to test your endpoints.

If the request is successful, you should see output similar to following:

HTTP/1.1 200 OK 
X-Powered-By: Express 
Content-Type: text/html; 
charset=utf-8 
Content-Length: 25 
ETag: W/"19-mtGkfbkTqxz/NZr8uVnRPTJZzm8" 
Date: Fri, 03 Apr 2020 21:18:53 GMT 
Connection: close  Server is up and running.

In case endpoints are not working, it should return a 404 error similar like the following:

HTTP/1.1 404 
Not Found X-Powered-By: Express 
Content-Security-Policy: default-src 'none' 
X-Content-Type-Options: nosniff Content-Type: text/html; charset=utf-8 Content-Length: 140 
Date: Fri, 03 Apr 2020 21:20:29 GMT 
Connection: close  
<!DOCTYPE html> 
<html lang="en"> 
<head> <meta charset="utf-8"> 
<title>Error</title>
 </head> 
<body> <pre>Cannot GET /r</pre> </body> 
</html>

Folder Structure

The code we have just written is working just fine but to make it standard, we should not put all our code into a single script, with the time being, it will a large file with lots of coding and you will find it difficult to write more features. To solve this problem, we are going to split our code into several scripts. In our server.js, we are going to keep server handling code and we are going to create a different script that will contain all the routes. This script can be exported as a module and be called in server.js and all the endpoints should work like just before. Let’s create a new directory named ‘routes’ and create a file named ‘routes.js’.

mkdir routes
touch routes/routes.js

Let’s start writing code in routes.js. First, we will import express like before and then create an instance of express, but not in ‘app’ variable with ‘express()’, instead we are going to use as following:

const express = require(‘express’);
const router = express.Router();

Let’s take out the routing code from the server and place them in routes.js. We are going to replace our app.METHOD with router.METHOD. At the end, we need to export it as a module.

// GET requestrouter.get(‘/’, function (req, res) {
res.status(200).send(‘Server is up and running.’)
})// POST requestrouter.post(‘/’, function (req, res) {
res.status(200).send(‘This is a POST request’)
})// PUT Requestrouter.put(‘/’, function (req, res) {
res.status(200).send(‘This is a PUT request’)
})// PATCH Requestrouter.patch(‘/’, function (req, res) {
res.status(200).send(‘This is a PATCH request’)
})// DELETE Requestrouter.delete(‘/’, function (req, res) {
res.status(200).send(‘This is a DELETE request’)
})module.exports = router;

Now, we can use routes.js as modules and can call this module from our server.js. To do so, let’s add these following two lines to server.js:

const router = require(‘./routes/routes’)
app.use(‘/’,router)

There will be no routes in the server now. The final code of server.js will be as follows:

require(‘dotenv’).config()const express = require(‘express’); // importing Express
const app = express(); // instance of express
const port = process.env.PORT || 3000; // Defining port by environmental parameter or 3000const router = require(‘./routes/routes’)
app.use(‘/’,router)// App is listening to user-defined port or 300 and printing the information to the console.app.listen(port, function (req, res) {
console.log(`Server is listening on port ${port}!`)
})

Test the endpoints with the test.rest. It should return 200 http codes and all endpoints should just work fine.

Push your code to GitHub

Now you are done with coding and testing. Let’s push your code to your GitHub. I assume you have already installed git, else you can do so b following the command:

$ sudo apt install git$ git config — global user.name “username”$ git config — global user.email “email”

Run the following command to push your code to GitHub (It may ask for your git username and password) :

$ git add .$ git ommit -m “Your commit message”$ git push

Congratulations on your first rest api development! I enjoyed a lot writing these first two parts and I hope you have also enjoyed reading and creating your first API. In the next part, I am going to cover some more important topics. Ask me any questions if you face any kind of difficulties during following this article.

But wait a minute! You don’t know anything about NodeJS, along with Express and even JS. Now what?

Just don’t worry and sit tight. This is going to be several parts articles that will help you to get to know about RESTful API design and by the end of this series, you may not be a professional developer but still, you will learn a lot of good stuff.

Let’s get started with a little bit of description of RESTful API! Here it goes!

What is RESTful API

RESTful API is a client-server-based architecture that utilizes stateless operations to access and manipulate data through HTTP requests. REST stands for REpresentational State Transfer. One of the principal requirements of a Restful architecture is that it consists of two core elements, client and server. Clients request resources from the server to do different operations. RESTful API-based system is stateless as each request from the client to the server must contain all of the information that is essential to understand the request, and cannot take advantage of any stored context on the server. REST API is designed to create an endpoint for specific operations using HTTP protocol and CRUD functionality (CRUD stands for Create, Read, Update, Delete). HTTP defines a set of request methods to indicate the desired action to be performed for a given resource based on CRUD functionality. The HTTP protocols that are used for designing REST API are listed below.

• POST — create a resource or generally provide data

• GET — retrieve an index of resources or an individual resource

• PUT — create or replace a resource

• PATCH — update/modify a resource

• DELETE — remove a resource

Enough of talking! Let’s get started with hands-on.

RESTful API development by Node.js and Express: Setup and configure the development environment

To get started with reSTful API development, first, we need to create a development environment. The following things are needed to be installed and configured before the jump to coding. We will only use stacks that are open-source and free to use.

• Programming Stack and package manager -NodeJS & NPM

• Source code editor — Visual Studio Code / WebStorm (Editor)

• REST API Testing Tools — POSTMAN / Insomnia

• Version Control — GitHub

Node.js and NPM

NodeJS is Chrome’s V8 JavaScript engine-based runtime that is open-source, lightweight, efficient server and vastly used for developing a client-server-based application. The performance of NodeJs is non-blocking and asynchronous and it is an event-driven based runtime environment. The official package manager for Node is NPM.

Windows ( as well as MAC )

Download the required installer from the following link, install Node by double-clicking on the downloaded file and following the installation prompts.

https://nodejs.org/en/

Install Node via Homebrew ( MAC and Linux)

Homebrew simplifies the installation of software on the Mac OS X operating system. Install Homebrew for MAC or Linux using the following command :

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"

or you can also use the following command:

/usr/bin/ruby -e “$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
brew doctor

In the terminal type the following command to install Node.

brew install node

If everything installed successfully then you can type in the following command in the terminal to check the Node and NPM version.

node -v
npm -v

Ubuntu 18.04 (Install from Ubuntu binary distributions repository )

The easiest way to install the most recent LTS version of Node 10.x is to use the package manager to get it from the Ubuntu binary distributions repository. This can be done very simply by running the following two commands on the terminal:

curl -sL https://deb.nodesource.com/setup_10.x | sudo -E bash — 
sudo apt-get install -y nodejs

Install Source code editor ( Visual Studio Code)

Visual Studio Code is a source code editor developed by Microsoft for Windows, Linux, and macOS.It is a simple yet powerful and fast source code editor with support for hundreds of languages with features like syntax highlighting, bracket-matching, auto-indentation, box-selection, snippets, intuitive keyboard shortcuts, easy customization, and community-contributed keyboard shortcut mappings and many more. You can get started with visual studio code by downloading from the following links. It is important that turn on the autosave mode.

Linux:

https://code.visualstudio.com/docs/setup/linux

macOS:

https://code.visualstudio.com/docs/setup/mac

Windows:

https://code.visualstudio.com/docs/setup/windows

You need to install a plugin that will make your coding experience more fun. The plugin’s name is Prettier, that’s a tool that automatically covert messy code into a readable format. Install it from here:

https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode

RESTful API testing tools (Postman & Insomnia)

Postman is a collaboration platform for API development. We will use to test our endpoints that will be created during creating RESTful API. POSTMAN can be downloaded and install for Windows and MAC from here:

https://www.postman.com/downloads/

Postman is also available from google chrome store that can be used as Chrome extension :

https://chrome.google.com/webstore/detail/postman/fhbjgbiflinjbdggehcddcbncdddomop?hl=fi

Another famous tool for API testing is Insomnia. It is a free cross-platform desktop for interacting with HTTP-based APIs. Download insomnia from here:

https://support.insomnia.rest/article/11-getting-started

Setup GitHub

GitHub is an open-source repository hosting service with features of tracking changes in a changelog so that you can know exactly what has been changed in your code each time.

Linux

Open a terminal window. Copy & paste the following into the terminal window and hit Return. You may be prompted to enter your password.

sudo apt update
sudo apt upgrade
sudo apt install git

Mac

Copy & paste the following into the terminal window and hit Return.

brew install git

You can use Git now.

Windows

Git for windows can be downloaded from here:

https://gitforwindows.org/

If you are new to Git, I will suggest you read:

https://kbroman.org/github_tutorial/pages/first_time.html

You will eventually get a bit more understanding about configuring GitHub for the first time.

Enough of talking about setting up the environment. It is now time to start development. The second part of this article will guide you on how you can start coding to make your first API using node js and express. You can read it here.

Happy Coding!