Install Nearby Shops on Ubuntu
In this article we will learn how to install Nearby Shops API on ubuntu 16.04
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
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
1. Setup and Customize android apps
2. Add swap space to the server
Caution for Developers
Currently the API Authenticates using Basic Auth and Lacks TLS / SSL Security.
Its not safe to run a production version of the app without the TLS encryption.
When planning to run a production version please ensure you have TLS encryption before you start.
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
sudo apt-get udpate
sudo apt-get install openjdk-8-jdk
in order to verify jdk has been installed use the following commands
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)
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
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.
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
In case the files are in zip format
Step 5 : Update API Configuration file
Use the following commands to edit the configuration file.
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
If your host is localhost, port is 5432 and database name is nearbyshopsdb then your jdbc url would be
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 !
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
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
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
which will tell you how you can setup the auto restart mechanism for Java process using SystemD init system.
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
Step 3 : Read the getting started guide for Admin
After doing all the technical setup you need to read the
guide which will tell you how to proceed and start as a administrator.
This guide is available in this section..
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.
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