Setting up your own Parse server

After Parse announced they would be shutting down their MBaaS hosting totally by the 28th January 2017, I decided (with little alternative) it was time to move the 8 apps I’ve built on the service in the past 12 months, over to my own servers.

Safe to say, Parse’s tutorial on how to set up your own “Parse Server” was a little frank, so after spending the day working out exactly the necessary steps were, I thought I would share what I had learnt with anyone else who found themselves in my position.

It was actually a lot simpler than I expected it to be … thank god.

** Anti-disclaimer — before today, I had never used github, never used heroku, never used MongoDB, and never used node.js. So don’t worry if you haven’t either.

** Pretty much everything is done through the terminal, so if you’re unfamiliar there … google is your friend

How Parse server works

You never used to need to know how your client side code interacted with your Parse database, and you still don’t need to be a server architect extraordinaire; a lot still happens behind the scenes when you use a self hosted “Parse Server”. However, now that you’re going to be managing it all yourself, it’s probably a good idea to know the basics.

It will come as a relief, when you realise that most of the technically difficult stuff Parse did, was in the client side SDK, and the handling of those HTTP requests by the server side javascript. Luckily, you still not going to have to touch any of that stuff. Basically now you just have a bit more admin to do.

There are only three main sections to think about when explaining how your server will work. You have the client code, from which you make requests to the server, a server side code that receives these requests, and a database which the server side code stores and retrieves data from, upon these requests. Whereas in the past Parse took care of each of these three sections, AND the linking between them, we now have to arrange a couple of different providers to take care of each specific section, and link them together ourselves.

The Circle of life

Client SDK >> Server Code >> Database >> Server Code >> Client SDK

The Parse client SDK combines the queries you make into the format of an HTTP request, which is sent to the node.js server code hosted on Heroku. This server code then destructs this HTTP request, and does the dirty work of trawling the MongoDB database for results that match the query. It then parses the results it finds into a nice JSON structure, which is returned to the client SDK, and destructed even further into a nice accessible array of PFObjects. So how do I link my client SDK to Heroku, and Heroku to MongoLab?

Tutorial starts here…

You will find a GitHub repository with an example parse server here. There are two sections to the tutorial Parse created, which threw me off at first. I’m going to ignore the first bit about local development, because it’s kind of pointless. It’s actually easier to set up your server on Heroku and MongoLab, and much more useful.

• Step 1 — Clone the GitHub repository

You will need to open up the terminal, paste the following line (without the dollar symbol) and press enter.

$ git clone https://github.com/ParsePlatform/parse-server-example

You have now essentially made a folder containing all the parse server code into a folder at the root of your current user directory. You can locate it in a finder window to check it’s there!

Then navigate to that directory in the terminal with

$ cd /parse-server-example

*For the rest of this tutorial make sure you stay navigated in the parse-server-example folder in the terminal.

• Step 2 — Prepare the app with Heroku

You need to create an account with Heroku, it’s free and quick. So if you haven’t already go do that! Then you need to download the latest version of the Heroku tool-belt here. Once the download has finished you will be able to use heroku commands from the command line.

Next, navigate to the parse-server-example folder in the terminal, and run

$ heroku login

Once you’ve entered your username and password you are all set up to create and deploy your server codeto be hosted on heroku! To set up the parse server as an heroku app, run-

$ heroku create

You now have an app created on Heroku which you can check exists in the dashboard.

Now to upload the code inside this app to Heroku itself, you need to first set this folder as a git repositiory by running

$ git init

and then to push the code to Heroku call

$ git push heroku master

*You run this command every time you have updated your code locally, and you need to update it on the server.

You will get a load of output in the terminal while the code is uploaded to Heroku, when it’s complete you should see

$ remote: Verifying deploy… done.

• Step 3— Add the MongoLab add on

This is an easy step, and basically sets up hosting for your Mongo database, with automatic scaling, and stuff. Run (still in the parse-server-example directory)-

$ heroku addons:create mongolab:sandbox

