This is a guide for migrating your existing Parse.com app to Parse on Buddy, our hosted version of the open-source Parse Server.
The deadline to migrate your app off Parse is coming up on January 30, 2017. Time is running out and we want to make this an easy transition for you.
We highly recommend that you first run through this guide with a development or test version of your app before working with a production app.
There are a few areas, mostly concerning cloud code, that the open source Parse server used by Buddy does not provide compatibility with the current Parse service. Carefully read through the list of compatibility issues with hosted Parse before proceeding.
Migrating to Parse on Buddy consists of three steps:
- Create an account at the Parse on Buddy Dashboard, and create an app.
- Initiate database migration, and test.
- Finalize database migration, and ship your app.
Your existing set up
You have an app, which points to https://api.parse.com/1, and uses the current Parse service. You want to migrate your app to Parse on Buddy, and point your client to the Parse on Buddy API at https://api.parse.buddy.com/parse/.
Create your Parse on Buddy Dashboard account and create your app
Go to https://parse.buddy.com and create your account. You will receive an account verification email; please follow the instructions to verify your account.
Next, log in, and create an app. You can name it the same as your current Parse app, or name it something different.
Initiate database migration and test
The next step is to migrate your data from your app’s Parse-hosted database to the Parse on Buddy database.
Go to your app in the Parse on Buddy Dashboard, select App Settings, then Security & Keys. There you will see the Mongo DB URL. Copy the entire URL:
Go to your old Parse app at the old Parse Dashboard. Click on your app, and then click on App Settings. On the right under the App Management heading, you will see a red Migrate button:
Click this, and paste the Mongo DB URL. Then click on Begin the migration:
A migration progress dialog will appear:
The migration will run through the following steps:
1. Copy Snapshot: The database migration tool first takes a snapshot of your existing data and transfers it to Buddy. Depending on the amount of data in your app, this can take from under a minute to hours.
2. Sync: Next, it will pause to allow manual verification, while continuing to keep data in sync with reads and writes that are coming in from your live app and dashboard, and your test app and dashboard.
3. Verify the Parse on Buddy Dashboard: Go to the Parse on Buddy Dashboard, navigate to your app, and browse through the collections in the newly created database. Check the collection counts and do a few spot checks to ensure that your data was migrated successfully. Although you have 24 hours to complete this, to mitigate possible hiccups in internet connectivity, we recommend testing in the few hours after you initiate migration.
Known old Parse dashboard migration issues
- The estimated time to complete (ETA) display is sometimes inaccurate. Generally this will correct itself as migration continues.
- On occasion migration will look to be done, but the ‘Verify’ step & ‘Finalize’ button will remain disabled. If this continues up to and past the 24 hour migration period, create a new Parse on Buddy app and retry.
Possible Error Messages
Typically there will be no error messages. Here is a list of ones you may encounter:
- The destination database was not empty – You will receive this error if you attempt to migrate into a Parse on Buddy app that was already a target of an interrupted migration. In that case, create a fresh Parse on Buddy app to migrate into.
- The destination database was too small – If you receive this error, please contact us at email@example.com.
- This migration was cancelled – You can try again from the app settings page. You will need to create a new Parse on Buddy app to migrate into.
- This migration was not finalized in time – There is a 24-hour limit in which to complete the migration synchronization and testing. You will need to create a new Parse on Buddy app to migrate into.
4. Migrate cloud code/web hosting and miscellaneous configuration:
- Cloud code and web hosting needs to be migrated manually using our command-line tool. For more details see our cloud code/web hosting tool documentation here.
- For push notifications, you need to upload your APNS (for iOS) and/or FCM (for Android) credentials. For information on how to acquire APNS credentials see here. For FCM credentials see steps in our FAQ, see here. Keep in mind that although FCM credentials are needed, GCM is still being used to send pushes. Client code changes are needed as well, see here.
- When testing APNS, your app’s ‘In production?’ mode needs to match both the sandbox or production push certificate, and the development or production (i.e. ad hoc or App Store) type of provisioning profile you use to build your iOS app. To change your ‘In production?’ mode, click on App Settings, then General. Set the ‘In production?’ switch appropriately.
- To continue to access files, you need to add your old dashboard.parse.com file key to the new Parse on Buddy dashboard. Click on App Settings, and then Security & Keys, in both dashboards. Copy your file key into the File Key edit box.
5. Verify your live and test apps: You need to update your client apps to the latest Parse Client SDK, and configure them with the Parse on Buddy API URL.
- The Parse on Buddy API URL is: https://api.parse.buddy.com/parse/. The trailing slash is necessary. For details on how to set this in the client SDK configuration, see here.
- You also need to supply your Parse on Buddy app ID. In your Parse on Buddy Dashboard, navigate to your app, click on App Settings, and then Security & Keys. You will see your app’s Application ID:
- All keys, including the client key. are now optional for the open source Parse Server, so they should be removed from your SDK configuration. We continue to support the master key, for scenarios where you’d like to override all permissions, for instance if you are running your Parse client on a server.
Build a debug version of your app using the updated SDK and new URL and app ID, and test. Also, verify current in-the-field installations of your app. A spot-check of functionality is all that’s necessary. If you encounter any problems, please let us know at firstname.lastname@example.org.
Finalize database migration and ship your app
Once your current app, new app, and dashboard testing is completed to your satisfaction, click the Finalize button in the migration progress dialog. You should then see a Congratulations! dialog:
At this point, your production app is still hitting api.parse.com, but is using Buddy’s database instance. Your test app is hitting api.parse.buddy.com, using the same database.
Now you can release the versions of your apps to all the platforms you support.
Congratulations, you have successfully migrated your Parse app to Parse on Buddy!
We are aiming for feature parity with the current Parse service. There a number of features that are missing from the open-source Parse Server. We are adding some, like PPNS. For the remainder, we are prioritizing based on customer interest, and will be publishing a roadmap soon. If there’s something that’s missing that you need, please contact us at email@example.com.