Migrating from Parse | mLab Documentation & Support

Overview

Parse announced on January 28th 2016 that it will be shutting down the Parse service and giving users one year to migrate their apps off of the service.

As a part of shutting down its service Parse has made it possible to deploy Parse Server, an open source version of the Parse backend, to any infrastructure that can run Node.js. Therefore, you can continue using Parse by self-hosting the Parse Server software and MongoDB, the database technology that powered the Parse service.

To help with the transition, Parse has partnered with mLab to allow existing Parse users to seamlessly migrate their database off the Parse platform. This migration guide is a detailed step-by-step tutorial that will teach you how to:

Migrate your Parse data onto an mLab-hosted MongoDB database
Create a new Parse Server
Deploy your Parse Server onto Heroku
Connect your client applications to the Parse Server

Part 1: Migrate your Parse data onto mLab

Choose your plan at mLab

Once you've created an account, you can create a new MongoDB database. Before creating the database, there are a couple things for you to consider:

Where should I host my mLab database?
Which mLab plan type should I choose?

Cloud hosting locations

We strongly recommend that you host your database in the same datacenter as your Parse Server as it will be the most secure method of deployment and will minimize latency between your application and database.

mLab supports MongoDB hosting on Amazon (AWS), Azure, and Google. For more details, see our list of supported cloud providers and datacenters. Once you've decided on a cloud provider, you'll need to choose the plan that is right for you.

The Parse service is hosted in AWS US East so if you choose to host your database with a different cloud provider or region, there will be a period of time during the migration process where your application will experience higher latency. Also, note that unless you have enabled SSL on your mLab-hosted database deployment, your data will be transmitted unencrypted over the open internet.

mLab plan types

mLab offers three types of plans: Sandbox, Shared, and Dedicated.

If you are running a non-production application with a small amount of data and modest performance requirements, our free Sandbox plan which includes up to 496 MB of storage is a good option. If you're unsure if a Sandbox plan is appropriate for your use case, you can consult our guide on running MongoDB in production.

If you are running a production application, we highly recommend using one of our for-pay plans because they include auto-failover to a redundant node in cases of component failures or maintenance.

If your dataset is larger than a few gigabytes and/or you need consistent, stable performance, we recommend one of our Dedicated Cluster plans which utilize virtual machines dedicated to only a single mLab deployment.

For more information, read our documentation on mLab's plan types.

We encourage you to email [email protected] so that we can help you pick the right plan and help monitor the migration process.

Key considerations when selecting a Dedicated plan

1. Current size of data stored at Parse

We suggest provisioning an mLab plan that has roughly 3-4 times the data size currently used by your Parse application. This allows for room to hold indexes, which are not included in the data size shown by Parse. For example, if Parse reports your app is storing 10GB of data in the "Data storage" metric we suggest a mLab plan that can accommodate 30-40GB of storage. You can always downgrade with no downtime after the migration if your deployment is over provisioned.

You can find your current data usage by looking up the Parse "Data storage" value. From the dashboard go to Analytics -> Overview.

If you are running a Parse Push app, your data size may be bigger than what Parse reports for "Data storage". Email us at [email protected] for help.

2. Rate of operations your application will need the database to support

If you have a high traffic application you should consider our High Performance plans which have local SSD storage and high RAM-to-storage ratios. These plans offer the best performance of all of our plan types.

3. Upsizing temporarily for the migration

For migrations to Dedicated plans, we recommend choosing a plan that is one size up from where you think you'll ultimately end up in order to ensure a smooth migration. In case your indexes are unusually large, the additional RAM and storage will help reduce migration time and mitigate any risk of running out of storage space. We pro-rate all of our plans daily although prices are listed at the monthly rate.

If your attempt to migrate to one of our Dedicated plans encounters errors, please email [email protected] right away, and we'll help you troubleshoot.

Once the migration is complete, our performance team can on request analyze the performance of the deployment and work with you to optimize indexes and potentially remove redundant indexes. Our Ops team can then assist you in scaling down with a zero-downtime migration.

4. Enabling SSL support for your MongoDB connections

Enabling SSL adds another level of security for communication between the application and database, allowing clients to open encrypted connections to the database servers and then verify the identity of those servers before sending any sensitive information.

If you are running workloads with sensitive data, you may want to consider enabling SSL connections on your database deployment. In addition, if you will be hosting your mLab deployment in a datacenter other than AWS US East (where Parse service is hosted), we highly recommend enabling SSL connections at least until your Parse Server is also hosted in the same datacenter.

