Migrating an Existing Parse App
The Parse hosted service will be retired on January 28, 2017. If you are planning to migrate an app, you need to begin work as soon as possible.
For most apps, the migration process is non-trivial, and will require dedicated development time. We recommend the following schedule:
- April 28, 2016: Data migrated to a self-hosted MongoDB (Step 1)
- July 28, 2016: Finish setting up your self-hosted Parse Server and release a new app pointing to it (Steps 2-12)
Following this schedule will give you time to develop your own Parse Server, as well as train your development team to maintain and scale the service. It will also give your users enough time to update to the new version of your app.
If you haven't migrated your database by April 28, we will assume your app is low priority, and we will de-prioritize its traffic to focus on production apps.
This migration guide assumes the use of Heroku and either mLab or ObjectRocket. These three services are easy to use, especially if you are new to deploying and managing your own backend stack. But, you can elect to use any infrastructure provider that supports Node.js environments.
After completion, you will have the following:
- Parse Server running on your computer, allowing you to develop locally.
- Parse Server running on Heroku.
- Your app’s data stored in MongoDB hosted on mLab or ObjectRocket.
- Your app’s client-side code updated to point to the Parse Server instance on Heroku, ready to be released.
- No dependency on api.parse.com for the new app client.
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 where Parse Server does not provide compatibility with the Parse hosted backend. Carefully read through the list of compatibility issues with hosted Parse before proceeding.
Here is a visual overview of the migration steps. Follow the detailed instructions after the diagram to migrate your app.
The first step is to migrate the data from your Parse hosted app to a self-hosted MongoDB. Set up a MongoDB instance that conforms to our database specifications. Due to data being compressed in the hosted Parse database, make sure to size your Mongo at least 10X the current amount of data storage you are using (you can find this information in your app's Analytics overview page).
Latency between the Parse hosted database and your self-hosted MongoDB should not exceed 20 ms. We recommend choosing either mLab or ObjectRocket for your hosted MongoDB as they both have datacenters in the US East geographic region. If you plan on hosting your production database in a different geographic region, you can do so after first migrating your data out of Parse and into the self-hosted MongoDB in US East.
Once you have Mongo setup, take note of the Mongo connection URL. Use the database migration tool to transfer your data (found in the new dashboard under App Settings → General → Migrate to external database). Ensure that the user in the connection string has admin privileges, as the migration tool will set some parameters automatically during the process.
The tool first takes a snapshot of your existing data and transfers it to MongoDB. Next, it will pause to allow manual verification, while continuing to keep things in sync with writes that are coming in from your live app. While you are in this state, your app continues to read and write from your Parse hosted database.
Connect to your Mongo instance 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.
Once you're satisfied, you can finalize the transfer in the migration UI and your app will be using the new MongoDB instance. At this point, your app is still hitting api.parse.com, but is using your MongoDB instance. You will need to administrate your database instance yourself, including maintaining indexes and scaling up.
Note that you can elect to skip migrating your data and test the functionality of your Parse Server hosted app with a blank database. You can always migrate your data later.
Follow the instructions in the Parse Server Sample App and use the Mongo connection string from Step 1.
Go to the Security & Keys section of App Settings in your Parse Dashboard and take note of the File Key, Master Key, Client Key, JavaScript Key, and dotNETKey values. Pass that into the ParseServer constructor in index.js.
Make sure saving an object and retrieving it via a query works:
curl -X POST \
-H "X-Parse-Application-Id: YOUR_APP_ID" \
-H "Content-Type: application/json" \
-d '{"score":1337,"playerName":"Sean Plott","cheatMode":false}' \
http://localhost:1337/parse/classes/GameScore
curl -X GET \
-H "X-Parse-Application-Id: YOUR_APP_ID" \
-H "X-Parse-Master-Key: YOUR_APP_MASTER_KEY" \
http://localhost:1337/parse/classes/GameScoreYou now have a Parse Server running locally that is connected to the data in MongoDB from step 1.
We will now migrate your existing Cloud Code to run in Parse Server. Copy your app’s Cloud Code to the parse-server/cloud directory, replacing the example main.js. You will need to replace any relative paths like ‘cloud/…’ to ‘./cloud’.
Native Cloud Code modules are not available in Parse Server, so you will need to use a replacement:
There is no direct replacement , but it is relatively easy to generate these tags yourself.
This is included natively with Node. Remove any require('buffer') calls.
Use the official npm module: https://www.npmjs.com/package/mailgun-js
Use the official npm module: https://www.npmjs.com/package/mandrill-api
Use the official npm module: https://www.npmjs.com/package/moment
We recommend using another image manipulation library, like the imagemagick wrapper module. Alternatively, consider using a cloud-based image manipulation and management platform, such as Cloudinary.
Use the official npm module: https://www.npmjs.com/package/sendgrid
Use the official npm module: https://www.npmjs.com/package/stripe
Use the official npm module: https://www.npmjs.com/package/twilio
Use the official npm module: https://www.npmjs.com/package/underscore
Run Parse Server and make some calls to it to verify that your Cloud Code is running correctly. If you had tests setup for the Cloud Code in your Parse hosted backend, point them to your local Parse Server and run the test suite.
Because the Parse hosted Cloud Code isn’t running a full node environment, there may be subtle differences in how your Cloud Code runs in Parse Server. We recommend exercising all your critical code paths to ensure full functionality.
If you are using Parse Hosting, you can migrate all these web endpoints to the same Express app that is serving Parse Server. For example, you could mount Parse Server under /parse and your website at the root, like so:
var api = new ParseServer({ ... });
app.use('/parse', api);
// Web endpoints
app.get('/', homeController.index);
app.get('/about', aboutController.index);
// ...When using Parse Server, any new file you create will be saved on the data store you select through the files adapter (MongoDB, S3, ...). However, when you migrate your application to your own MongoDB instance, your existing files are still in Parse's hosted service. As long as you specify the correct fileKey, Parse Server knows exactly how to access them, so they will keep working just fine.
Parse's S3 bucket will be turned down on January 28th, 2017, which means those files will need to be migrated before that date. We have a plan and we're currently working on a set of tooling to help you migrate all the existing files referenced by your application to your own backing store. Stay tuned!
Go through your app settings panel and make sure to understand how these settings will be impacted by moving to Parse Server.
- Require revocable sessions - This is required by Parse Server.
- Expire inactive sessions - This is not yet available in Parse Server.
- Revoke session on password change - This is not yet available in Parse Server.
- Enable new methods by default - This is hardcoded as true in Parse Server.
- Allow username and password-based authentication - This is currently not optional in Parse Server, username and password based accounts are always enabled.
- Allow anonymous users - This is currently not optional in Parse Server, anonymous users are always enabled.
- Allow FB auth - This is available in Parse Server if a Facebook App ID is configured.
- Add a Facebook app (list of apps) - The ability to restrict to one Facebook App is not available in Parse Server.
Update your app with the latest version of the Parse SDK (at least version 1.12 for iOS, 1.13.0 for Android, 1.6.14 for JS, 1.7.0 for .NET), which [have the ability to change the server URL]](https://github.com/ParsePlatform/parse-server/wiki/Parse-Server-Guide#using-parse-sdks-with-parse-server).
Now, test your app locally. We recommend running a staging database using a snapshot of your production database, as there may be legacy data in your database that exercises code paths that wouldn't otherwise be exercised. Be very careful if your Parse Server is pointing to the same Mongo instance as your live app, as you could be mutating production data.
At this point, your app may be totally functional. Objects, queries, and users will work right out of the box.
Follow the instructions for deploying the server to Heroku.
Now, update your client to point to the location of the API that you deployed on Heroku.
Test your app now that it uses the Heroku backend.
You can now publish the new app, which will utilize your new backend. You should encourage users to update to the new version of your app. On January 28, 2017, any calls to the hosted Parse backend service (api.parse.com) will cease to function.