This adds a free “sandbox” version of MongoLab to your heroku account. Again, this will take a second or two. When it is complete, you need to “find the URI of your database”, to do this call-

$ heroku config

Within the output from the terminal you will see something that looks like this

MONGOLAB_URI: mongodb://heroku_gx0x*************1sohcjdp@ds****85.mongolab.com:55485/heroku_gx*x6f4r

Now copy and past the bit after MONGOLAB_URI: and paste it into the command line after

$ heroku config:set DATABASE_URI=

like so

$ heroku config:set DATABASE_URI=mongodb://heroku_gx0x*************1sohcjdp@ds****85.mongolab.com:55485/heroku_gx*x6f4r

• Step 4— Set appID and clientKey

You’ll be familiar with having to add a clientKey and appId into the initialisation of your client code, to allow your app to communicate with Parse. Now however, you need to set these keys both in your client code and in the server code. Get a finder window, and open up index.js in the parse-server-example. Find this section and set both the clientKey, and appId, to whatever you want

You will then need to go into the initialization block of your code, and set a matching appId.

The only new bit of code to add to the client SDK, is to specify your new server address. This is the address of your Heroku app that hosts your server side code. You can find it in the settings of your app on your Heroku Dashboard. It is just a URL of the form

https://NAME_OF_YOUR_HEROKU_APP.herokuapp.com/parse

*Don’t forget the /parse suffix, I kept forgetting this.

Your initialization block in your client code should now look something like this (this is Swift in my example)

Parse.initializeWithConfiguration(ParseClientConfiguration(block: { (configuration:ParseMutableClientConfiguration) -> Void in
     configuration.server=”https://stark-atoll-72202.herokuapp.com/parse"
     configuration.applicationId=”APP_ID”
     configuration.clientKey=”CLIENT_KEY”
}))

The final step is to update your Heroku app, since you changed the appId and added a clientKey. So run these three commands in the terminal (remember that when you change the code locally on your computer, it isn’t automatically updated on Heroku, which is why you have to update it like this)

$ git add .
$ git commit -m "My first commit"
$ git push heroku master

When that is done ….. so are you…

FINISHED

Amazingly, you can now use your client side Parse SDK just as you always did, and it somehow just kind of magically works. Now instead of connecting to a Parse run server, your client code is connecting directly to your Heroku app, which saves all your data in your MongoDB database. I found this kind of astounding. Your queries all work fine, saving of PFFiles, PFGeoPoints, it’s all perfectly still working.

But …. you might feel a bit in the dark, saving all this data and not really being able to see it or inspect it. Though you can create tables of your data in MongoLab (just follow the link there on Heroku), there’s a lot less features and freedom. For now, it seems, there still is a way

Connecting to the Parse dashboard

Parse have now made it possible for you to link your new MongoLab database, with their dashboard, so that you can still manage your database in a familiar format. They haven’t made it clear whether this will always be the case, but in the mean time it’s a good way to check you’re still doing stuff correctly. If you create a new app in the parse dashboard, you now have the option to connect to any MongoDB database.

You just need to add the URI that you found in Step 4, and that’s it. You can still view, filter, delete, and explore your data just as you would have done before. For now anyway.

What’s missing…

It is worth noting, that a lot of extra features that made Parse really useful, won’t now be built into your MongoDB server. You can no longer view analytics of your requests (though I think there are plugins you can use with Heroku), and most of your app settings are no longer configurable through the dashboard. Most importantly though, is the lack of support for Push Notifications. That’s kind of a big deal. Parse say in a rather unhelpful way “Push — We did not rebuild a new push delivery system for parse-server, but we are open to working on one together with the community.” I’m in the process of building a new push module for this purpose, myself so if you would benefit from it get in touch and I’ll happily share it with you.

EDIT — How I’m doing push

I found out about OneSignal https://onesignal.com/ shortly after writing this, and now use that for my push notifications. It’s possibly even better than parse’s own for targetting different channels. Works in a slightly different way but can get exactly the same outcome.

Extra links

https://parse.com/docs/server/guide#overview

Getting Started with Node.js on Heroku

https://www.mongolab.com/home