Visit our documentation on enabling SSL for more information and pricing.

Create and prepare your mLab database deployment

First, create a free mLab account. This will allow you to create new MongoDB databases on demand and manage multiple database deployments in a single view. We suggest that Parse users with multiple applications should create a database deployment per app.

For this tutorial, we created a Shared Cluster plan with the database name "parse-demo". Once your deployment is created and ready to be used, you'll see a green check mark by the deployment name.

Set the failIndexKeyTooLong parameter to false

MongoDB has a limit on how large an index key value may be if it is to be indexed. If you attempt to insert or update a document so that the value of an indexed field is longer than the Index Key Length Limit, the operation will fail and return an error to the client.

Parse migration guide suggests that the failIndexKeyTooLong MongoDB server parameter be set to "false" which will suppress this error and insert the document, although the document will not appear in the index and therefore not be found by queries that use that index.

Available only for Shared and Dedicated plans

You can temporarily toggle this parameter by navigating to the "Tools" tab for the deployment's primary node. Note that this parameter will not survive a restart and that setting this parameter on the primary will not affect the parameter on any other nodes in the deployment.

This parameter cannot be modified on a Sandbox database because other users on the shared database server process would be affected by the change.

If you want to migrate to a Sandbox, we suggest first attempting the migration without modifying the parameter. A "false" value is only necessary if your data contain indexed fields that exceed the maximum index key length of 1024 bytes. The migration may succeed without changing this parameter.

Keep this browser tab open as we'll need the database information in the next step.

Start the data migration process

From a new browser tab, open your Parse dashboard and navigate to App Settings -> General. Here you'll find the "Migrate to external database" option.

Once you click "Migrate", you'll be prompted for your database connection string. Go back to the mLab UI and click on the deployment you created.

If you created a Dedicated or Shared Cluster plan, you will see the cluster view above. Click on your database name, which is "parse-demo" in our example.

You'll then be taken to the database view. If you created a Sandbox plan, you are automatically brought to the database view.

Notice that we have not created a database user yet. Go ahead and create one now.

Once you've created a database user, you can construct a proper connection string URI that the Parse migration tool can use. Under "To connect using a driver via the standard MongoDB URI", you'll find your deployment-specific connection string. Copy this URI and replace the "dbuser" and "dbpassword" values with the user and password information that you have just created (note: do not include the "<>" characters in your username or password as they are placeholders).

Navigate back to the Parse tab and paste your database URI in the migration tool. If your deployment is running without SSL, you will receive a warning message but will be able to continue the migration. If you want to run a deployment with SSL enabled, you will have to use one of our Dedicated plans.

Verify and finalize the data migration

Once the migration is ready to be finalized, the progress will be in the "Verify" state, and you will receive an email from Parse to saying that you have "less than 24 hours" to finish the migration. Note that until the migration has been finalized, read traffic will still be hitting your database at Parse and not mLab.

Check counts

Review the "Rows Migrated" metric at Parse to make sure that this number is in line with the rows you see in your Parse Core -> Browser view.

You can also verify that the documents are in your mLab database by navigating to the database view.

Ask mLab support to do a health check and take a backup

If you are migrating into a Cluster plan at mLab, we suggest that you email [email protected] to help you verify that everything looks good from the database perspective. We will take a look at the deployment's performance metrics, make sure there is no replication lag on the replica set, and help you take a backup before you actually finalize the migration.

Finalize

Go back to the Migration tab and click the "Finalize" button.

Congratulations! You are now running Parse on your own MongoDB deployment!

Review important notes on database management

Now that your data has been migrated, there are a couple items to be conscious of:

1. You will need to manage your own database indexes.

The original Parse platform featured auto-indexing of your MongoDB collections based on your application's query patterns.

The open-source Parse Server software does not support auto-indexing. You will be responsible for managing your indexes, which is crucial for maintaining optimal database performance.

When you migrate your database to mLab, all existing indexes will be migrated. However, as you change your application and add new query patterns you will need to manage your indexes appropriately.

For more information on managing indexes please see:

If at any time you have questions about performance or need help with indexing strategies, please email [email protected] for help.

2. Images and files are not migrated as part of the database migration.

File storage is an important part of your application as it allows for shared storage of files such as documents, images, or videos. There are several ways Parse Server can store files associated with your application. To implement these Parse provides a number of File Adapters:

