Configuring a Parse Server


Parse provides a cloud-based backend service to build data-driven mobile apps quickly. Facebook, which acquired the company more than 3 years ago, announced that the service would be shutting down on January 28, 2017. An open source version enables developers to continue using their apps was published, along with a migration guide.

While there are many alternate options to Parse, most of them lack either the functionality, documentation, or sample code to enable quick prototyping. For this reason, the open source Parse version is a good option to use with minimal deployment/configuration needed.

Differences with Open Source Parse

You can review this Wiki to understand the current development progress of this app. There are a few notable differences in the open source version:

  • Authentication: By default, only an application ID is needed to authenticate with open source Parse. The base configuration that comes with the one-click deploy options does not require authenticating with any other types of keys. Therefore, specifying client keys on Android or iOS is not needed.

  • Push notifications: Because of the implicit security issues with allowing push notifications to be sent through Android or iOS directly to other devices, this feature is disabled. Normally in you can toggle an option to override this security restriction. For open source Parse, you must implement pre-defined code written in JavaScript that can be called by the clients to execute, otherwise known as Parse Cloud.

  • Single app aware: The current version only supports single app instances. There is ongoing work to make this version multi-app aware. However, if you intend to run many different apps with different datastores, you currently would need to instantiate separate instances.

  • File upload limitations: The backend for open source is backed by MongoDB, and the default storage layer relies on Mongo's GridFS layer. The current limit is set for 20 MB but if you depend on storing large files, you should really configure the server to use Amazon's Simple Storage Service (S3).

Many of the options need to be configured by tweaking your own configuration. You may wish to fork the code that helps instantiate a Parse server and change them based on your own needs. The guide below includes instructions on how to add push notifications and storing files with Parse.

Setting a new Parse Server

The steps described this guide walk through most of the process of setting an open source version with Parse. There are obviously many other hosting options, but the one-click deploys made available with Heroku as discussed in this guide are the simplest. In both cases, you are likely to need a credit card attached to your account to activate.

Signing up with Heroku

Use Heroku if you have little or no experience with setting up web sites. Heroku allows you to manage changes to deploy easily by specifying a GitHub repository to use. In addition, it comes with a UI data viewer from mLab.

  1. Sign Up / Sign In at Heroku

  2. Click on the button below to create a Parse App


  3. Make sure to enter an App Name. Scroll to the bottom of the page.

  4. Make sure to change the config values.

    • Leave PARSE_MOUNT to be /parse. It does not need to be changed.
    • Set APP_ID for the app identifier. If you do not set one, the default is set as myAppId. You will need this info for the Client SDK setup.
    • Set MASTER_KEY to be the master key used to read/write all data. Note: in hosted Parse, client keys are not used by default.
    • Set SERVER_URL to be Assuming you have left PARSE_MOUNT to be /parse, this will enable the use of Parse Cloud to work correctly.
    • If you intend to use Parse's Facebook authentication, set FACEBOOK_APP_ID to be the FB application ID.
    • If you intend to setup push notifications, there are additional environment variables such as GCM_SENDER_KEY and GCM_API_KEY┬áthat will need to be configured. See this section for the required steps.
  5. Deploy the Heroku app. The app should be hosted at https://<app name> where <app name> represents your App Name that you provided (or if one was assigned to you if you left this field blank).

If you ever need to change these values later, you can go to (<app name>/settings). Check out this guide for a more detailed set of steps for deploying Parse to Heroku.

Now, we can test our deployment to verify that the Parse deployment is working as expected!

Testing Deployment

After deployment, try to connect to the site. You should see I dream of being a website. Please star the parse-server repo on GitHub! if the site loaded correctly. If you try to connect to the /parse endpoint, you should see {error: "unauthorized"}. If both tests pass, the basic configuration is successful.

Next, make sure you can create Parse objects. You do not need a client Key to write new data:

curl -X POST -H "X-Parse-Application-Id: myAppId" \
-H "Content-Type: application/json" \
-d '{"score":1337,"playerName":"Sean Plott","cheatMode":false}' \

Be sure to replace the values for myAppId and the server URL. If you see Cannot POST error then be sure both the X-Parse-Application-Id and the URL are correct for your application. To read data back, you will need to specify your master key as well:

curl -X GET -H "X-Parse-Application-Id: myAppId" -H "X-Parse-Master-Key: abc"  \

Be sure to replace the values for myAppId and the server URL. If these commands work as expected, then your Parse instance is now setup and ready to be used!

Browsing Parse Data

There are several options that allow you to view the data. First, you can use the mLab viewer to examine the store data. Second, you can setup the open source verson of the Parse Dashboard, which gives you a similar UI used in hosted Parse. Finally, you can use Robomongo.


The hosted Parse instance deployed uses mLab (previously called MongoLab) to store all of your data. mLab is a hosted version of MongoDB which is a document-store which uses JSON to store your data.

If you are using Heroku, you can verify whether the objects were created by clicking on the MongoDB instance in the Heroku panel:

Parse Dashboard

You can also install Parse's open source dashboard locally. Download NodeJS v4.3 or higher. Make sure you have at least Parse server v2.1.3 or higher (later versions include a /parse/serverInfo that is needed).

npm install -g parse-dashboard
parse-dashboard --appId myAppId --masterKey myMasterKey --serverURL ""

Connect to your dashboard at http://localhost:4040/apps. Assuming you have specified the correct application ID, master Key, and server URL, as well as installed a Parse open source version v2.1.3 or higher, you should see the app appear correctly:


