Install Nearby Shops on Ubuntu

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

Prerequisite Knowledge

To understand this installation guide you dont need to be an expert but having some basic knowledge of linux terminal commands, PostgreSQL Database and java will help you.

Steps for Installation

1. Install OpenJDK 8 or OpenJDK 11
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 Execution of API jar file using SystemD

Remaining Tasks

1. Create Domain name for the api
2. Setup third party Integrations
3. Login as Admin and Update app configuration
4. Submit your app to Nearby Shops Market Aggregator
5. Submit your app to Other Market Aggregators

Optional Tasks

1. Setup and Customize android apps
2. Add swap space to the 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 of the JDK to stay on the safe side of licensing.

To install OpenJDK 8. Type the following commands on your terminal

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

in order to verify jdk has been installed use the following commands

                     Code
                  
    java -version
                    
                

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

                     Output
                  
  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)
                    
                

For more information on JDK installation you can also refer to this guide JDK installation tutorial from Digital Ocean

Step 2 : Install PostgreSQL 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 and add User

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

After the above step please save the database name, username and password somewhere because we will require that in following steps. 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 Download 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.

You should keep the jar file and configuration file in one folder. Because api jar file needs configuration file in order to execute.

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

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

                     Code
                  
    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

                     Code
                  
  unzip [jar-file-name.jar]
  unzip [configuration-file-name.jar]
                  
                

Step 5 : Update API Configuration file

Use the following commands to edit the configuration file.

                     Code
                  
   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

                     Code
                  
   jdbc:postgresql://host:port/database
                  
                

If your host is localhost, port is 5432 and database name is nearbyshopsdb then your jdbc url would be

                     Code
                  
   jdbc:postgresql://localhost:5432/nearbyshopsdb
                  
                

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

Instructions to update the configuration are given in the configuration file. You can learn from those instructions how to configure the api.

Step 6 : Test the jar file by running it

After updating 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 name of the configuration file should be “api_config.properties”

Another Important Note : Please ensure that your jar file and api configuration file is in the same folder. If you dont keep them in same folder the execution will fail !

                     Code
                  
   cd ~/nearbyshops
   java -jar ./[file-name].jar

   Please Note : Replace file-name with the name of your file
                  
                

Verify Successful Execution : In order to verify and test that we have a successful connection to the api. We will test the endpoints to see if we get any result. The url for the endpoint is
[IP:port]/api/serviceconfiguration
Replace the IP and port number according to your installation. For example if you are running this jar file on your local computer at port address 1500 your url will be localhost:1500/api/serviceconfiguration when you execute this url in your browser you should see some json output.
Having the output verifies successful execution.

Step 7 : Configure SystemD to auto restart the java process

Sometimes the java process can terminate unexpectedly. This can happen due to unexpected server restart or other technical reasons. Therefore we need a mechanism which automatically restarts the java 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.

Dont worry you dont need to know anything about systemD just follow the instructions and you're done !

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

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 “Integrations” section.

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

Step 2 : Customize the android apps

Nearby Shops comes with three android apps one for Admin, one for shop owner and one for the end-user. To use the app for production use. You will be required to customize the apps to use your own brand name, brand logo, colors and graphics.

You will also be required to update the url for api server in order to connect the apps with your own api backend installation.

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

Step 3 : Read the getting started guide for Admin

After doing all the technical setup you need to read the Getting Started guide which will tell you how to proceed and start as a administrator. This guide is available in this section..

Optional Tasks

Step 1 : 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 API Server URL on the client side every time there is a change in the server IP. If you dont set a domain name you will have to update the API Server URL every time there is a change in server IP. And this can get really messy and can give you a huge headache and some grey hair ... just joking !

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

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

Step 2 : 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.

Facing difficulty in understanding ? ... let us know ! If you have any questions and queries feel free to get in touch with us on our forum