Install Nearby Shops on Digital Ocean - Ubuntu Droplet
In this article we will learn how to install Nearby Shops backend on Digital Ocean
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
Nearby Shops single-market mode and multi-market mode !
1. Login as admin and Update app Service Configuration
2. Setup Multi-Market Mode
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
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.
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
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.
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 ]
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.
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
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 !
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
Your submission will be reviewed and approved after few hours.
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
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.
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.
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 !
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