How to Migrate from Parse (Part 2, Setting up the Server)

Grant is groggy. It’s Monday morning. He’s still thinking about Puzzle Fighter as he steps through the Go Nimbly front door. That’s when Ian drops a bomb. “Remember that Parse migration thing you needed to do? Parse is shutting down next month and you still haven’t migrated God Hates Charades.”

He’s not the only one who’s been procrastinating. Fortunately at Go Nimbly we’ve handled migrations for a variety of clients. That’s why we put together this three-part series on a typical Parse Server migration. If you haven’t, I recommend starting with part 1.

Last time I went through how to migrate your database from Parse’s hosted solution to MongoDB hosted by mLab. If you have a production app you should have also migrated your production database by now. Today I’ll go over how to get a Parse Server instance up and running on Heroku. It should take about an hour so let’s rock.

Clone go-nimbly-parse-server-example

Parse-server-example is a template for a basic Parse Server. This makes it a great starting point for your Parse Server.

1. Open a terminal window and cd into the directory where code lives on your computer.

$ cd your/billion/dollar/ideas/

2. Clone the contents of the go-nimbly-parse-server-example into your folder.

$ git clone https://jgaull@bitbucket.org/jgaull/go-nimbly-parse-server-example.git

3. After the repo finishes cloning cd into the go-nimbly-parse-server-example directory…

$ cd go-nimbly-parse-server-example/

4. Take a look at the contents:

$ ls
Dockerfile  azuredeploy.json openshift.json
README.md   cloud            package.json
app.json    index.js         public
app.yaml    jsconfig.json    scalingo.json

In the root directory there are two files to take note of. The first is index.js. It’s the starting point of your server. Open it in your text editor of choice and take a look at lines 14–20:

var api = new ParseServer({
  databaseURI: databaseUri || 'mongodb://localhost:27017/dev',
  cloud: process.env.CLOUD_CODE_MAIN || './cloud/main.js',
  appId: process.env.APP_ID || 'myAppId',
  masterKey: process.env.MASTER_KEY || '',
  serverURL: process.env.SERVER_URL || 'http://localhost:1337/parse'
});

This is where your server is configured. Notice all the lines that say process.env.NAME_OF_VARIABLE. These are environment variables. They are configuration data that your app will use at run time such as the application keys and your database URI. I will show you how to assign values to them soon.

Next take a look at the file named package.json. Parse-server runs in Node.js. The package.json file is at the heart of every Node.js project. Notice the section nameddependencies:

"dependencies": {
    "express": "~4.11.x",
    "kerberos": "~0.0.x",
    "parse": "~1.8.0",
    "parse-server": "*"
  }

This is a list of packages that your project needs in order to work. Your Heroku server will use this list to automatically install the correct packages when deploying a build. The package.json in parse-server-example includes the necessities for getting a basic Parse Server up and running.

While you’re in the package.json you should change the project name, version, description, etc. to values that are appropriate for your project:

"name": "go-nimbly-parse-server-example",
"version": "1.4.0",
"description": "An example Parse API server using the parse-server module",

Create a Server on Heroku

Heroku allows you to create apps. Each app consists of some number of dynos. Each dyno is an instance of a server for your app. You will create an app with one dyno for your Parse Server.

First, create a free Heroku account.

Heroku Toolbelt is a command line tool for performing common Heroku tasks. Install the Heroku Toolbelt. (All of the functionality we’ll use in this guide is duplicated within the web interface so feel free to use that if you prefer.)

Go back to your terminal window. Log in to Heroku:

$ heroku login

Create a Heroku server:

$ heroku create <name-of-app>
Creating ⬢ <name-of-app>... done
https://<name-of-app>.herokuapp.com/ | https://git.heroku.com/<name-of-app>.git

This command does a bunch of stuff, but there are two things in particular that are relevant to you at this time. The first is that it creates an app with one dyno. You can send requests to the app with the herokuapp.com URL that heroku create returned. Save this URL for later.

The second is that it adds a Git remote named heroku that points to the Git URL for this app on heroku. The Git repo is used to deploy code to the server. More on that soon.

Deploy Your Parse Server

Time to turn the key and listen to this kitten purr.

Commit your changes to package.json:

$ git commit -am “Initial parse-server configuration”

Deploy the changes to your Heroku server by using the heroku remote:

$ git push heroku master

Watch your console window blow up with the beautiful sight of a Heroku deployment. At this point Heroku is turning your code into a slug. In this case the slug contains go-nimbly-parse-server-example’s code and all the dependencies listed in the package.json.

After the push completes, go to your browser and visit your server’s URL:

https://<your-app>.herokuapp.com/

You should see “I dream of being a website.” Yay! This tells you that your server is up and running.

Now you need to make sure Parse is up and running. To do this you can call a test cloud code function that go-nimbly-parse-server-example includes by default. Use this curl command to call the hello function (make sure to replace <your app id> and <your-app-name>):

curl -X POST \
  -H "X-Parse-Application-Id: <your app id>" \
  -H "Content-Type: application/json" \
  -d '{}' \
  https://<your-app-name>.herokuapp.com/parse/functions/hello

Bummer, {“error”:”unauthorized”}. Time to take a look at Heroku’s logs to see if there is any helpful info.

$ heroku logs --tail --app <your-app-name>

Uh oh, looks like there was an error connecting to the database:

2016-11-16T22:10:30.338600+00:00 app[web.1]: DATABASE_URI not specified, falling back to localhost.
2016-11-16T22:10:30.429731+00:00 app[web.1]: Your parse-server is running on port 32929.
2016-11-16T22:10:30.478343+00:00 app[web.1]: warn: Unable to ensure uniqueness for usernames:  MongoError: failed to connect to server [localhost:27017] on first connect

If you remember, the database URI should be contained in one of those handy environment variables you saw in index.js. Unfortunately it hasn’t been configured so your Parse Server isn’t yet functional.

Configure Your Parse Server

It’s time to configure your environment variables. First you’ll need to assemble some information.

Go back to your Parse Dashboard at Parse.com. Click App Settings -> Security and Keys. Copy and paste the Application ID and Master Key into a text document.

Now it’s time to assign values to those environment variables. Set the DATABASE_URI environment variable with this Heroku Toolbelt comand:

$ heroku config:set DATABASE_URI=<your database uri>

Your Heroku server will restart. Congratulations, you’ve just told Parse Server where your database can be found.

Run the same command to set your APP_ID, MASTER_KEY, and SERVER_URL.

$ heroku config:set APP_ID=<your app id>
$ heroku config:set MASTER_KEY=<your master key>
$ heroku config:set SERVER_URL=https://<your-app-name>.herokuapp.com/parse/

Run the CURL command again:

curl -X POST \
  -H "X-Parse-Application-Id: <your app id>" \
  -H "Content-Type: application/json" \
  -d '{}' \
  https://<your-app-name>.herokuapp.com/parse/functions/hello

This time you should see {“result”:”Hi”}.

Congratulations, you win! The prize? You’re ready for the final part of this series. In part 3, you’ll update your front-end to point at the new server and port your cloud code.

Go Nimbly is the premier marketing and sales consultancy for SaaS companies. Founded and headquartered in San Francisco, Go Nimbly provides customers with a customized team to manage everything from strategy to execution for their marketing and sales systems. To learn more, visit gonimbly.com.