You can also setup Robomongo to connect to your remote mongo database hosted on Heroku to get a better data browser and dashboard for your app.

To access mLab databases using Robomongo, be sure to go the MongoDB instance in the Heroku panel as shown above. Look for the following URL: mongodb://<dbuser>:<dbpassword> Use that to identify the login credentials:

port: 11218
db: heroku_2flx41aa
user: dbuser
password: dbpassword

Using that cross-platform app to easily access and modify the data for your Parse MongoDB data.

Enabling Client SDK integration

Make sure you have the latest Parse-Android SDK in your app/build.gradle file. It should be at least 1.13.1:

dependencies {
    compile 'com.parse:parse-android:1.13.1'
    compile 'com.parse:parseinterceptors:0.0.2' // for logging API calls to LogCat
    compile 'com.parse.bolts:bolts-android:1.+'

If you are migrating from a previous Parse configuration, make sure to delete the CLIENT_KEY reference in your AndroidManifest.xml file. You can in fact delete both lines since we will be using a custom config builder in the next step.

 <!--- these lines should be deleted in lieu of our custom Parse builder -->
            android:value="myAppId" />
            android:value="clientKey" />
 <!--- end of delete --->

Modify your Parse.initialize() command to point to this newly created server. You must be on the latest Parse Android SDK to have these options.

public class ParseApplication extends Application {
    public void onCreate() {

        // set applicationId, and server server based on the values in the Heroku settings.
        // clientKey is not needed unless explicitly configured
        // any network interceptors must be added with the Configuration Builder given this syntax
        Parse.initialize(new Parse.Configuration.Builder(this)
                .applicationId("myAppId") // should correspond to APP_ID env variable
                .clientKey("")  // set explicitly blank unless clientKey is configured on Parse server
                .addNetworkInterceptor(new ParseLogInterceptor())

The /parse/ path needs to match the PARSE_MOUNT environment variable, which is set to this value by default.

Troubleshooting Parse Server

  • If you see Application Error or An error occurred in the application and your page could not be served. Please try again in a few moments., double-check that you set a MASTER_KEY in the environment settings for that app.

  • If you are using Heroku, download the Heroku Toolbelt app here to help view system logs.

First, you must login with your Heroku login and password:

heroku login

You can then view the system logs by specifying the app name:

heroku logs --app <app name>

The logs should show the response from any types of network requests made to the site. Check the status code.

2016-02-07T08:28:14.292475+00:00 heroku[router]: at=info method=POST path="/parse/classes/Message" request_id=804c2533-ac56-4107-ad05-962d287537e9 fwd="" dyno=web.1 connect=1ms service=2ms status=404 bytes=179
  • If you are seeing Master key is invalid, you should only use master key to send push, chances are you are trying to send Push notifications without enable client push. On you can simply enable a toggle switch but for hosted parse there is an outstanding issue that must be resolved to start supporting it.

  • If you see the exception Error Loading Messagescom.parse.ParseException: java.lang.IllegalArgumentException: value == null, try setting the clientKey to a blank string such as Parse.initialize(...).applicationId(...).clientKey("") rather than null. Review this issue and this issue for further details.

  • You can also use Facebook's Stetho interceptor to watch network logs with Chrome:

    dependencies {
      compile 'com.facebook.stetho:stetho:1.3.0'

And add this network interceptor as well:

 Stetho.initializeWithDefaults(this); // init Stetho before Parse

 Parse.initialize(new Parse.Configuration.Builder(this)
   .addNetworkInterceptor(new ParseStethoInterceptor())
  • If you wish to troubleshoot your Parse JavaScript code is to run the Parse server locally (see instructions). You should also install node-inspector for Node.js, which allows you to use Chrome or Safari to step through the code yourself:
npm install node-inspector
node --debug index.js

Open up locally. You can use the Chrome debugging tools to set breakpoints in the JavaScript code.

Point your Android client to this server::

Parse.initialize(new Parse.Configuration.Builder(this)
     .server("")  // lookup your IP address of your machine

Enabling Push Notifications

See this guide for more details about how to setup both the Parse open source version and the Parse Android SDK Client.

Storing Files with Parse

You can continue to save large files to your Parse backend using ParseFile without any major changes:

byte[] data = "Working at Parse is great!".getBytes();
ParseFile file = new ParseFile("resume.txt", data);

By default, the open source version of Parse relies on the MongoDB GridStore adapter to store large files. There is an alternate option to leverage Amazon's Simple Storage Service (S3) but still should be considered experimental.

Using Amazon S3

If you wish to store the files in an Amazon S3 bucket, you will need to make sure to setup your Parse server to use the S3 adapter instead of the default GridStore adapter. See this Wiki for how to configure your setup. The steps basically include:

  1. Modify the Parse server to use the S3 adapter. See these changes as an example.
  2. Create an Amazon S3 bucket.
  3. Create an Amazon user with access to this S3 bucket.
  4. Generate an authorized key/secret pair to write to this bucket.
  5. Set the environment variables:
    • Set S3_ENABLE to be 1.
    • Set AWS_BUCKET_NAME to be the AWS bucket name.
    • Set AWS_ACCESS_KEY and AWS_SECRET_ACCESS_KEY to be the user that has access to read/write to this S3 bucket.

When testing, try to write a file and use the Amazon S3 console to see if the files were created in the right place.

Fork me on GitHub