Migrate from Parse to MongoDB Cloud Manager & AWS

1. Register for and Configure AWS

Requirements

• Credit Card
• Phone Number

Instructions

1. Create AWS account on https://aws.amazon.com/
2. Go to IAM Console.
3. Click "Users": Create a user for yourself and record:
       a. "Access Key ID"
       b. "Secret Access Key"
   
4. Save these credentials in a safe place, you will not be able to access them again.
5. Click on user created, and select the "Permissions" tab under Summary. Click "Attach Policy" and select "AmazonEC2FullAccess" and "AdministratorAccess", as described in the Cloud Manager documentation.
6. Navigate to the EC2 console for the us-east-1 region
7. Select "Network & Security -> Security Groups" with the left hand menu
8. Click "Create Security Group" and create a new security group without any rules (we will refer to this group as "MongoDB-Security-Group" through the rest of these tutorials) .
9. Click on the group, select the "Inbound" tab, and click edit. Add inbound rules:
       a. Custom TCP rule for port 27000 for "MongoDB-Security-Group" itself (enter the Security Group ID in the source field)
       b. SSH rule for port 22 for anywhere (0.0.0.0/0)
   
10. Save rules and refresh to verify that they were correctly added.

2. Deploy MongoDB replica set on AWS using MongoDB Cloud Manager

Requirements

• File Storage, Data Storage, and Data Transfer Rate from Parse dashboard
• SSL Certificate from trusted Certificate Authority (for secure deployment)
• AWS Credentials

Before you begin:

Size your Instances

During this stage, you will provision Amazon EC2 instances to run your database processes. To help you best size your deployment, we have created a sizing chart. To use the worksheet, first get your Data Storage, and Data Transfer Rate per month from the Parse dashboard.

Choose the cell in the sizing chart that matches your usage profile. Note this down, as we will use it later in the instructions to determine which machine to provision.

Generate SSL Certificates

For a secure deployment, one should enable TLS/SSL for traffic between the MongoDB database and the application server, as well as for traffic between the members of a MongoDB replica set.

For development purposes, you can configure a local certificate authority and generate your own certificates with openssl for the hosts provisioned by Cloud Manager.

Self-signed certificates, however, are still vulnerable to man-in-the-middle attacks and secure deployments should use an TLS/SSL certificate from a trusted Certificate Authority.

Instructions

1. Register for MongoDB Cloud Manager at https://www.mongodb.com/cloud (click "Start your 30-day free trial" to begin).
2. Choose a New Group Name for your Cloud Manager Group. (We will refer to this group as "App Group", but you should name it something that makes sense for your application).
3. Use the wizard to deploy a new 3 node replica set in the "us-east-1" region. We will name this replica set "mongodb-rs" but you should name it something that makes sense for you.
4. You will be asked to configure your EC2 Instances. Set:

5. Click "Provision Servers" and wait. Once three server automation agents are visible, click "Continue".
6. Click “Advanced Setup” in the top right, then click the wrench icon to the top right of the Replica Set topology view to open the Replica Set editor. (the wrench should be under “Actions” in the “Deployment” view)

7. Modify the version to 3.0.x latest (e.g. 3.0.9). Review your changes, and click “Apply”.

8. Ensure that everything looks correct, then click “Review & Deploy”, then “Confirm & Deploy”.
9. Click the wrench icon to once again open the Replica Set editor.
10. Expand “Advanced Options”, and click the “Add Option” button.
11. Add the option:
• Startup Option: “failIndexKeyTooLong”
• Value: false

12. It is strongly recommended that you configure TLS/SSL for your deployment before migrating from Parse. Instructions on how to do this can be found in the Cloud Manager documentation
13. Click “Apply”, and again “Review and Deploy” your changes.
14. We will now configure a user for you to connect to your database with. Click on “Authentication & Users” on the left side of the UI.
15. Click “Add user” and create a new user with the specs below. Don't forget to save the password!
• database: “admin”
• username: “testuser”
• roles: root@admin

Test that you can connect to your MongoDB Replica Set.

Construct the MongoDB_ReplicaSet_URI.

First, record the three replica set members’ hostnames and ports visible in Cloud Manager. We will then combine the hostnames with their respective ports, separated by commas, along with the username and password, replica set name (replicaSet) and SSL parameters as below:

mongodb://testuser:testpass@mdb-1.dnshostname:27000,mdb-2.dnshostname:27000,mdb-3.dnshostname:27000/?replicaSet=mongodb-rs&ssl=true

More detailed information on the connection string format can be found in the MongoDB documentation. Hold onto the connection string you've made, we will reference this as the MongoDB_ReplicaSet_URI later in the tutorial.

3. Deploy Parse stack locally

Requirements

• Node.js version 4.x or newer
• npm

Instructions

1. Install the parse-server module from npm
• a. Open a terminal and run npm install -g parse-server
2. Install MongoDB; download 3.0 here
3. Clone the parse-server-example repository and start the app
• Run git clone https://github.com/ParsePlatform/parse-server-example
4. Copy your Application ID and Master Key from Parse.com’s administrative interface under “App Settings”, by selecting “Security & Keys”
5. Modify the index.js file to properly contain your Application ID and your Master Key, using your text editor of choice.

Initially the middle part of index.js will look like:

 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 || 'myMasterKey' 
 }); 
 // Client-keys like the javascript key or the .NET key are not necessary with   parse-server 
 // If you wish you require them, you can set them as options in the             initialization above: 
 // javascriptKey, restAPIKey, dotNetKey, clientKey