GridStoreAdapter, which is backed by MongoDB;
S3Adapter, which is backed by Amazon S3; or
GCSAdapter, which is backed by Google Cloud Storage

We strongly suggest storing files in S3 or Google Cloud Storage, as it is more scalable, less expensive, and minimizes load on your database.

We have provided steps on configuring S3 with Parse Server in a later section of this guide.

Part 2: Self-host the open-source Parse Server software

Now that you have successfully migrated your data from the Parse-hosted database onto an mLab database, you will have to replace the Parse backend service.

Parse Server prerequisites

Parse Server is an open-source version of the Parse backend that can be deployed to any infrastructure that can run Node.js. We'll walk through how to deploy Parse Server both locally and on Heroku.

Ensure that you have the following installed on your local machine:

Heroku toolbelt - This provides you access to the Heroku Command Line Interface (CLI), which can be used for managing and scaling your applications and add-ons.
Node.js

Test locally

Set up a staging database

We will first set up a local Parse Server and test that it can read and write to a test MongoDB database. We recommend setting up a staging database using a snapshot of your production database for this testing phase. If you use an empty database you might not be able to test your client applications properly. In contrast, if you use your actual production database for testing you risk corrupting production data.

To create a backup of your production database, go to the "Backups" tab for your deployment.

Click on the "Take one-time mongodump" or "Take one-time backup" button.

Once the backup is complete, go back to the home deployment view and click "Create from backup". Choose the newly created backup and choose the same plan type that your production database is running. This will create a new staging database from the backup. We recommend adding "-staging" to the name of the cluster or database.

Set up a local Parse Server

Now let's create a local Parse Server that connects to your staging database. This will allow you to test client applications and different API requests.

Make sure you have at least Node.js v4.3.

$ node --version
&gt; v5.7.0

Clone the repo and cd into the parse-server-example directory.

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

Install the Node.js modules

Take note of the MongoDB connection URI of the staging database.

Open the parse-server-example/index.js file in your favorite text editor.

Assign the MongoDB connection URI from your staging database to the databaseUri variable on line 7. The MongoDB connection URI is used to authenticate from your Parse Server to your mLab database.

var databaseUri = process.env.DATABASE_URI || process.env.MONGOLAB_URI || 'mongodb://<dbuser>:<dbpassword>@ds######-a0.mlab.com:#####,ds######-a1.mlab.com:#####/parse-demo?replicaSet=rs-ds######';

Next, go to the "Security & Keys" section of App Settings in your Parse Dashboard and take note of the "Application ID", "File key", and "Master key" values.

Within the opened parse-server-example/index.js file in your text editor, pass the following values into the ParseServer constructor.

Replace "myAppID" in the ParseServer constructor with your Application ID.
Replace "masterKey" in the ParseServer constructor with your Master key.
Replace "optionalFileKey" in the ParseServer constructor with your File key.

The "myAppID" is a unique identifier for your application, the "masterKey" overrides all permissions, and the "optionalFileKey" allows access to files already hosted on parse.com. The "optionalFileKey" will allow you to read images hosted on parse.com, and any writes will be saved by your Parse Server to the datastore you select through the files adapter (MongoDB, S3, …). Later in this tutorial we will go over how to set up your S3 bucket with Parse Server.

ParseServer constructor

var api = new ParseServer({
  databaseURI: databaseUri,
  cloud: process.env.CLOUD_CODE_MAIN || __dirname + '/cloud/main.js',
  appId: process.env.APP_ID || 'myAppId',
  masterKey: process.env.MASTER_KEY || 'masterKey', //Add your master key here. Keep it secret!
  fileKey: process.env.FILE_KEY || 'optionalFileKey', // For migrated apps, this is necessary to provide access to files already hosted on parse.com
  serverURL: process.env.SERVER_URL || 'http://localhost:1337'  // Don't forget to change to https if needed
});

Replace your "myAppId", "masterKey", "optionalFileKey", and MongoDB connection URI values only when testing the local Parse Server. Remove these string values before deploying to Heroku. We will be setting config vars later in this tutorial that will keep your sensitive application information hidden on Heroku. Always remember to keep your "myAppId", "masterKey", "optionalFileKey", and MongoDB connection URI information secure.

Run your local Parse Server

Now that we have finished configuring your ParseServer constructor, lets try running the local Parse Server.

Start the Parse Server

