Installation / Installation Guide

Do you need Technical Assistance ?

If you come from a non-tech background and need help. Feel free to ask for help on our forum or call us at +91-8688667928 for Paid Support Options

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
9. Setup third party Integrations
8. Create Domain name for the api
10. Customize the android apps
11. Login as admin and Configure Settings

Optional Tasks

1. Add swap space to the server
2. Submit to Market aggregators

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 : Connect with Postgres Database

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.

Step 8 : 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 9 : 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 10 : Build and Customize the android app

To use the app for production use. You will need to customize the android app 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 app with your own api backend installation.

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

Step 11 : Login as Admin and Update app Service Configuration

After doing all the technical setup you need to setup some basic configuration for the app. Like setting up the country and service name. Setting up the country sets the currency accordingly. So it is very essential that you complete this configuration.

For setting up the app configuration you will be required to login as admin to the admin app.

You can download the admin app from the downloads page of this section.

The credentials for the admin are provided in the api_config.properties available at your api server.

After you login as admin you need to open service configuration screen in the admin app and update the country and other settings accordingly.

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 : Submit your app to market aggregators

As the name suggests market aggregator are apps from which people can access multiple markets. By submitting your instance to market aggregators. You can gain free access to existing audience of market aggregators. Thereby reducing your marketing costs. To submit your instance to market aggregators please read this page.

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