Migrating Applications from Parse to IBM Bluemix

This week Parse.com, Facebook’s Mobile Backend as a Service offering, shocked both their customers and the development community by announcing that they are sunsetting the service to “focus resources elsewhere.” Luckily, they’re not leaving current customers high and dry – they are giving developers a year’s notice before the service is shut down, providing data migration tools to MongoDB, and open-sourcing parse-server, a Parse.com API-compatible router package for Express.js on top of Node.js.
If you’re a Parse customer looking to move your app infrastructure to someplace secure, then you’re in luck. Bluemix is the place for you. In this post, I spell out the process of migrating an application from Parse.com to Bluemix. Let’s get started!

Create your Parse-on-Bluemix application

The first thing you need to do is create an app on Bluemix. If you don’t already have a Bluemix account, you can sign up here (it’s free to try!). Once you’re logged in, it’s time to create a new Node.js app on Bluemix to host the Parse server. Click the CREATE APP button on your dashboard.

Then, when prompted, select the WEB application option. This doesn’t mean that you can’t connect a mobile app to it; this option just sets up the backend application server, without provisioning any Bluemix mobile services like Mobile Client Access. The web option is used to deliver REST API calls, but does not support any enhanced mobile security or analytics features.

Next you need to specify the type of application you want to create.
Bluemix supports a variety of server-side processing options; in this case you want to select “SDK for Node.js” and then CONTINUE.

Next you are prompted to enter an application name. Go ahead and enter one. (Application names must be unique across Bluemix.)

When you click FINISH, the app is staged, and you are presented with instructions and next steps. At this point, click “Overview” to go back to the app’s dashboard.

Add the MongoDB service to your Bluemix application

The next step is to create a MongoDB instance to migrate the data from Parse.com. From the app’s dashboard select ADD A SERVICE OR API.

Scroll down to the “Data and Analytics” section and select “MongoDB by Compose” to add a MongoDB instance to your application.

You are then presented with details for configuring a MongoDB instance.

Open up a new browser window for the next step – leave Bluemix open, because you’re going to need to come back here to finalize the MongoDB configuration.

Create and configure the MongoDB instance on Compose.io

The MongoDB instance on Bluemix is available through Compose.io, a recent IBM acquisition.

To create and configure the MongoDB instance, click on this Compose link and navigate to compose.io.
If you don’t already have a Compose account, you need to create one (they’re free for 30 days!).

Once you’re logged in, click on the deployments icon (top icon on the left side) and select the MongoDB option to create a new MongoDB deployment.

You need to specify a deployment name and region, then click “Add deployment” to create the MongoDB instance.
For this example I created a deployment called “parse-migration”.

Next you need to create a database instance. Once the deployment is created, click on “Add Database” and create a new database.
In this sample I created a database called “myDatabase”.

Once the database is created, you need to add a user account to access the database. On the database screen, select the “Users” menu option on the left side, and then click “Add User” to create a new user.

Next click on the “Admin” (gear) link on the left side to view the connection info for your database instance – you’re going to need this in the next step.

Go back to the Bluemix MongoDB screen and specify the MongoDB host string, port, and login credentials, then click CREATE to finalize the MongoDB configuration within your Bluemix app.

The host string is in this format: server.domain:port/databaseName
For this sample app, it is: candidate.63.mongolayer.com:10373/myDatabase

The port is 10373, and the username and password are the ones for the account that was just created.

Migrating data from Parse.com to your MongoDB instance

At this point you’re ready to migrate data out of Parse.com, and into the MongoDB instance you just created. Detailed instructions are available in the Parse.com migration guide.

Log into Parse.com and select the app that you want to migrate. Go into “App Settings”, then select “General”, and click the “Migrate” button to begin the process.

Note: You must be in the new/beta view to see this option.

To begin the migration process, a modal dialog asks you to specify your database connection string. The connection string is in the format: mongodb://:@server.domain:port/databaseName

So, in the example app, it is: mongodb://user1:password1@candidate.63.mongolayer.com:10373/myDatabase

Click “Begin the migration”. In a few minutes the migration will complete, and you can return to your MongoDB database on Compose.io to see the migrated data.

Note: Migration times vary depending upon the amount of data you need to migrate.

Configuring your Bluemix application