$ npm start
&gt; [email protected] start /Users/username/code/parse/parse-server-example
&gt; node index.js
&gt; parse-server-example running on port 1337.

Confirm your Parse Server is running by visiting . You should see "I dream of being a web site." in your browser.

Migrate Cloud Code to local Parse Server

We will now migrate your existing Cloud Code to run in your local Parse Server.

Change directory to the parse-server-example/cloud directory.

Copy your app's Cloud Code to the parse-server-example/cloud directory, replacing the example main.js.

There are a few considerations when using Cloud Code with Parse Server.

You will need to replace any relative paths like "cloud/…" to "./cloud" if there are any references in your code.
Native Cloud Code modules are not available in Parse Server, so you will need to use a replacement Node.js module.
There may also be compatibility issues with your Parse Server depending on your Cloud Code SDK version, queries, and methods.

Verify Cloud Code runs correctly

With Parse Server running, make example requests to verify that your Cloud Code is running correctly.

Because the Parse-hosted Cloud Code isn't running a full Node.js 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 before moving on.

Configure File Adapter for your local Parse Server

GridStoreAdapter, which is backed by MongoDB;
S3Adapter, which is backed by Amazon S3; or
GCSAdapter, which is backed by Google Cloud Storage

We strongly suggest storing files in S3 or Google Cloud Storage, as it is more scalable, less expensive, and minimizes load on your database.

Set up S3 bucket and permissions

Log into your AWS account or create a new one.
Head to the S3 service and choose "Create Bucket".
Fill out a unique Bucket Name and click "Create". The bucket name should not contain any period "." for directAccess to work. All other defaults are OK.
Now head to the Identity and Access Management (IAM) service.
Click the "Users" tab, then "Create New User".
Fill out at least one user name and make sure "Generate an access key for each user" is selected before clicking "Create".
Make sure to "Download Credentials" on the next screen.
Now select the "Policies" tab, then "Create Policy".
Select "Create Your Own Policy", fill out a "Policy Name".
Copy the following config in "Policy Document", changing "BUCKET_NAME" for the name of the bucket you created earlier.
```
{
```
"Version": "2012-10-17", "Statement": [
```
{
  "Effect": "Allow",
  "Action": [
    "s3:*"
  ],
  "Resource": [
    "arn:aws:s3:::BUCKET_NAME/*"
  ]
}
```
] }
Make sure to "Validate Policy" first, then click "Create Policy".
Go back to the "Users" tab and select the user you created earlier.
In Permissions, select "Attach Policy" and find the policy we just created to attach it.

Your S3 bucket has now been created, and a policy has been created to allow for Parse Server to access your S3 bucket for files storage. Now let's configure your Parse Server to be able to communicate with your S3 bucket.

Configure Parse Server to store files in S3

Within your parse-server-example/index.js file, configure the ParseServer constructor to use the S3 files adapter.

Require the S3 adapter within the parse-server-example/index.js.

var S3Adapter = require('parse-server').S3Adapter;

Make sure you place the above line before the ParseServer constructor code.

We will also be adding the "filesAdapter" constructor within the ParseServer constructor, which requires the "AWS_ACCESS_KEY_ID", "AWS_SECRET_ACCESS_KEY", and "BUCKET_NAME". You can find the AWS keys in the credentials file you had downloaded earlier (in step 7).

var api = new ParseServer({
  databaseURI: databaseUri || 'mongodb://localhost:27017/dev',
  cloud: process.env.CLOUD_CODE_MAIN || __dirname + '/cloud/main.js',
  appId: process.env.APP_ID || 'myAppId',
  masterKey: process.env.MASTER_KEY || '', //Add your master key here. Keep it secret!
  fileKey: process.env.FILE_KEY || 'optionalFileKey', // For migrated apps, this is necessary to provide access to files already hosted on parse.com.
  serverURL: process.env.SERVER_URL || 'http://localhost:1337',  // Don't forget to change to https if needed
  filesAdapter: new S3Adapter(
    process.env.AWS_ACCESS_KEY_ID || "AWS_ACCESS_KEY_ID",
    process.env.AWS_SECRET_ACCESS_KEY || "AWS_SECRET_ACCESS_KEY",
    process.env.BUCKET_NAME || "BUCKET_NAME"
  )
});

