Install Nearby Shops on Digital Ocean - Ubuntu Droplet

In this article we will learn how to install Nearby Shops backend on Digital Ocean

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. Request Snapshot Transfer
2. Create a Droplet from Snapshot
3. Setup third party Integrations
4. Create Domain name for the api

Concepts

Nearby Shops single-market mode and multi-market mode !

Remaining Tasks

1. Login as admin and Update app Service Configuration
2. Setup Multi-Market Mode

Optional Tasks

1. Setup Single-Market Mode : Customize android apps
2. Add swap space to the server
3. Update API Configuration
4. Submit your app to Other Market Aggregator's

Installation on Digital Ocean is our recommended way of Installing Nearby Shops backend. Its easy, simple and saves your time ! Installation takes very little time and everything just works out of the box ! If you dont have an account on Digital Ocean just go ahead and create an account and then come back here to follow the remaining steps !

An easy way to Install Nearby Shops backend on digital ocean is by creating a droplet from Nearby Shops starter snapshot image. On Digital Ocean you can get your app up and running in just 5 $ per month hosting fee.

Step 1 : Request Snapshot Transfer

Currently we dont have one-click image for Digital Ocean. So you have to request a droplet snapshot Image. There is nothing complicated about a droplet snapshot ... its just a copy of working installation of Nearby Shops backend. You can create a working installation out of snapshot. And its ready to use with just a little configuration update.

To request a droplet snapshot transfer you need to have an account on Digital Ocean. If or when you have that ... go to nearby shops forum at this link https://forum.nearbyshops.org/t/snapshot-transfer-requests/16 Here you can make a request for snapshot and we will send you the snapshot image !

Step 2 : Create a Droplet from Snapshot

After you've acquired the snapshot image. You can create a droplet from that snapshot. So just go ahead and create a droplet ... then login to the droplet using SSH and follow the remaining steps.

                     Code
                  
    ssh root@[ip_of_your_new_droplet]
                  
                

You will be asked to provide your password. You will receive the password on your e-mail that you provided for your DO account.

Step 3 : Setup Third Party Integrations

E-mail and SMS integration is one of the basic requirement to run nearby shops. E-mail and SMS is used to send order status updates to the user. For example : when the order is packed and ready for delivery. The user will get a SMS message or e-mail that his order is packed and ready for delivery.

Moreover ... E-mail and SMS is also required for user registration. To enable SMS-OTP, Email 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.

Step 4 : 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 dont set a domain name you will have to update the API Server URL on client side 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 ]

Concepts

Nearby Shops Multi-Market mode and Single-Market Mode

Nearby Shops mobile app can be setup in compile time to work in one of the two different modes. One is single-market mode and another is multi-market mode. In the Single market mode the app is configured to access only a single market. But in multi-market mode the app is configured to access more than one local market each self-hosted by a different service provider.

In multi-market mode the user can see the list of multiple local markets available at his location and he can select and shop using any local market out the many available markets.

Both multi-market mode and single market mode has their own pros and cons. While single market mode can give you more independence and autonomy but will require a higher marketing budget. While in multi-market mode your market will benefit from the popularity of the platform and will get free of cost marketing and audience for your app.

Moreover in multi-market mode it is easier to setup, maintain and update the app. While in single -market mode it gets a little more complicated to keep your code in sync with the original codebase and update your app.

To get a better understanding let us see another example. A single-market mode is like a wordpress website designed for single publication. While multi-market mode is like medium.com website. Medium.com is a single platform that contains many different publications.

Wordpress Website = Single Publication = (similar to) Single-Market Mode

Medium Platform = Multiple Publications = (similar to) Multi-Market Mode



You can setup your instance in 3 different ways.

1. Single-market Mode : Your instance is configured to work Only in Single-Market mode

2. Multi-Market Mode : Your instance is configured to work Only in Multi-market Mode

3. Dual Mode : Your instance is configured to work in both single-market mode and multi-market mode simultaneously

In the following part of his tutorial we will see how we can setup your instance to work in all the above mentioned modes.

Remaining Tasks

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

Step 2 : Setup your instance to work in Multi-Market Mode

When you setup your instance to work in multi-market mode your local market becomes visible and accessible to the users of Nearby Shops mobile app platform.

In this way your market can benefit from the popularity and visibility of the Nearby Shops platform. And this can reduce your marketing budget and help you gain more audience for your local market free of cost.

Nearby Shops is a Nonprofit Open-Source Platform and we do not charge any fee to the service providers to get their market listed on our platform. Nearby Shops is free of cost for Service Providers.

Let us discuss how you can get your local market listed on Nearby Shops Platform. To get your Instance (Local Market) Listed on Nearby Shops platform. Please follow the instructions given below !

Step 1 : Go the the api_config.properties file

                     Code
                  
    cd ~/nearbyshops
    sudo nano api_config.properties
                  
                    

Step 2 : Add "http://sds.nearbyshops.org" to the trusted market aggregators
So after adding that to your api config file your api_config.properties file would look like !


                     Code 
                  
                      trusted_market_aggregators = http://sds.nearbyshops.org
                  
                  



Step 3 : Submit your Local Market !

Download the Nearby Shops end-user app from the homepage of nearbyshops.org
In this app go to the markets screen.

You will see the + button in the markets screen. When you press this button you will be asked to provide your market url and make a submission.

Your submission will be reviewed and approved after few hours.

Optional Tasks

Step 1 : Setup Single-Market Mode : Customize the android apps

For technical reasons we recommend multi-market mode over single-market mode to keep the maintenance of the app simple and easy.

But still if you want to configure single market mode you have that option also. For single market mode you need to customize the Nearby Shops android app and connect it with your local market Instance ...

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

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.

Step 3 : Update API Configuration (Optional)

You have logged in to your droplet using SSH ... now you can update the API configuration to personalize the installation.

                     Code
                  
    cd ~/nearbyshops
    sudo nano api_config.properties
                  
                

The instructions to update the API configuration file is provided in the configuration file. You can follow these instructions to update the configuration file. To secure your database you can change username and password of the database. You should change username and password for your PostgreSQL database first and then update the new username and password in the configuration file.

After you finish updating the api configuration please restart the process to reflect the changes ! Then check if it has restarted successfully !

                     Code
                  
    sudo systemctl restart nearbyshopsapi
    systemctl status nearbyshopsapi
                  
                

Step 4 : Submit your app to other market aggregators

Theoretically there could be many market aggregators. And technically it is possible for a service provider to submit their Instance to multiple market aggregators. Nearby Shops is just one of the many market aggregators.

you simply have to repeat the above procedure for different market aggregators.

Right now there isnt any other market aggregator but in future we may have ... or if you want to build one you can ... The tutorial for how to build a market aggregator will be provided !

We want to ensure that their is a level playing field and no vendor lock-in for service providers ... therefore all the technology will be made open-source.

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