Next, let’s configure some environment variables to use in the Node.js application.
On the Bluemix app’s dashboard select the “Environment Variables” option on the left menu, then select USER-DEFINED.

Add environment variables for APP_ID, MASTER_KEY, and REST_KEY that correspond with the App Keys from Parse.com. Also add a PARSE_MOUNT key that contains the path where the services will be exposed on Node.js. For this last one, just use the value /parse.

On Parse.com, you can access the ID and Key values by going to the app, selecting “App Settings”, and then selecting “Security & Keys”.

Save these environment variables. Now we’re ready to deploy the Node.js application.

Deploy your Bluemix application

The parse-server API is a router for Express.js (an application framework for Node.js). It can be easily leveraged in a new Node.js/Express.js app, or dropped into an existing Express.js app to expose the Parse.com API. There is a sample application in the parse-server repository that you can copy to get started. Or, you can take the easy route. IBM Cloud Data Services Developer Advocate Mike Elsmore has put together a base Node.js application that can be quickly deployed that already supports the Bluemix environment configuration.

You can click the “Deploy to Bluemix” button below to deploy this project directly to Bluemix in a single click, or head over to github.com/ibm-cds-labs/parse-on-bluemix to view the source code.

If you want to deploy the application manually, then clone it to your local machine and use the Cloud Foundry API cf push command to push it to Bluemix.

git clone https://github.com/ibm-cds-labs/parse-on-bluemix.git
cf push Your-App-Name-On-Bluemix

You application will be deployed and staged, and it’s now ready for consumption.

Testing the deployment

You should now test the deployment using curl commands from the command line to verify that the migration and deployment were successful.

curl -X GET \
  -H "X-Parse-Application-Id: PARSE_API_KEY_GOES_HERE" \
  -H "X-Parse-Master-Key: PARSE_MASTER_KEY_GOES_HERE" \
  http://parse-on-bluemix.mybluemix.net/parse/classes/GameScore

Note: the actual URL depends on your data model.

If things were successful, you should see data returned from your parse server instance:

{"results":[{"objectId":"jCtOiC18nc","createdAt":"2016-01-29T21:27:21.567Z","updatedAt":"2016-01-29T21:27:31.139Z","playerName":"Andy","score":0,"cheatMode":true}]}

Or you can post data to the server to test write ability:

curl -X POST \
  -H "X-Parse-Application-Id: PARSE_API_KEY_GOES_HERE" \
  -H "Content-Type: application/json" \
  -d '{"score":1337,"playerName":"Andy Trice","cheatMode":false}' \
  http://localhost:1337/parse/classes/GameScore

What Next?

If you are using Parse Cloud Code, then you can copy your Cloud Code files into the Node.js project. (See the “cloud” directory in the git project.)

For additional details, be sure to check Parse.com’s migration guide.

Configure the client apps

Once you’ve stood up the new back-end system for your app(s), you’re ready to point the mobile client applications to the new back-end infrastructure. The most recent version of the Parse.com SDK introduced the ability to change the server URL (at least version 1.12 for iOS, 1.13.0 for Android, 1.6.14 for JS, 1.7.0 for .NET).

Limitations and warnings

Parse.com has done a great job providing you with tools to migrate your apps off their platform, but be warned – not all features of the Parse.com platform are available in the open-source parse-server.

Push notifications are not implemented. Luckily, the push notification implementation can be modified to support IBM Bluemix’s Push notification service, so your app does not have to suffer loss of functionality.

In addition, Parse.com’s App Links do not have a direct replacement in the parse-server. Many of these offerings have separate Node.js npm modules that can be leveraged, but each requires additional development effort; they are not drop-in ready.
App settings are impacted by this transition. This includes social logins, user authentication and sessions. App analytics, the client dashboard, in-app purchases, and jobs are also not supported.

Luckily, the Bluemix catalog has many of these features covered, plus a whole lot more.
If you run into any cases where the parse-server seems to just “do nothing”, meaning services don’t seem to exist or they fail silently, then double-check your PARSE_MOUNT environment variable and MongoDB connection/host string to make sure they are in the proper formats mentioned above.

For more details on transitioning away from Parse.com, be sure to read the sunset announcement, the database migration tool, and the parse-server migration guide.