Replace your "AWS_ACCESS_KEY_ID", "AWS_SECRET_ACCESS_KEY", and "BUCKET_NAME" values only when testing the local Parse Server. Remove these values before deploying to Heroku. We will be setting config vars later in this tutorial that will keep your information hidden on Heroku. Always remember to your "AWS_ACCESS_KEY_ID", "AWS_SECRET_ACCESS_KEY", and "BUCKET_NAME" information secure.

S3Adapter constructor options

new S3Adapter(accessKey, secretKey, bucket, options)

Parameter	Description	Notes
accessKey	The AWS access key for a user that has the required permissions	Required.
secretKey	The AWS secret key for the user	Required.
bucket	The name of your S3 bucket.	Required.
options	JavaScript object (map) that can contain:
region	Key in `options`. Set the AWS region to connect to.	Optional. Default: 'us-east-1'
bucketPrefix	Key in `options`. Set to create all the files with the specified prefix added to the filename. Can be used to put all the files for an app in a folder with 'folder/'.	Optional. Default: ''
directAccess	Key in `options`. Controls whether reads are going directly to S3 or proxied through your Parse Server. If set to true, files will be made publicly accessible, and reads will not be proxied.	Optional. Default: false

Existing files on Parse backend service

Even though you have migrated your application data from Parse to mLab, your existing files are still in Parse's backend service. As long as you have specified the correct File key in the ParseServer constructor of your parse-server-example/index.js file, Parse Server knows exactly how to access them, so they will keep working just fine. Any new file you create using Parse Server will be saved on the in the datastore you set up through the files adapter.

File Migration from Parse backend service

Parse's backend service (S3 bucket) will be turned down on January 28th, 2017, which means those files will need to be migrated to your own S3 bucket account before that date. Parse has a plan and is currently working on a set of tooling to help you migrate all the existing files referenced by your application to your own S3 bucket or alternative backing store. We will update this tutorial section once Parse has a documented plan for migrating files for existing applications.

Review app settings impacted by Parse Server

Go through your app settings panel and make sure to review how these settings will be impacted by moving to Parse Server. Go to the App Settings -> Users in your Parse Dashboard and view the different settings for user sessions, authentication, and social login.

For a detailed description of each one of these settings that are currently supported by Parse Server versus what was available through the Parse backend service check here.

Test local Parse Server via command line

Once you've confirmed that your local Parse Server is running, you can now verify that your local server can receive requests. If you have successfully created a Parse Server, you can use the REST API directly.

Here are example requests you can use to confirm that your local server is configured properly. We recommend making test production client application requests to properly ensure full functionality.

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
&gt; {"objectId":"svbLKCXlzG","createdAt":"2016-03-03T00:46:45.828Z"}

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/GameScore
&gt;{"results":[{"objectId":"svbLKCXlzG","score":1337,"playerName":"Sean Plott","cheatMode":false,"updatedAt":"2016-03-03T00:46:45.828Z","createdAt":"2016-03-03T00:46:45.828Z"}]}

Test S3 file storage configuration

If you have added the S3 adapter for storing files, here are example requests you can use to confirm your local server can store files in your S3 bucket.

curl -X POST -H "X-Parse-Application-Id: YOUR_APP_ID" -H "Content-Type: image/jpeg" --data-binary '@myPicture.jpg' http://localhost:1337/parse/files/pic.jpg
&gt;{"url":"https://parse-demo.s3.amazonaws.com/1d4732c8555d0b026aaaefbc34453bc8_pic.jpg","name":"1d4732c8555d0b026aaaefbc34453bc8_pic.jpg"}

Put the "url" into your browser. If it downloads a jpg file, you have successfully stored a file onto S3 and can access it. Now you can associate files with objects.

For additional examples storing and accessing files on Parse Server, refer to their docs here:

Before moving to production, be sure to remove any test files from your S3 bucket.

Move your test client app onto your local Parse Server

Before deploying your Parse Server onto Heroku, first test your local Parse Server with a test client application.

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.

Update your test client application to point to the SERVER_URL of the local Parse Server. This may vary based on your code base, but be sure to configure your SERVER_URL to have "/parse" or "/1" (for older versions) at the end.

SERVER_URL: http://localhost:1337/parse

In addition, ensure that your AppId within your test client application matches the APP_ID config variable in your local Parse Server.

We highly recommend that you practice configuring and deploying a development or test client application to use your local Parse Server before deploying your Parse Server to Heroku. Test thoroughly before pushing to production to prevent any unexpected behavior.

Deploy to Heroku