Modify and save the file and replace the MYDATABASEURI, MYAPPIO, and MYMASTERKEY fields below, with quotes values: # index.js

var api = new ParseServer({ 
   databaseURI: MY_DATABASE_URI, 
   cloud: __dirname + '/cloud/main.js', 
   appId: MY_APP_ID, 
   masterKey: MY_MASTER_KEY, 
 }); 
 // Client-keys like the javascript key or the .NET key are not necessary with   parse-server 
 // If you wish you require them, you can set them as options in the             initialization above: 
 // javascriptKey, restAPIKey, dotNetKey, clientKey

See the example below for how this should look in practice:

var api = new ParseServer({
  databaseURI: 'mongodb://localhost:27017',
  cloud: process.env.CLOUD_CODE_MAIN || __dirname + '/cloud/main.js',
  appId: 'Sa7DThZqltQFRm0nIb11LQsN6SEMVcTBGoBKwJnh',
  masterKey: 'QOLq1NtAoz8hnK2eU92ENPaWgAvpiEFWsq52S26'
 }); 
 // Client-keys like the javascript key or the .NET key are not necessary with   parse-server 
 // If you wish you require them, you can set them as options in the             initialization above: 
 // javascriptKey, restAPIKey, dotNetKey, clientKey

6. If your deployment leverages parse’s Cloud Code capabilities, then you will need to copy your cloud code *.js files into the cloud directory in parse-server-example.
• NOTE: the Cloud Code environment hosted on Parse.com and that executed by the open source parse-server are not exactly identical, so be sure to thoroughly test all critical code paths during migration.
7. You are now ready to start your parse-server app.
• npm install
• npm start
8. You should now be able to point your application at your express application (by default running on port 1337) which will be running from your local mongodb instance. You can use ngrok to test your app’s functionality and ensure that everything is working as planned locally.
9. Once you have a stable version, we will want to create a .zip file containing all of the files in our parse-server-example express application, which we will use to deploy to Amazon ElasticBeanstalk.
10. Don't forget to update MYDATABASEURI with the appropriate mongodb connection string (defined as MongoDBReplicaSetURI in Step 2 above) that you will get from the list of hostnames used to deploy your replica set in MongoDB Cloud Manager, and save it into index.js.

4. Deploy Parse stack on AWS Elastic Beanstalk

Requirements

• AWS Credentials
• zip file with correct configuration (from Step 3 above)

Instructions

1. Sign back into your AWS account and click on Elastic Beanstalk.
2. Choose a configuration option for your Application server. Chose the Node.js platform under “Preconfigured” and click “Launch Now”.
3. AWS will provision and begin to configure your new ElasticBeanstalk instance.
4. Once your instance is ready, click the Upload and Deploy button.
5. This will bring you to a screen where you can upload the zip file you configured earlier. It is probably also a good idea to name your version with a reasonable label. Now, we need to once again configure the inbound rules for AWS so that the ElasticBeanstalk instance can talk to the MongoDB replica set. This can be easily configured using AWS security groups.

6. Navigate to “Services->EC2”. Select “Network & Security -> Security Groups” from the navigation bar on the left side of the screen. You should now see something like this:

   

7. ElasticBeanstalk will have created a default security group for itself when you configured it earlier. In the case - it is the one with the description “SecurityGroup for ElasticBeanstalk Environment”. Copy the Group ID for this entry into your clipboard.
8. Open up the inbound rules for the security group containing your database servers, and add a custom TCP rule for port 27000. Select “Custom IP” and paste the Group ID for the ElasticBeanstalk security group. This allows our ElasticBeanstalk instance to connect to our MongoDB replica set while still preventing general access from the outside world.
9. We can now test our deployed parse-server endpoint using the GET and POST commands from the Parse API. If you have curl, the following commands will test basic functionality.

curl -X POST \
  -H "X-Parse-Application-Id: ${MY_PARSE_APP_ID}" \
  -H "X-Parse-Master-Key: ${MY_PARSE_MASTER_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"score":1337,"playerName":"Sean Plott","cheatMode":false}' \
  http://${MY_ELASTIC_BEANSTALK_INSTANCE}/parse/classes/GameScore

curl -X GET \
  -H "X-Parse-Application-Id: ${MY_PARSE_APP_ID}" \
  -H "X-Parse-Master-Key: ${MY_PARSE_MASTER_KEY}" \
  http://${MY_ELASTIC_BEANSTALK_INSTANCE}/parse/classes/GameScore

5. Test application with new infrastructure

Please use your standard application tests to ensure all functionality works on your new, open source Parse infrastructure. The open source parse-server package does not cover the complete feature set offered by Parse, and your application may not function exactly the same as before. The Parse migration guide has more details on the differences between Parse and parse-server in "Section 8 - Compatibility Issues". We urge users to read these sections carefully and test their apps thoroughly before moving forward with a full migration. If you are interested in getting help with this process, or learning more about your options for running your own MongoDB deployment, our professional services team is here to speak with you.

6. Export data from Parse into MongoDB replica set

Requirements

• MongoDB replica set on AWS EC2
• Access to Parse admin dashboard
• User with admin privileges on MongoDB replica set

Instructions

1. Go to the new Parse dashboard > “App Settings” and click on “Migrate to external database”.

• Provide the MongoDB_ReplicaSet_URI which we defined in Step 2 above.

• Click the “Begin the migration” button.
• Ensure that the data is written to your MongoDB Replica Set.

7. Looking forward

MongoDB is here to support the Parse community, and we will continue to monitor and vet best practices and new tools. As these expand, we will also be expanding this tutorial, and other resources to help users adapt to the new landscape.