Nearby Shops API Installation Guide for Ubuntu 16.04

In this article we will learn how we can install Nearby Shops API on ubuntu 16.04

Steps for API Installation

  1. Install OpenJDK 8
  2. Install Postgres Database Latest Version
  3. Create Database , add User, assign password and Grant Privileges
  4. Download Jar file and Configuration File
  5. Add / Update API Configuration
  6. Test jar file by running it
  7. Automate API jar file Execution using SystemD

Optional Tasks

  1. Add Swap space to the Server
  2. Create Domain Name for API

Remaining Tasks

  1. Setup Third Party Integrations
  2. Setup and Customize Android apps
  3. Getting Started as Admin

 

A word of Caution for Developers

Currently the API Authenticates using Basic Auth and Lacks TLS / SSL Security. When planning to run a production version of the app please add TLS encryption before you start a production server.

 

Enough of the Introduction and Let us now begin with the step by step installation Guide for Nearby Shops API Backend

Step 1 : Install OpenJDK 8

Our API Runs on Java therefore we need JDK on our machine. We can install Oracle JDK also. But we recommend you to install OpenJDK-8 the open-source version because by using Oracle JDK you might get trapped into licensing issues.

To stay on the safe side of licensing issues prefer to install the open source version.

To install OpenJDK 8

Type these commands on your terminal

sudo apt-get udpate
sudo apt-get install openjdk-8-jdk

in order to verify jdk has been installed type type “java -version”

java -version

The above command gives the following output which indicates that Java 8 has been installed

openjdk version “1.8.0_151”
OpenJDK Runtime Environment (build 1.8.0_151-8u151-b12-0ubuntu0.16.04.2-b12)
OpenJDK 64-Bit Server VM (build 25.151-b12, mixed mode)

 

Step 2 : Install Postgres Database Latest Version

We use postgres as our primary database therefore we need to install Postgres. Currently Postgres 10 is the latest version of Postgres therefore we will install Postgres 10.

The instructions to install Postgres 10 are given at the following link

http://yallalabs.com/linux/how-to-install-and-use-postgresql-10-on-ubuntu-16-04/

If these instructions do not work for you. You can always find a tutorial on Postgres Installation by searching on Google.

 

Step 3 : Create Database , add User and Grant Privileges to user in Postgres DB

We need to create new database and add new user with password. We will grant all privileges to use the database to the new user we have created.

After that please write and note the database name, username and password somewhere because we will require them in future.

The following article provides very good overview of what command will be required.

https://medium.com/coding-blocks/creating-user-database-and-adding-access-on-postgresql-8bfcd2f4a91e

Make sure you don’t use “postgres” as username and “password” as password. They are popular defaults and hackers look for them. Therefore using them as username and password is going to make your postgresql Installation vulnerable to hacking attacks.

 

Step 4 : Download Jar File and Configuration File

Head over to the Developer Guide page of this website. You will see the Downloads Section. From the downloads section copy the download link and  download the jar file and the api configuration file. If the files are available in zip format so you will need to unzip them after you have downloaded them.

After the download you are required to keep jar file and configuration file in one folder. The api jar file needs configuration file in order to execute.

Please note that you can also generate your own jar file using source code. Please refer the guide “generate fat jar / uber jar from source code” available in the developer guide.

You can download the files using the wget command from the terminal

cd ~
mkdir nearbyshops
cd nearbyshops

wget <download-link-for-jar-file>
wget <download-link-for-configuration-file>

In case the files are in zip format

unzip <jar-file-name.jar>
unzip <configuration-file-name.jar>

 

 

Step 8 : Add / Update API Configuration file

Type the following commands to edit the configuration file.

cd ~/nearbyshops
sudo nano api_config.properties

In the step 3 we created new Database and added a new user with username and password. We will now have to edit the configuration file and provide the database name and username and password.

In order to update the database name we will have to update the JDBC URl. The format of JDBC URL is given here

https://jdbc.postgresql.org/documentation/80/connect.html

jdbc:postgresql://host:port/database

If your host is localhost, port is 5432 and database name is nearbyshopsdb then your jdbc url would be  “jdbc:postgresql://localhost:5432/nearbyshopsdb”

Update the api configuration file with the new values for jdbc url and username and password

 

Step 6 : Test the jar file by running it

After you have edited the configuration file you can now run the Jar file and see whether it runs successfully.

Note : Before running the Jar file ensure that you have a configuration file with correct name. The of configuration file should be “api_config.properties”

 cd ~/nearbyshops
 java -jar ./nearby-shops-api-1.1.jar

 

 

Step 7 : Create systemd Unit script for auto restart the java process after being terminated

Sometimes the java process can terminate unexpectedly. This can happen due to unexpected server restart or even other technical reasons. Therefore we need a mechanism which automatically starts the process if it gets terminated. We also need to ensure that process starts automatically at server restart.

To solve this issue we will use SystemD init system available in Ubuntu Linux. SystemD is a system in linux which handles the execution of the programs. We will write a small script which will tell SystemD to restart our Java process if it gets terminated unexpectedly.

Please read the following article which will tell you how you can setup the auto restart mechanism for Java process using SystemD init system

https://nearbyshops.org/auto-restart-java-process-after-termination-or-system-reboot-on-ubuntu-16-04-using-systemd/

 

 

Optional Tasks

 

Step 1 : Add Swap Space to the API Server

If you wish to use the API server for the long term you need to add some swap space so that you dont face memory shortage.

https://www.digitalocean.com/community/tutorials/how-to-add-swap-space-on-ubuntu-16-04

You can add the swap space by following the instructions in the tutorial given in above link.

 

Step 2 : Configure Domain Name for the API

If you wish to use the API Server for a long duration or for a production usage. You must setup a domain name for the API server. This is necessary because the IP address of the API Server can change when you are doing some maintenance or for any other reason.

If you have a domain name you will not have to update the API Server URL in the android apps (client side) . If you have not set a domain name you will have to update the API Server URL in the android apps (client side) . This can be a huge headache.

Therefore you must assign a domain name for the API server.

An example for the domain name would be  [ api.nearbyshops.org ]

 

 

Remaining Tasks

 

Step 1 : Setup Third Party Integrations

To enable SMS-OTP, Email and Push Notifications you need to setup third party integrations. The guide for setting up third party Integrations is provided in the “Third Party Integrations” section available at the Developer Guide.

So head over to that guide and follow the instructions. Setting up SMS-OTP is mandatory for login. You cant login into the app unless you setup these basic third party integrations.

 

Step 2 : Setup and Customize the android apps

You need to customize the android apps where you need to change the URL for API server and set this to the URL of your own api server.

The complete guide for customizing the android apps is provided in the developer guide.

 

Step 3 : Getting started as Admin

After doing all the technical setup you need to read this guide which will tell you how to proceed and start as a administrator. This guide is available in the Developer Guide. So head over to Developer Guide and find it.

 

 

 


 

If you have any questions and queries feel free to ask in the comment. Have any difficulty in understanding anything let me know in the comments below ?