Now that you have fully vetted your local Parse Server, you can deploy it to Heroku, a Platform-as-a-Service provider, which will host your production Parse Server. Your final production Parse Server will be used by your existing client applications.

The following steps will walk you through deploying to Heroku via command line.

Configure Heroku Toolbelt

$ heroku login
&gt; Enter your Heroku credentials.
&gt; Email: [email protected]
&gt; Password:
&gt; ...

Create an application on Heroku

Next, you will create a new Heroku application to host our Parse Server

$ heroku create
&gt; Creating app... done, stack is cedar-14
&gt; https://still-island-32919.herokuapp.com/ | https://git.heroku.com/still-island-32919.git

When you create an app, a remote git repository (called heroku) is also created and associated with your local git repository.

Heroku generates a random name (in this case "still-island-32919") for your app, or you can pass a parameter to specify your own app name e.g. heroku apps:create example-app

Set config vars

In our local workspace and previous testing, the Parse Server object has been configured with string values. The index.js file in the parse-server-example specifies defaults, which are superseded by Heroku config vars.

We'll now configure all the relevant config variables so that you no longer need to have string values in your Parse Server constructor.

$ heroku config:set APP_ID=myAppId
&gt; Setting config vars and restarting still-island-32919... done
&gt; APP_ID: myAppId

$ heroku config:set MASTER_KEY=masterKey
&gt; Setting config vars and restarting still-island-32919... done
&gt; MASTER_KEY: masterKey

$ heroku config:set FILE_KEY=optionalFileKey
&gt; Setting config vars and restarting still-island-32919... done
&gt; FILE_KEY: optionalFileKey

$ heroku config:set MONGOLAB_URI=mongodb://<dbuser>:<dbpassword>@ds######-a0.mlab.com:#####,ds######-a1.mlab.com:#####/production_db?replicaSet=rs-ds######
&gt; Setting config vars and restarting still-island-32919... done
&gt; MONGOLAB_URI: mongodb://<dbuser>:<dbpassword>@ds######-a0.mlab.com:#####,ds######-a1.mlab.com:#####/production_db?replicaSet=rs-ds######

$ heroku config:set SERVER_URL=http://myAppName.herokuapp.com/parse
Setting config vars and restarting still-island-32919... done
SERVER_URL: http://myAppName.herokuapp.com/parse

$ heroku config:set PARSE_MOUNT=/parse
Setting config vars and restarting still-island-32919... done
PARSE_MOUNT: /parse

By default the Parse Server will use a path of "/parse" for the API routes. To change this, or to use older client SDKs, run the command below.

$ heroku config:set PARSE_MOUNT=/1

If you added the S3 adapter, be sure to also add the AWS ID, Key, and Bucket Name variables.

$ heroku config:set AWS_ACCESS_KEY_ID=AWS_ACCESS_KEY_ID
&gt; Setting config vars and restarting still-island-32919... done
&gt; AWS_ACCESS_KEY_ID: AWS_ACCESS_KEY_ID

$ heroku config:set AWS_SECRET_ACCESS_KEY=AWS_SECRET_ACCESS_KEY
&gt; Setting config vars and restarting still-island-32919... done
&gt; AWS_SECRET_ACCESS_KEY: AWS_SECRET_ACCESS_KEY

$ heroku config:set BUCKET_NAME=BUCKET_NAME
&gt; Setting config vars and restarting still-island-32919... done
&gt; BUCKET_NAME: BUCKET_NAME

Deploy your code

Now that you've set your config vars, you can remove your "myAppId", "masterKey", "optionalFileKey", and MongoDB connection URI from your parse-server-example/index.js file before you deploy your code.

If you have added an S3 adapter, be sure to remove your "AWS_ACCESS_KEY_ID", "AWS_SECRET_ACCESS_KEY", and "BUCKET_NAME" as well. These steps will ensure that your sensitive application information is kept safe and not saved within your code as plain-text.

Now deploy your Parse Server code to Heroku:

