In this article we will learn how we can install Nearby Shops API on ubuntu 16.04
Steps for API Installation
- Install OpenJDK 8
- Install Postgres Database Latest Version
- Create Database , add User, assign password and Grant Privileges
- Download Jar file and Configuration File
- Add / Update API Configuration |
- Test jar file by running it
- Automate API jar file Execution using SystemD
- Add Swap space to the Server
- Create Domain Name for API
- Customize Android apps : Update Service URL
- Login as Admin through the Admin app
- Enable OTP and SMS by adding MSG91 api key
- Enable Push Notifications by adding OneSignal API Key and app id
- Read Getting Started for 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”
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
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.
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 Docs 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.
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
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. Therefore we need a mechanism which automatically starts the process if it gets terminated or there is a Server Reboot / Restart.
To solve this issue we will use SystemD init system and write a small script which will tell SystemD to restart our Java process if it gets terminated unexpectedly.
Please read this article which will tell you how you can setup the auto restart mechanism for Java process using SystemD init system
Step 8 : Add Swap Space to the API Server
You can add the swap space by following the instructions in the tutorial given in above link.
Step 9 : Configure Domain Name for the API
You should assign a domain name to your API Server because when the api server is changed and its IP address changes we will not have to update the API URL at the client side. Updating the IP address for the domain will solve our problem.
Watch the following video which tells you how to configure a domain name on Digital Ocean Server.
The domain name for your rest API service is the “Service URL” of the service. Remember this URL and provide this URL whenever asked.
Step 10 : Customize the Android apps and update the Service URL to connect client apps with new self hosted nearby-shops-api
Step 11 : Log in as admin through the Service Provider App
Download the service provider android app from the downloads section of this website.
If you are downloading the service provider app from the direct download link and not from the google play store then you will need to change the security setting on your android device to enable installation from unknown sources.
After you change this setting go ahead and install the service provider app.
Now login to your app using these credentials
Username : admin
Password : password
these are auto generated by the System. And needs to be used when accessing your system for the first time.
Logging successfully to the admin app confirms that api has been running successfully.
Step 12 : add MSG91 API key to enable SMS and OTP
Go the the msg91.com and get an api key to enable otp sms service. MSG91 is a SMS / OTP provider which offers a paid service for sending OTP / SMS to the users.
After you obtain an API key update the api configuration file with the new api key. This will enable the SMS service.
Step 13 : add One SIgnal api key to enable push notifications
Nearby Shops uses One-Signal to send Push Notifications. Therefore head over to One-Signal and create a new project. Add the rest api key and app id to the configuration file and you will also need to update the android apps with the project number and the app key.
After you have updated the keys the push notification service will start.
Step 14 : Get started as an Admin of the Nearby Shops app
This article lists all the steps which you are supposed to do in order to successfully start your service as a administrator of the new app.
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 ?