In this article we will learn how we can install Nearby Shops API on ubuntu 16.04 server using Digital Ocean Cloud Hosting Service.
A word of Caution for Developers
You can use the current setup for testing and review purpose or just for playing with it or experimenting with it but before you decide to use this software in Production Environment please note that right now it lacks some of the very essential features and security. And when you use this software in Production you should understand that you bear the risks associated. because you have been warned !
The following essential features have not been implemented althought we are in the process of implementing them soon.
TLS / SSL security, e-mail integration, Google and facebook sign-in are some of the features which is currently absent but we are going to implement these features soon. Pull requests which add these features into the API are welcome.
Currently the API Authenticates using Basic Auth but i believe we will soon upgrade it and replace it with a token based authentication System.
Enough of the Introduction and Let us now begin with the step by step installation Guide for Nearby Shops API Backend
Step 1 : Create an API Jar File from the source code
We need to compile the source code and create a Jar file for the REST API. Let us see how do we do that.
Download the API source code from the github and create the Uber Jar file using maven. Maven is a popular build tool used in Java Ecosystem. If you dont have maven installed on your machine you can install it by using “sudo apt-get install maven” . Before typing the following commands on your terminal make sure you have git and maven both installed on your machine.
cd / mkdir nearbyShopsAPI cd /nearbyShopsAPI git clone https://github.com/SumeetMoray/Nearby-Shops-API.git mvn install
“mvn install” would download all the dependencies and create an Uber Jar (a jar file which contains all of its dependencies). After this command executes successfully. You will see two jar files in the target folder which lie inside the project folder. THe jar file with higher size will be the Uber Jar. Its size will be around 15 MB approx.
You will move this Uber Jar file the server using scp command.
Pro tip :
If you want to customize port and Postgres DB username and password. You can do it before you generate a Jar file by editing the “Main.java” and “JDBCContract.java” which resides inside the Source Folder.
A word of caution for using NGINX server
You might consider using the NGINX server. But this approach has some pitfalls so if you are considering using the NGINX server please understand that it has some issues. The push notifications utilizes SSE (Server Sent Events) mechanism and they stop working when we use NGINX proxy.
Therefore unless you are willing to bear the disabling of push notifications on android app. Dont consider using the NGINX server.
If you find any solution to keep the push notifications enabled while using the NGINX Server please let us know and share your solution with us.
Step 2 : Create Server or Droplet
Digital Ocean offers a intuitive and easy to understand user-interface for creating a server. Please create a server with a following configuration.
Ubuntu 16.04 with minimum 512 MB ram or above !
You can also watch the following video which contains instructions for creating and initial setup of a Server
Step 3 : Login to the server using SSH and Enable it
The tutorial for how to setup your server is given at the following links. Please go through these links and setup your server.
More instructions are given in this video
Step 4 : Install OpenJDK 8
Nearby shops is a developed using java and its a java application. So you will need to install JDK in order to run it. But our personal recommendation is to install OpenJDK 8 and prefer to use Open JDK over Oracle JDK.
On this date we are hearing lot of licensing issues and cases where oracle is charging and suing people for using Java. Therefore its always safe to use OpenJDK over Java.
You can install open-jdk 8 by using following commands.
sudo apt-get udpate sudo apt-get install openjdk-8-jdk
Step 5 : Install PostgresDB
You can install postgresDB’s latest version by typing the following commands in the terminal. For more detailed information on how to install postgresql please refer this tutorial.
sudo apt-get update sudo apt-get install postgresql postgresql-contrib
Step 6 : Add User to PostgresDB
Installing the PostgresDB is not enough to get access to the PostgresDB. We also need to create a user with username and password. In order to do that please type the following commands in your terminal.
We have to create a user with username ‘postgres’ and password ‘password’ because app uses this setting to connect with the postgresDB.
In future we are planning to have a configuration file where you can set your own username and password. But for now please use the following settings.
sudo -u postgres psql ALTER USER postgres PASSWORD 'password'; // do not forget the semicolon at the end of ALTER USER Statement press ctrl + D to come out
Step 7 : Copy NearbyShops API jar file to the Folder on the Server
Download the latest API Jar file available on the downloads page.
We now have to copy the Jar file to the server. The jar file is an uber Jar – a jar which contains all of its dependencies.
In order to copy the file first we should create a folder with name of your choice. All of our files will be copied in this folder.
mkdir /nearbyshops cd /nearbyshops scp -r /path/to/jar/filename.jar firstname.lastname@example.org:/nearbyshops Note : Please note that you need to replace 0.0.0.0 with the IP address of your own server. Reference : Use the following command to copy the files scp -r /path/to/my/files email@example.com:/path/on/remote/droplet
Consider the name of the Jar file is “nbs_api.jar” you can now run this jar file to ensure that everything is working fine.
Type “Java -jar nbs_api.jar” in the remote terminal in order to execute the jar file and get the api up and running. You would start seeing the api log. Please read this log, you should see “HTTP Server created” or something similar to that.
You can test whether your api is successfully running or not by typing
on your browser. Please replace server-ip and server-port with IP of your server and port of your server. This is a link to the default server api configuration. You should now see a JSON ouput something similar to the following. If you see this it is an indication that your API is connected to Postgres Successfully and started running.
Step 8 : 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 and it will also start the process on 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 9 : Configure Domain Name
You should assign a domain name to your API because the Server can be change and in such a situation IP of your service will change. This is not acceptable becasue client apps will not be able to find your server then.
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 give this URL whenever asked.
Step 10 : 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 unable installation from unknown sources.
After you change this setting go ahead and install the service provider app. Type the service URL for your service which you configured using the above step.
Now login to your app using these credentials
Username : username
Password : password
these are auto generated by the System. And needs to be used when accessing your system for the first time.
Step 11 : Add a service Configuration
After you have logged in as an Administrator. Go to the Service Configuration. and fill up all the details to update the service configuration. This configuration will be used by “Service Discovery Service” to access your service and define the visibility of your service by its location.
Step 12 : After you have updated the Service Configuration. Submit the Service to the Service Discovery Service
After you have updated your service Configuration. You should submit your service URL to the “Service Discovery Service”.
“Service Discovery Service” is like a location based directory of services. It shows you the services which are available in the given location.
SDS is used by End-User app and Distributor app to find and configure the service.
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 ?