$ git push heroku master
&gt; Counting objects: 136, done.
&gt; Delta compression using up to 8 threads.
&gt; Compressing objects: 100% (70/70), done.
&gt; Writing objects: 100% (136/136), 28.97 KiB | 0 bytes/s, done.
&gt; Total 136 (delta 63), reused 136 (delta 63)
&gt; remote: Compressing source files... done.
&gt; remote: Building source:
&gt; remote:
&gt; remote: -----&gt; Node.js app detected
&gt; remote:
&gt; remote: -----&gt; Creating runtime environment
&gt; remote:
&gt; remote:        NPM_CONFIG_LOGLEVEL=error
&gt; remote:        NPM_CONFIG_PRODUCTION=true
&gt; remote:        NODE_ENV=production
&gt; remote:        NODE_MODULES_CACHE=true
&gt; remote:
&gt; remote: -----&gt; Installing binaries
&gt; remote:        engines.node (package.json):  &gt;=4.3
&gt; remote:        engines.npm (package.json):   unspecified (use default)
&gt; remote:
&gt; remote:        Resolving node version &gt;=4.3 via semver.io...
&gt; remote:        Downloading and installing node 5.6.0...
&gt; remote:        Using default npm version: 3.6.0
&gt;      ....
&gt; remote: -----&gt; Build succeeded!
&gt; remote:        ├── [email protected]
&gt; remote:        ├── [email protected]
&gt; remote:        ├── [email protected]
&gt; remote:        └── [email protected]
&gt; remote:
&gt; remote: -----&gt; Discovering process types
&gt; remote:        Procfile declares types     -&gt; (none)
&gt; remote:        Default types for buildpack -&gt; web
&gt; remote:
&gt; remote: -----&gt; Compressing...
&gt; remote:        Done: 20.5M
&gt; remote: -----&gt; Launching...
&gt; remote:        Released v3
&gt; remote:        https://still-island-32919.herokuapp.com/ deployed to Heroku
&gt; remote:
&gt; remote: Verifying deploy.... done.
&gt; To https://git.heroku.com/still-island-32919.git
&gt;  * [new branch]      master -&gt; master

Open on Heroku

Confirm your Parse Server is running on Heroku.

You should see "I dream of being a web site." in your browser.

Test Parse Server via command line

Once you've confirmed that your Parse Server on Heroku is running, you can test that the Parse Server is working by using the previous methods used above for your local Parse Server. Note that the URL has changed, because your Parse Server is now running on Heroku. For example, our test GET request to our Heroku-hosted Parse Server is now:

curl -X GET -H "X-Parse-Application-Id: YOUR_APP_ID" -H "X-Parse-Master-Key: YOUR_APP_MASTER_KEY" http://myAppName.herokuapp.com/parse/classes/GameScore
&gt;{"results":[{"objectId":"Ry13dOYYIH","score":2016,"playerName":"Hans Gruber","cheatMode":true,"updatedAt":"2016-03-05T02:37:42.474Z","createdAt":"2016-03-05T02:37:42.474Z"}]}

Part 3: Migrate your client app to Parse Server

Test your client app

Move test client app onto self-hosted Parse Server

Now that you have a production-ready Parse Server deployed to Heroku, the next task is to try connecting a test client application. This is a precursor to moving your existing production client applications onto your Parse Server.

Update your test client application to point to the SERVER_URL of the Parse Server that you deployed on Heroku. Be sure to configure your SERVER_URL to have "/parse" or "/1" at the end.

SERVER_URL: http://myAppName.herokuapp.com/parse

Also change your AppId in your test client application to the APP_ID config variable in your Parse Server.

Roll out new client app to production

Change from the staging database to the production database

We have now tested end to end with a staging database, a Parse Server deployed to Heroku, and a test client application. Once you're confident with your Parse Server testing, you can replace the staging database URI with your production database URI. This is done by changing the config var in your Heroku deployment with the MongoDB connection URI of your production database. Your production database is the deployment you originally migrated your Parse data into.

Change config vars via the Heroku CLI:

$ heroku config:set MONGOLAB_URI=mongodb://<dbuser>:<dbpassword>@ds######-a0.mlab.com:#####,ds######-a1.mlab.com:#####/production_db?replicaSet=rs-ds######
&gt; Setting config vars and restarting still-island-32919... done
&gt; MONGOLAB_URI: mongodb://<dbuser>:<dbpassword>@ds######-a0.mlab.com:#####,ds######-a1.mlab.com:#####/production_db?replicaSet=rs-ds######'

Move production client apps onto product Parse Server

Once you've configured your Parse Server to use your production database, you can begin migrating your production client applications onto your Parse Server. You can migrate your apps by changing the server URL to your Parse Server URL and configuring your AppId. You can find examples specific to your client application languages in the Parse wiki.

Once you finish migrating your production client applications, you should encourage users to update to the newest version of your app as soon as possible. On January 28, 2017, any calls to the hosted Parse backend service (api.parse.com) will cease to function.

