Surviving the Parse Apocalypse [tutorial]

Part 1/2 How to migrate your Parse apps to the open-source Parse server.

In this blog post, I will walk you through the process of migrating a Parse app to the open-source Parse server.

Parse is a BaaS (Back-end as a Service) tool that has proved to be very useful for app developers. Founded in 2011, it came under the Facebook umbrella in 2013. Parse was created to make it easy for app developers to create a back-end (API, data store, etc.) for their mobile and web apps. Parse has its limitations, and there are many situations where your best option is to build a custom back-end from scratch. Nevertheless, it is a powerful tool for those who want to get up and running quickly on a tight budget.

Here at CauseLabs, we have used Parse for a number of projects. Unfortunately for us, and the tens of thousands of other developers who use it, Facebook announced early this year that they are shutting down Parse by January of 2017. This presents a serious problem for those of us who have come to rely on it. For some of our projects, like Moneythink, the solution has been to develop a new, custom API and migrate the data and the mobile apps over to it. This is no small challenge, but it can be done.

Fortunately, it’s not the only option. Shortly after announcing the impending shut-down, Facebook opened up the source code for the Parse server and dashboard. This makes it possible for developers to set up their own Parse instance and migrate their services to it. It also drastically reduces the amount of time needed to move your code and data.

This is the choice we made for MobileMi$$ion, an app we developed for the Council of Better Business Bureaus. It was a natural fit: we needed to transition away from Parse quickly, and keep to the budget. The structure of MobileMi$$ion has worked well within the framework of Parse, so there was no technical need to move to a more complex, custom-built back-end.

The Basics

There are a number of options available for how to get started. Which path you choose will depend on your server setup. If you are moving to an established infrastructure provider like AWS or Heroku, you will find helpful guides on the Parse Server Wiki. The Parse Server Github page is also a useful resource.

Our client wanted to manage the infrastructure themselves, so they set up a new Ubuntu 14.04 server for us to work on. The Parse server itself is largely self-contained, so there wasn’t a lot to install. Because Parse is based on node.js, I first needed Node and its Package Manager:

$ sudo apt-get update

$ sudo apt-get install nodejs

$ sudo apt-get install npm

Once this was done, we could use npm to install the Parse server:

$ sudo npm install -g parse-server

Because Parse uses the MongoDB database, we also needed to install that:

$ sudo apt-get install mongodb

This takes care of the basic requirements.

Starting it Up

The simplest way to start the Parse Server is outlined in the Github docs:

$ parse-server — appId APPLICATION_ID — masterKey MASTER_KEY — databaseURI mongodb://localhost/test

Where APPLICATION_ID and MASTER_KEY can be whatever you want. This is fine for creating a simple test app, but that’s not what we want to do. We want to migrate our existing app from Parse’s servers. This requires us to do some prep work, starting with the MongoDB database.

Preparing the Database

We are by no means experts on MongoDB; in fact, we had never touched it before this. So we strongly recommend you check out some other resources on the subject, starting with the Official MongoDB Site. However, we were able to learn enough to get the job done, so that’s what we’ll cover here.

There are two things you’ll need to set up in MongoDB: a database to store your data, and a user that has permissions to read from and write to that database. The first thing we want to do is set the mongod server to noauth mode, so we can easily log in with full access. To do that, edit the mongod config file:

$ sudo vi /etc/mongod.conf

(NOTE: This is the standard location for the mongod.conf file. If it’s not there, you may need to do some research on your particular OS and configuration to find it.)

In the configuration file, find the following line:

auth true

And comment it out. Save the file, and restart the mongod service. If you’re on Ubuntu, this will restart it:

$ sudo service mongod restart

Now type:

$ mongo

And you will have a mongo command line with full access. To create the database (which for our purposes will be called mydb), type:

> use mydb

To create an admin user, you need to first switch to the admin database, which holds all of the user information:

> use admin

Then call the createUser() function to create a user with full administration permissions:

> db.createUser( {user: “admin”, pwd: “password”, roles: [ { role: “userAdminAnyDatabase”, db: “admin” } ] } )

The user we just created here has username admin and its password is simply password. You’ll obviously want to use something more secure.

Now exit the mongo command line:

> exit

And edit your mongod.conf file again. Uncomment auth true and restart the mongod service. You can now test your login:

$ mongo -uadmin -ppassword admin

If you get the > prompt with no errors, then you have successfully connected to the mongo service as admin.

Congratulations! Your MongoDB database is now set up and ready to receive data from Parse. Now it’s time for the migration.

Migrating your data

(NOTE: We once again strongly encourage you to go to the source and read Parse’s Official Migration Guide for more detailed information.)

This is one area where staying with Parse’s software gives you a HUGE advantage. If you’re migrating to a new custom API, you have to juggle a lot of balls to make sure things go smoothly:

• You have to write scripts to pull your existing data from Parse, convert it to the correct format, and write it to your new database.
• You have to release your new mobile app(s) that point to the new API. As soon as this is done, you have to find a way to shut off access to the old Parse API so you don’t have users writing new data to the old database after you’ve already migrated it.
• And finally, you need to encourage users to update their mobile apps as soon as possible.

No matter how careful you are, something will go wrong. It’s not easy; trust us, we had to do it.

Parse’s migration process eliminates all of these worries for you. There are only a few steps:

1. Take the information from the previous step and build a mongodb connection URI, like this:

mongodb://admin:password@api.new.com:27017/mydb

As you can see, it contains the username and password for the mongo user we created in the previous step, the host name and port number of the server containing your new database, and the name of the database. Note that the port is optional; if you leave it out, it will default to the standard MongoDB port of 27017.

2. Next you want to log in to your Parse account at https://dashboard.parse.com/apps, and go to your app’s settings. Scroll down to “App Management”, and click the “Migrate” button. This will open a dialog prompting you to enter a database connection string. This is where you put in the connect URI.

3. Click “Begin the Migration”, and if everything is set-up properly, Parse will begin migrating your data from their database to yours. This could take a while, depending on how much data you have.

4. Once it’s done, if there are no errors, you will be asked to “Finalize” the migration. As the name suggests, this step is final; there’s no going back. But once it is done, the app hosted on Parse’s servers (and the Dashboard) will point to your custom database. From the users’ perspective, nothing has changed at all, but you’ve already completed a big chunk of the migration process.

That’s all for now, but join us next time for Part 2. We’ll cover the process of spinning up your own instance of Parse Server and getting it to connect to your new database. Also be sure to follow us on Twitter @CauseLabs for more Tutorials and notes from our tech lab.