Parse Server is an open source version of the Parse backend that can be deployed to any infrastructure that can run Node.js.

Parse Server works with the Express web application framework. It can be added to existing web applications, or run by itself.

Getting Started

The fastest and easiest way to get started is to run MongoDB and Parse Server locally:

$ npm install -g parse-server mongodb-runner
$ mongodb-runner start
$ parse-server --appId APPLICATION_ID --masterKey MASTER_KEY

You can use any arbitrary string as your application id and master key. These will be used by your clients to authenticate with the Parse Server.

That's it! You are now running a standalone version of Parse Server on your machine.

Using a remote MongoDB? Pass the --databaseURL DATABASE_URI parameter when starting parse-server. Learn more about configuring Parse Server here. For a full list of available options, run parse-server --help.

Saving your first object

Now that you're running Parse Server, it is time to save your first object. We'll use the REST API, but you can easily do the same using any of the Parse SDKs. Run the following:

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

You should get a response similar to this:

{
  "objectId": "2ntvSpRGIK",
  "createdAt": "2016-03-11T23:51:48.050Z"
}

You can now retrieve this object directly (make sure to replace 2ntvSpRGIK with the actual objectId you received when the object was created):

$ curl -X GET \
  -H "X-Parse-Application-Id: APPLICATION_ID" \
  http://localhost:1337/parse/classes/GameScore/2ntvSpRGIK

// Response
{
  "objectId": "2ntvSpRGIK",
  "score": 1337,
  "playerName": "Sean Plott",
  "cheatMode": false,
  "updatedAt": "2016-03-11T23:51:48.050Z",
  "createdAt": "2016-03-11T23:51:48.050Z"
}

Keeping tracks of individual object ids is not ideal, however. In most cases you will want to run a query over the collection, like so:

$ curl -X GET \
  -H "X-Parse-Application-Id: APPLICATION_ID" \
  http://localhost:1337/parse/classes/GameScore

// The response will provide all the matching objects within the `results` array:
{
  "results": [
    {
      "objectId": "2ntvSpRGIK",
      "score": 1337,
      "playerName": "Sean Plott",
      "cheatMode": false,
      "updatedAt": "2016-03-11T23:51:48.050Z",
      "createdAt": "2016-03-11T23:51:48.050Z"
    }
  ]
}

To learn more about using saving and querying objects on Parse Server, check out the Parse documentation.

Connect your app to Parse Server

Parse provides SDKs for all the major platforms. Refer to the Parse Server guide to learn how to connect your app to Parse Server.

Running Parse Server elsewhere

Once you have a better understanding of how the project works, please refer to the Parse Server wiki for in-depth guides to deploy Parse Server to major infrastructure providers. Read on to learn more about additional ways of running Parse Server.

Parse Server Sample Application

We have provided a basic Node.js application that uses the Parse Server module on Express and can be easily deployed using any of the following buttons:

Parse Server + Express

You can also create an instance of Parse Server, and mount it on a new or existing Express website:

var express = require('express');
var ParseServer = require('parse-server').ParseServer;
var app = express();

// Specify the connection string for your mongodb database
// and the location to your Parse cloud code
var api = new ParseServer({
  databaseURI: 'mongodb://localhost:27017/dev',
  cloud: '/home/myApp/cloud/main.js', // Provide an absolute path
  appId: 'myAppId',
  masterKey: 'myMasterKey', // Keep this key secret!
  fileKey: 'optionalFileKey',
  serverURL: 'http://localhost:1337/parse' // Don't forget to change to https if needed
});

// Serve the Parse API on the /parse URL prefix
app.use('/parse', api);

app.listen(1337, function() {
  console.log('parse-server-example running on port 1337.');
});

Documentation

The full documentation for Parse Server is available in the wiki. The Parse Server guide is a good place to get started. If you're interested in developing for Parse Server, the Development guide will help you get set up.

Migrating an Existing Parse App

The hosted version of Parse will be fully retired on January 28th, 2017. If you are planning to migrate an app, you need to begin work as soon as possible. There are a few areas where Parse Server does not provide compatibility with the hosted version of Parse. Learn more in the Migration guide.

Configuration

Parse Server can be configured using the following options. You may pass these as parameters when running a standalone parse-server, or by loading a configuration file in JSON format using parse-server path/to/configuration.json. If you're using Parse Server on Express, you may also pass these to the ParseServer object as options.

For the full list of available options, run parse-server --help.

Basic options

• appId (required) - The application id to host with this server instance. You can use any arbitrary string. For migrated apps, this should match your hosted Parse app.
• masterKey (required) - The master key to use for overriding ACL security. You can use any arbitrary string. Keep it secret! For migrated apps, this should match your hosted Parse app.
• databaseURI (required) - The connection string for your database, i.e. mongodb://user:[email protected]/dbname.
• cloud - The absolute path to your cloud code main.js file.
• facebookAppIds - An array of valid Facebook application IDs.
• serverURL - URL which will be used by Cloud Code functions to make requests against.
• push - Configuration options for APNS and GCM push. See the wiki entry.

Client key options

The client keys used with Parse are no longer necessary with Parse Server. If you wish to still require them, perhaps to be able to refuse access to older clients, you can set the keys at initialization time. Setting any of these keys will require all requests to provide one of the configured keys.

• clientKey
• javascriptKey
• restAPIKey
• dotNetKey

Advanced options

• fileKey - For migrated apps, this is necessary to provide access to files already hosted on Parse.
• filesAdapter - The default behavior (GridStore) can be changed by creating an adapter class (see FilesAdapter.js).
• maxUploadSize - Max file size for uploads. Defaults to 20mb.
• databaseAdapter (unfinished) - The backing store can be changed by creating an adapter class (see DatabaseAdapter.js).
• loggerAdapter - The default behavior/transport (File) can be changed by creating an adapter class (see LoggerAdapter.js).
• enableAnonymousUsers - Set to false to disable anonymous users. Defaults to true.
• allowClientClassCreation - Set to false to disable client class creation. Defaults to true.
• oauth - Used to configure support for 3rd party authentication.

Using environment variables to configure Parse Server

You may configure the Parse Server using environment variables:

PORT
PARSE_SERVER_APPLICATION_ID
PARSE_SERVER_MASTER_KEY
PARSE_SERVER_DATABASE_URI
PARSE_SERVER_URL
PARSE_SERVER_CLOUD_CODE_MAIN

The default port is 1337, to use a different port set the PORT environment variable:

$ PORT=8080 parse-server --appId=APPLICATION_ID --masterKey=MASTER_KEY

For the full list of configurable environment variables, run parse-server --help.

Configuring File Adapters

Parse Server allows developers to choose from several options when hosting files: the GridStoreAdapter, which backed by MongoDB; the S3Adapter, which is backed by Amazon S3; or the GCSAdapter, which is backed by Google Cloud Storage.

GridStoreAdapter is used by default and requires no setup, but if you're interested in using S3 or GCS, additional configuration information is available below.

Configuring S3Adapter

You can use the following environment variable setup to enable the S3 adapter:

S3_ACCESS_KEY
S3_SECRET_KEY
S3_BUCKET
S3_REGION
S3_BUCKET_PREFIX
S3_DIRECT_ACCESS

Configuring GCSAdapter

You can use the following environment variable setup to enable the GCS adapter:

GCP_PROJECT_ID
GCP_KEYFILE_PATH
GCS_BUCKET
GCS_BUCKET_PREFIX
GCS_DIRECT_ACCESS

Contributing

We really want Parse to be yours, to see it grow and thrive in the open source community. Please see the Contributing to Parse Server guide.