Resources

For the full Github repository of the example used in this tutorial, check the Parse Server example.

The following resources will be useful to you as you migrate your application from Parse.

If you need any help with this migration guide or have any questions please contact the mLab team at [email protected].

FAQ

Q. Why use mLab instead of self-hosting MongoDB on AWS, Azure, or Google?

mLab provides a Database-as-a-Service platform for MongoDB that takes care of all the operational aspects of running a fault-tolerant MongoDB cluster so that you can focus on your application. Our for-pay plans include:

Full automation of provisioning and scaling
Multi-zone replication and auto-failover
Automatic backups with easy restore
Monitoring and alerting
Web-based tools for managing your deployment and your data
Expert support, including 24x7 emergency support on Dedicated plans

See mLab's plans and features page as well as our pricing page for more information and details. If you have any questions about our service, please contact [email protected].

Q. Where should I host my Parse Server?

This tutorial shows you how to deploy your Parse Server onto Heroku, which is hosted on AWS. However, there are other alternative hosting providers to consider, especially if your mLab database is not on AWS. We strongly suggest that you host your database in the same datacenter as your Parse Server to minimize the latency between these two components of your application. Failure to do so can lead to poor application performance.

mLab supports MongoDB hosting on Amazon Web Services (AWS), Microsoft Azure, and Google Cloud Platform in most regions.

Here are some suggested strategies by cloud provider:

AWS:

Self-host your Parse Server on AWS and place your mLab database in the same AWS region.
Host your Parse Server on Heroku's Platform-as-a-Service (PaaS) and place your mLab database in the same AWS region (Heroku's guide).
Host using AWS Elastic Beanstalk, AWS's PaaS, and place your mLab database in the same AWS region (AWS' guide).

Azure:

Self-host your Parse Server on Azure and place your mLab database in the same Azure region.
Host your Parse Server with Azure App Service (Azure's PaaS) and place your mLab database in the same Azure region (Azure's guide).

Google:

Self-host your Parse Server on Google and place your mLab database in the same Google region.
Host your Parse Server on Google App Engine (Google's PaaS) and place your mLab database in the same Google region (Google's guide).

The Parse API runs in AWS US East, so if you are executing a migration plan that migrates the database first, we suggest you run your database in AWS US East. Placing your database in the same datacenter will maximize performance while your app is still hosted on Parse.

Q. How do I "ensure the user in the connection string has admin privileges"?

The reason that Parse's migration guide asks for a user that has "admin privileges" is that the migration tool will try to set the failIndexKeyTooLong parameter to false (see next FAQ). If the database user provided to Parse does not have admin privileges, the migration will still continue without setting the parameter.

An alternative approach which does not require you to provide Parse with a database user that has admin privileges is to:

Set the failIndexKeyTooLong parameter to false (see instructions in next FAQ)
Create a database user on the "Users" tab of the database that you'll be migrating into
Provide Parse with a connection string with the username/password for this database user

If you're using a Dedicated plan and really want to provide Parse with a database user that has full admin privileges (even though this is unnecessary), you can not use "admin" as the name of the database in the connection string or else the data will be migrated into the "admin" database which is intended for deployment metadata only.

Q. How do I set the failIndexKeyTooLong parameter to false?

MongoDB has a limit on how large a key value may be if it is to be indexed. If you attempt to insert or update a document so that the value of an indexed field is longer than the Index Key Length Limit, the operation will fail and return an error to the client.

Parse's migration guide suggests that the failIndexKeyTooLong MongoDB server parameter be set to "false" which will suppress this error and insert the document, although the document will not appear in the index and therefore not be found by queries that use that index.

The following instructions, by plan type, explain how to set the parameter to "false" for the migration.

Sandbox plan

Admin privileges are required in order to set the "failIndexKeyTooLong" parameter. Our free Sandbox plans do not provide administrative privileges nor the ability to override the default setting for this parameter.

If you are unable to use a for-pay plan, we suggest first attempting the migration without modifying the parameter. A "false" value is only necessary if your data contain indexed fields that exceed the maximum index key length of 1024 bytes. The migration may succeed without setting the parameter to "false".

Shared and Dedicated plans (for-pay plans)

Our Shared and Dedicated plans provide a means to override this setting. You can temporarily toggle this parameter by navigating to the "Tools" tab for the deployment.

Q. Will Parse Server still manage my database indexes?