Getting Started

Parse Server is an open source backend that can be deployed to any infrastructure that can run Node.js. You can find the source on the GitHub repo.

• Parse Server uses MongoDB or PostgreSQL as a database.
• You can deploy and run Parse Server on your own infrastructure.
• You can develop and test your app locally using Node.

Prerequisites

• Node 8 or newer
• MongoDB version 3.6
• Python 2.x (For Windows users, 2.7.1 is the required version)
• For deployment, an infrastructure provider like Heroku or AWS

The fastest and easiest way to get started is to run MongoDB and Parse Server locally. Use the bootstrap script to set up Parse Server in the current directory.

$ sh <(curl -fsSL https://raw.githubusercontent.com/parse-community/parse-server/master/bootstrap.sh)
$ npm install -g mongodb-runner
$ mongodb-runner start
$ npm start

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.

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":123,"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": 123,
  "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": 123,
      "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 documentation for the SDK you will be using in your app.

Connect your app to Parse Server

Parse provides SDKs for all the major platforms. Refer to the rest of 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 Deploying Parse Server section to learn more about additional ways of running Parse Server.

Database

Parse Server let you use MongoDB or Postgres as a database.

The prefered database is MongoDB but Postgres is a great option if you’re starting a new project and you expect to have a stable Schema.

MongoDB

If you have not used MongoDB before, we highly recommend familiarizing yourself with it first before proceeding.

The Mongo requirements for Parse Server are:

• MongoDB version 3.6
• An SSL connection is recommended (but not required).

If this is your first time setting up a MongoDB instance, we recommend a Database-as-a-Service (DBaaS) like MongoDB Atlas or ObjectRocket which provide fully managed MongoDB instances and can help you scale as needed.

When using MongoDB with your Parse app, you need to manage your indexes yourself. You will also need to size up your database as your data grows.

In order to allow for better scaling of your data layer, it is possible to direct queries to a mongodb secondary for read operations. See: Mongo Read Preference.

Postgres

The Postgres requirements for Parse Server are:

• Postgres version 9.5
• PostGIS extensions 2.3

The postgres database adapter will be automatically loaded when you pass a valid postgres URL, for example: postgres://localhost:5432. The available configuration options through the URL are:

postgres://localhost:5432/db?ssl=boolean&rejectUnauthorized=boolean&ca=/path/to/file&pfx=/path/to/file&cert=/path/to/file&key=/path/to/file&passphrase=string&secureOptions=number&client_encoding=string&application_name=string&fallback_application_name=string&max=number&query_timeout=idleTimeoutMillis=number&poolSize=number&binary=boolean&keepAlive=boolean

When using Postgres with your Parse app, you need to manage your indexes yourself.

Details about the configuration options can be found on pg-promise. Some useful combinations are below:

• SSL with verification - postgres://localhost:5432/db?ca=/path/to/file
• SSL with no verification - postgres://localhost:5432/db?ssl=true&rejectUnauthorized=false

Caveats

• You will need to configure a file adapter in order to store files.
• Join tables are resolved in memory, there is no performance improvements using Postgres over MongoDB for relations or pointers.
• Mutating the schema implies running ALTER TABLE, therefore we recommend you setup your schema when your tables are not full.

• The postgres URL for 4.2.0 and below only supports the following configuration options:

    postgres://localhost:5432/db?ssl=boolean&client_encoding=string&application_name=string&fallback_application_name=string&poolSize=number&binary=boolean&keepAlive=boolean
  

Usage

Parse Server is meant to be mounted on an Express app. Express is a web framework for Node.js. The fastest way to get started is to clone the Parse Server repo, which at its root contains a sample Express app with the Parse API mounted.

The constructor returns an API object that conforms to an Express Middleware. This object provides the REST endpoints for a Parse app. Create an instance like so:

var api = new ParseServer({
  databaseURI: 'mongodb://your.mongo.uri',
  cloud: './cloud/main.js',
  appId: 'myAppId',
  fileKey: 'myFileKey',
  masterKey: 'mySecretMasterKey',
  push: { ... }, // See the Push wiki page
  filesAdapter: ...,
});

The parameters are as follows:

• databaseURI: Connection string URI for your MongoDB.
• cloud: Path to your app’s Cloud Code.
• appId: A unique identifier for your app.
• fileKey: A key that specifies a prefix used for file storage. For migrated apps, this is necessary to provide access to files already hosted on Parse.
• masterKey: A key that overrides all permissions. Keep this secret.
• clientKey: The client key for your app. (optional)
• restAPIKey: The REST API key for your app. (optional)
• javascriptKey: The JavaScript key for your app. (optional)
• dotNetKey: The .NET key for your app. (optional)
• push: An object containing push configuration. See Push
• filesAdapter: An object that implements the FilesAdapter interface. For example, the S3 files adapter
• auth: Configure support for 3rd party authentication.
• maxUploadSize: Maximum file upload size. Make sure your server does not restrict max request body size (e.g. nginx.conf client_max_body_size 100m;)

The Parse Server object was built to be passed directly into app.use, which will mount the Parse API at a specified path in your Express app:

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

var app = express();
var api = new ParseServer({ ... });

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

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

And with that, you will have a Parse Server running on port 1337, serving the Parse API at /parse.

Keys

Parse Server does not require the use of client-side keys. This includes the client key, JavaScript key, .NET key, and REST API key. The Application ID is sufficient to secure your app.

However, you have the option to specify any of these four keys upon initialization. Upon doing so, Parse Server will enforce that any clients passing a key matches. The behavior is consistent with hosted Parse.

Read-Only masterKey

Starting parse-server 2.6.5, it is possible to specify a readOnlyMasterKey. When using this key instead of the masterKey, the server will perform all read operations as if they were executing with the masterKey but will fail to execute any write operation.

This key is especially powerful when used with parse-dashboard. Please refer to Parse Dashboard’s documentation for more information.

Using Parse SDKs with Parse Server

To use a Parse SDK with Parse Server, change the server URL to your Parse API URL. For example, if you have Parse Server running locally mounted at /parse:

iOS / OS X / watchOS / tvOS

Swift

let configuration = ParseClientConfiguration {
    $0.applicationId = "YOUR_APP_ID"
    $0.clientKey = ""
    $0.server = "http://localhost:1337/parse"
}
Parse.initialize(with: configuration)

Objective-C

[Parse initializeWithConfiguration:[ParseClientConfiguration configurationWithBlock:^(id<ParseMutableClientConfiguration> configuration) {
   configuration.applicationId = @"YOUR_APP_ID";
   configuration.clientKey = @"";
   configuration.server = @"http://localhost:1337/parse";
}]];

Android

Parse.initialize(new Parse.Configuration.Builder(myContext)
    .applicationId("YOUR_APP_ID")
    .server("http://localhost:1337/parse/")
    ...
    .build()
);

JavaScript

Parse.initialize("YOUR_APP_ID");
Parse.serverURL = 'http://localhost:1337/parse'

.NET

ParseClient.initialize(new ParseClient.Configuration {
    ApplicationId = "YOUR_APP_ID",
    Server = "http://localhost:1337/parse/"
});

PHP

ParseClient::initialize('YOUR_APP_ID', 'YOUR_CLIENT_KEY', 'YOUR_MASTER_KEY');
ParseClient::setServerURL('http://localhost:1337', 'parse'); // server url & mount path passed separately

Deploying Parse Server

The fastest and easiest way to start using Parse Server is to run MongoDB and Parse Server locally. Once you have a better understanding of how the project works, read on to learn how to deploy Parse Server to major infrastructure providers. If your provider is not listed here, please take a look at the list of articles from the community as someone may have already written a guide for it.

Deploying to Heroku and MongoDB Atlas

Heroku and MongoDB Atlas provide an easy way to deploy Parse Server, especially if you’re new to managing your own backend infrastructure.

Here are the steps:

1. Create a repo for your Express app with the Parse Server middleware mounted (you can use our sample project, or start your own).
2. Create a Heroku account (if you don’t have one already) and use the Heroku Toolbelt to log in and prepare a new app in the same directory as your Express app. Take a look at Heroku’s Getting Started with Node.js guide for more details.
3. Set up your MongoDB database:
   1. Sign up for a MongoDB Atlas account.
   2. Create a New Project.
   3. Open the page Database Access and create a new database user with username and password. Remember these user credentials, you will need them later to connect Parse Server to the database. As user privileges choose Read and write to any database, you can change these privileges later on and make them more restrictive according to your needs.
   4. Open the page Clusters and create a new cluster.
   5. On the cluster details page, click on the tab Collections and create a new database.
   6. On the cluster details page, click on the tab Command Line Tools, click on Connect Instructions and choose Connect your application.
   7. Copy the database connection string. Replace the placeholders in the connection string with the username and password of the user you created earlier and the database name.
4. Use heroku config and note the URI provided by Atlas under the var MONGOLAB_URI
5. Copy this URI and set it as a new config variable: heroku config:set DATABASE_URI=mongodb://...
6. Deploy it: git push heroku master

You may also refer to the Heroku Dev Center article on Deploying a Parse Server to Heroku.

Deploying to Glitch and mLab

Before you start, you’ll need:

• mLab account (for free MongoDB)

Step 1: Creating your database on mLab

mLab provides a Database-as-a-Service for MongoDB. They include a free tier for small sandbox databases. Create an account on mLab and then use the Single-node, Sandbox plan to get a (free) database up and running. Within the mLab wizard, you’ll need to be sure to create a user that has access to connect to the new database. Upon completion, you should be able to construct a Mongo DB connection string like the following:

mongodb://yourusername:[email protected]:yourdatabaseport/yourdatabasename

Step 2: Running parse-server-example on Glitch

Glitch provides an easy way to instantly create and deploy Node.js applications for free. We will use it to run the parse-server-example application.

To get the example server up and running for quick testing, you can simply click the button below:

Now that the import is complete, we’ll need to make two small changes to the 🗝️.env file, which stores private environment variables.

It should look like the following:

# Environment Config

# store your secrets and config variables in here
# only invited collaborators will be able to see your .env values

# reference these in your code with process.env.SECRET

SECRET=
MADE_WITH=

# note: .env is a shell file so there can't be spaces around =
APP_ID=myAppId
MASTER_KEY=your_master_key_here
DATABASE_URI=your_mlab_database_uri_here
SERVER_URL=https://project-name.glitch.me/parse
PARSE_SERVER_LOGS=/tmp

First, change the DATABASE_URI value to your mLab connection string from step 1.

Next, change the project-name portion of the SERVER_URL value to the name of the project that was created. So, if clicking the button creates electric-dinner.glitch.me, your SERVER_URL value would be https://electric-dinner.glitch.me/parse.

You can delete the SECRET and MADE_WITH lines, but there’s no harm in leaving them there.

It is important, for this tutorial, to leave the APP_ID as myAppId as the “test” page hard-codes that and expects that value.

If you’d like to keep this project, create an account on Glitch. Projects created as an anonymous user expire after five days. You can read more about the technical restrictions on free Glitch projects here.

Step 3: Testing

Once you’re finished making your changes to your 🗝️.env file, Glitch will automatically build and deploy your application. If you use the Logs feature within Glitch (click on Tools → Logs), you should see this when your app is deployed:

parse-server-example running on port 3000.

You should then be able to use the “Show” button to launch the application in the browser and get to a page that urges you to star the parse-server GitHub repository. To access the test harness page, add a trailing /test to your URL. This should take you to a page that will allow you to exercise a few parts of the Parse Server Javascript SDK and create a dummy collection and record in your MongoDB. If you’re able to complete steps one through three on this test page, Parse Server is up and running. Optionally, you can go back to mLab.com and take a look at the data that was stored by the test harness to get a feel for how Parse Server stores data in MongoDB.

Deploying on Back4App

Back4App provides an easy way to deploy and host your Parse Server Apps.

Here are the steps:

1. Create a free Back4App Account.
2. Create a new Parse App.
3. Go to your App Core Settings Menu and check your App Keys and Database URI.

If you need to migrate your local Parse Server to Back4App you can follow these guidelines.

Push Notifications

Parse Server provides basic push notification functionality for iOS, macOS, tvOS and Android. With this feature, you can:

• Target installations by platform
• Target installations by a ParseQuery
• Send push notifications to Android devices through Firebase Cloud Messaging (FCM)
• Send push notifications to iOS, tvOS and macOS devices through Apple Push Notification Service (APNS)
• Use most of the sending options

However, there are a few caveats:

• Does not support super high throughput since it does not employ a job queue system
• Client push is not supported. You can only use masterKey to send push notifications
• Delivery reports are not supported
• Scheduled push is not supported

API

We support most of the sending options. Check the detailed doc here. Parse Server supports the following:

• channels to target installations by channels
• where to target installations by ParseQuery
• priority under data for iOS push priority
• push_type under data for iOS push type
• alert under data for notification message
• number badge under data for iOS badge number
• sound under data for iOS sound
• content-available under data for iOS background job
• category under data for iOS category
• title under data for Android notification title
• uri under data for Android notification launched URI
• custom data under data for ios and Android
• Increment badge under data for iOS and Android badge number

Here is the list of sending options we do not support yet:

• push_time for scheduled push

Push Notifications Quick Start

1. Prepare APNS and FCM Credentials

You will need to obtain some credentials from FCM and APNS in order to send push notifications.

APNS (iOS)

If you are setting up push notifications on iOS, tvOS or macOS for the first time, we recommend you visit the raywenderlich.com’s Push Notifications tutorial or appcoda.com’s iOS Push tutorial to help you obtain a production Apple Push Certificate. Parse Server supports the PFX (.p12) file exported from Keychain Access. Parse Server also supports the push certificate and key in .pem format. Token-based authentication instead of a certificate is supported as well.

FCM (Android)

To get your FCM API key, go to the Firebase console and navigate to the project. Navigate to the settings of the project, and within the “Cloud Messaging” tab, you will find it, labeled “Server key”

2. Configure Parse Server

When initializing Parse Server, you should pass an additional push configuration. For example

var server = new ParseServer({
  databaseURI: '...',
  cloud: '...',
  appId: '...',
  masterKey: '...',
  push: {
    android: {
      apiKey: '...'
    },
    ios: {
      pfx: '/file/path/to/XXX.p12',
      passphrase: '', // optional password to your p12/PFX
      bundleId: '',
      production: false
    }
  }
});

The configuration format is

push: {
  android: {
    apiKey: '' // The Server API Key of FCM
  },
  ios: {
    pfx: '', // The filename of private key and certificate in PFX or PKCS12 format from disk  
    passphrase: '', // optional password to your p12
    cert: '', // If not using the .p12 format, the path to the certificate PEM to load from disk
    key: '', // If not using the .p12 format, the path to the private key PEM to load from disk
    bundleId: '', // The bundle identifier associated with your app
    production: false // Specifies which APNS environment to connect to: Production (if true) or Sandbox
  }
}

For iOS, if you would like to use token-based authentication instead of certificates, you should use the following configuration format

push: {
  ios: {
    token: {
      key: '/file/path/to/AuthKey_XXXXXXXXXX.p8',
      keyId: "XXXXXXXXXX",
      teamId: "YYYYYYYYYY" // The Team ID for your developer account
    },
    topic: 'com.domain.appname', // The bundle identifier associated with your app
    production: false
  }
}

If you would like to support both the dev and prod certificates, you can provide an array of configurations like

push: {
  ios: [
    {
      pfx: '', // Dev PFX or P12
      bundleId: '',
      production: false // Dev
    },
    {
      pfx: '', // Prod PFX or P12
      bundleId: '',  
      production: true // Prod
    }
  ],
  tvos: [
    // ...
  ],
  osx: [
    // ...
  ]
}

The configuration for macOS and tvOS works exactly as for iOS. Just add an additional configuration for each plattform under the appropriate key. Please note the key for macOS is osx and for tvOS is tvos. If you need to support both the dev and prod certificates, you can do that for all Apple plattforms like described above.

var server = new ParseServer({
  databaseURI: '...',
  cloud: '...',
  appId: '...',
  masterKey: '...',
  push: {
    android: {
      apiKey: '...'
    },
    ios: {
      pfx: '/file/path/to/XXX.p12',
      passphrase: '', // optional password to your p12/PFX
      bundleId: '',
      production: false
    },
    osx: {
      pfx: '/file/path/to/XXX.p12',
      passphrase: '', // optional password to your p12/PFX
      bundleId: '',
      production: false
    },
    tvos: {
      pfx: '/file/path/to/XXX.p12',
      passphrase: '', // optional password to your p12/PFX
      bundleId: '',
      production: false
    }
  }
});

If you have a list of certificates, Parse Server’s strategy on choosing them is trying to match installations’ appIdentifier with bundleId first. If it can find some valid certificates, it will use those certificates to establish the connection to APNS and send notifications. If it can not find, it will try to send the notifications with all certificates. Prod certificates first, then dev certificates.

3. Configure Client Apps

Configure an app which connects to Parse Server. We have provided a detailed list of steps to configure your iOS and Android clients.

4. Send Push Notifications

Currently Parse Server only supports sending push notifications by your masterKey. The easiest way to do that is to curl:

curl -X POST \
  -H "X-Parse-Application-Id: you_app_id" \
  -H "X-Parse-Master-Key: your_master_key" \
  -H "Content-Type: application/json" \
  -d '{
        "where": {
          "deviceType": {
            "$in": [
              "ios",
              "android"
            ]
          }
        },
        "data": {
          "title": "The Shining",
          "alert": "All work and no play makes Jack a dull boy."
        }
      }'\   http://your_server_address/parse/push

Push notifications can also be sent from cloud code:

// With promises
Parse.Push.send({
  where: { ... },
  data: { ... }
}, { useMasterKey: true })
.then(function() {
  // Push sent!
}, function(error) {
  // There was a problem :(
});

// With Legacy Backbone callbacks
Parse.Push.send({
  where: query,
  data: {
    alert: 'Test',
    badge: 1,
    sound: 'default'
  }
}, {
  useMasterKey: true,
  success: function() {
    // Push sent!
  },
  error: function(error) {
    // There was a problem :(
  }
});

After sending this to your Parse Server, you should see the push notifications show up on your devices.

Note: The iOS simulator cannot receive push notifications. You must run iOS apps on an iOS device.

In your Parse Server logs, you can see something similar to

// FCM request and response
{"request":{"params":{"priority":"normal","data":{"time":"2016-02-10T03:21:59.065Z","push_id":"NTDgWw7kp8","data":"{\"alert\":\"All work and no play makes Jack a dull boy.\"}"}}},"response":{"multicast_id":5318039027588186000,"success":1,"failure":0,"canonical_ids":0,"results":[{"registration_id":"APA91bEdLpZnXT76vpkvkD7uWXEAgfrZgkiH_ybkzXqhaNcRw1KHOY0s9GUKNgneGxe2PqJ5Swk1-Vf852kpHAP0Mhoj5wd1MVXpRsRr_3KTQo_dkNd_5wcQ__yWnWLxbeM3kg_JziJK","message_id":"0:1455074519347821%df0f8ea7f9fd7ecd"}]}}

APNS Connected
APNS Notification transmitted to:7a7d2864598e1f65e6e02135245b7daf8ea510514e6376f072dc29d53facaa41

These logs mean that the FCM and APNS connections are working.

Push Adapter

Parse Server provides a PushAdapter which abstracts the way we actually send push notifications. The default implementation is ParsePushAdapter, which uses FCM for Android push and APNS for iOS push. However, if you want to use other push providers, you can implement your own PushAdapter. Your adapter needs to implement send(data, installations), which is used for sending data to the installations. You can use ParsePushAdapter as a reference. After you implement your PushAdapter, you can pass that instance to Parse Server like this

var server = new ParseServer({
  databaseURI: '...',
  cloud: '...',
  appId: '...',
  masterKey: '...',
  push: {
    adapter: your_adapter
  }
});

By doing this, after Parse Server decodes the push API request and runs the installation query, your PushAdapter’s send(data, installations) will be called and is responsible for sending the notifications. If you provide your custom PushAdapter, the default ParsePushAdapter will be ignored.

Future Improvements

The current solution provides a good starting point for push notifications. We have a lot of ideas to improve the feature:

• Support more platforms
• Support more sending options
• Support more push providers
• Support scheduled pushes
• Support delivery report and error handling
• Support job queue and benchmarking

If you’re interested in any of these features, don’t hesitate to jump in and send a PR to the repo. We would love to work with you!

Notes

Silent Notifications

If you are seeing situations where silent notifications are failing to deliver, please ensure that your payload is setting the content-available attribute to Int(1) (or just 1 as in javascript) and not “1”. This value will be explicitly checked.

When sending a push notification to APNs you also have to set push_type to background for delivering silent notifications to devices running iOS 13 and later, or watchOS 6 or later.

PPNS

• PPNS Protocol Specification (for Parse IoT devices)

Configuring your clients to receive Push Notifications

The following will guide you through the necessary steps to configure your iOS and Android client apps to receive push notifications from Parse Server. If you haven’t yet, you will first need to prepare your APNS and FCM credentials as documented in Step 1 of the Push Notifications Quick Start.

iOS Apps

Register Device for Push Notifications

Open up your AppDelegate.swift, AppDelegate.m, or AppDelegate.cs file and make your app register for remote notifications by adding the following in your application:didFinishLaunchingWithOptions: function:

// Swift
let types: UIUserNotificationType = [.Alert, .Badge, .Sound]
let settings = UIUserNotificationSettings(forTypes: types, categories: nil)
application.registerUserNotificationSettings(settings)
application.registerForRemoteNotifications()

// Objective-C
UIUserNotificationType userNotificationTypes = (UIUserNotificationTypeAlert |
                                                UIUserNotificationTypeBadge |
                                                UIUserNotificationTypeSound);
UIUserNotificationSettings *settings = [UIUserNotificationSettings settingsForTypes:userNotificationTypes
                                                                         categories:nil];
[application registerUserNotificationSettings:settings];
[application registerForRemoteNotifications];

// Xamarin
UIUserNotificationType notificationTypes = (UIUserNotificationType.Alert |
                                            UIUserNotificationType.Badge |
                                            UIUserNotificationType.Sound);
var settings = UIUserNotificationSettings.GetSettingsForTypes(notificationTypes,
                                                              new NSSet(new string[] { }));
UIApplication.SharedApplication.RegisterUserNotificationSettings(settings);
UIApplication.SharedApplication.RegisterForRemoteNotifications();

// Handle Push Notifications
ParsePush.ParsePushNotificationReceived += (object sender, ParsePushNotificationEventArgs args) => {
  // Process Push Notification payload here.
};

Store the device token and handle the UI for notifications by adding the following to your main app delegate:

// Swift
func application(application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: NSData) {
    let installation = PFInstallation.currentInstallation()
    installation.setDeviceTokenFromData(deviceToken)
    installation.saveInBackground()
}

func application(application: UIApplication, didFailToRegisterForRemoteNotificationsWithError error: NSError) {
    if error.code == 3010 {
        print("Push notifications are not supported in the iOS Simulator.")
    } else {
        print("application:didFailToRegisterForRemoteNotificationsWithError: %@", error)
    }
}

func application(application: UIApplication, didReceiveRemoteNotification userInfo: [NSObject : AnyObject]) {
    PFPush.handlePush(userInfo)
}

// Objective-C
- (void)application:(UIApplication *)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken {
  // Store the deviceToken in the current installation and save it to Parse.
  PFInstallation *currentInstallation = [PFInstallation currentInstallation];
  [currentInstallation setDeviceTokenFromData:deviceToken];
  [currentInstallation saveInBackground];
}

- (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo {
  [PFPush handlePush:userInfo];
}

// Xamarin
public override void DidRegisterUserNotificationSettings(UIApplication application,
    UIUserNotificationSettings notificationSettings) {
  application.RegisterForRemoteNotifications();
}

public override void RegisteredForRemoteNotifications(UIApplication application,
    NSData deviceToken) {
  ParseInstallation installation = ParseInstallation.CurrentInstallation;
  installation.SetDeviceTokenFromData(deviceToken);

  installation.SaveAsync();
}

public override void ReceivedRemoteNotification(UIApplication application,
    NSDictionary userInfo) {
  // We need this to fire userInfo into ParsePushNotificationReceived.
  ParsePush.HandlePush(userInfo);
}

Compile and run!

If you configured your app correctly, installation objects will automatically be saved to Parse Server when you run your app. You can run this curl command to verify:

curl -X GET \
  -H "X-Parse-Application-Id: YOUR_APP_ID" \
  -H "X-Parse-Master-Key: YOUR_MASTER_KEY" \
  http://your_parse_server:1337/parse/installations

Proceed to Step 4.

Android apps

FCM Push Setup

Add this in your root build.gradle file (not your module build.gradle file):

allprojects {
	repositories {
		...
		maven { url "https://jitpack.io" }
	}
}

Then, add the library to your project build.gradle

dependencies {
    implementation "com.github.parse-community.Parse-SDK-Android:fcm:latest.version.here"
}

with the latest version being

Then, follow Google’s docs for setting up an Firebase app. Although the steps are different for setting up FCM with Parse, it is also a good idea to read over the Firebase FCM Setup. You will need to do the following:

• Add app to Firebase console.
• Add the com.google.gms.google-services Gradle plugin (see setup guide)
• Download and add google-services.json to your app/ dir.
• Remove GcmBroadcastReceiver, PushService, com.parse.push.gcm_sender_id if upgrading from GCM.
• Added ParseFirebaseInstanceIdService and ParseFirebaseMessagingService to your AndroidManifest.xml file (as shown below):

You will need to register some services in your manifest, specifically:

<service
    android:name="com.parse.fcm.ParseFirebaseInstanceIdService"
    android:exported="true">
    <intent-filter>
        <action android:name="com.google.firebase.INSTANCE_ID_EVENT" />
    </intent-filter>
</service>

Additional, you will register:

<service
    android:name="com.parse.fcm.ParseFirebaseMessagingService">
    <intent-filter>
        <action android:name="com.google.firebase.MESSAGING_EVENT"/>
    </intent-filter>
</service>

After these services are registered in the Manifest, you then need to register the push broadcast receiver:

<receiver
    android:name="com.parse.ParsePushBroadcastReceiver"
    android:exported="false">
    <intent-filter>
        <action android:name="com.parse.push.intent.RECEIVE" />
        <action android:name="com.parse.push.intent.DELETE" />
        <action android:name="com.parse.push.intent.OPEN" />
    </intent-filter>
</receiver>

Custom Notifications

If you need to customize the notification that is sent out from a push, you can do so by extending ParsePushBroadcastReceiver with your own class and registering it instead in the Manifest.

Register Device for Push Notifications

Create an Installation object by adding the following to the onCreate method of your Application class:

// Native: Application.java
public void onCreate() {
  // ...
  ParseInstallation.getCurrentInstallation().saveInBackground();
}

// Xamarin: Application.cs

// IMPORTANT: Change "parsexamarinpushsample" to match your namespace.
[Application(Name = "parsexamarinpushsample.ParseApplication")]
class ParseApplication : Application {
  // ...

  public override void OnCreate() {
    base.OnCreate();

    // ...

    ParsePush.ParsePushNotificationReceived += ParsePush.DefaultParsePushNotificationReceivedHandler;
  }
}

Compile and run!

If you configured your app correctly, installation objects will automatically be saved to Parse Server when you run your app. You can run this curl command to verify:

curl -X GET \
  -H "X-Parse-Application-Id: YOUR_APP_ID" \
  -H "X-Parse-Master-Key: YOUR_MASTER_KEY" \
  http://your_parse_server:1337/parse/installations

Proceed to Step 4.

Note that GCM push support is deprecated and FCM should be used instead, but instructions for GCM setup can be found here

Class Level Permissions

Class level permissions are a security feature from that allows one to restrict access on a broader way than the ACL based permissions.

requiresAuthentication

If you want to restrict access to a full class to only authenticated users, you can use the requiresAuthentication class level permission. For example, you want to allow your authenticated users to find and get objects from your application and your admin users to have all privileges, you would set the CLP:

// PUT http://localhost:1337/schemas/:className
// Set the X-Parse-Application-Id and X-Parse-Master-Key header
// body:
{
  classLevelPermissions:
  {
    "find": {
      "requiresAuthentication": true,
      "role:admin": true
    },
    "get": {
      "requiresAuthentication": true,
      "role:admin": true
    },
    "create": { "role:admin": true },
    "update": { "role:admin": true },
    "delete": { "role:admin": true },
  }
}

Note that this is in no way securing your content. If you allow anyone to log in to your server, any client will be able to query this object.

Configuring File Adapters

Parse Server allows developers to choose from several options when hosting files:

• GridStoreAdapter, which is backed by MongoDB;
• S3Adapter, which is backed by Amazon S3; or
• GCSAdapter, which is backed by Google Cloud Storage; or
• FSAdapter, local file storage

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

When using files on Parse, you will need to use the publicServerURL option in your Parse Server config. This is the URL that files will be accessed from, so it should be a URL that resolves to your Parse Server. Make sure to include your mount point in this URL.

When using Postgres, you will need to configure S3Adapter, GCSAdapter, or FSAdapter for file support. The GridStoreAdapter does not work with Postgres.

Configuring GridStoreAdapter

If you are using Mongo and don’t need file encryption, there are no additional steps needed to use the GridStoreAdapter. If you’d like to enable file encryption follow these instructions to configure Parse Server to use GridStoreAdapter with file encryption.

Set up file encryption

File encryption is available in parse-server 4.4.0+. The GridStoreAdapter can encrypt files at rest in Mongo using AES256-GCM, allowing the adapter to detect if files are tampered with.

To use, simply do any of the following:

• Use the environment variable PARSE_SERVER_ENCRYPTION_KEY
• Pass in –encryptionKey in the command line when starting your server
• Initialize ParseServer with encryptionKey="Your file encryptionKey".

An example starting your Parse Server in index.js is below:

const api = new ParseServer({
  databaseURI: databaseUri || 'mongodb://localhost:27017/dev',
  cloud: process.env.PARSE_SERVER_CLOUD || __dirname + '/cloud/main.js',
  appId: process.env.PARSE_SERVER_APPLICATION_ID || 'myAppId',
  masterKey: process.env.PARSE_SERVER_MASTER_KEY || '', 
  encryptionKey: process.env.PARSE_SERVER_ENCRYPTION_KEY, //Add your file key here. Keep it secret
  ...
});

Be sure not to lose your key or change it after encrypting files.

Enabling encryption on a server that already has unencrypted files

When this is the case, it is recommended to start up a development parse-server (or a separate process from your main process) that has the same configuration as your production server. On the development server, initialize the file adapter as above with the new key and do the following after initialization in your index.js:

//You probably want to back up your unencrypted files before doing this.
//This can take awhile depending on how many files and how large they are. It will attempt to rotate the key of all files in your filesSubDirectory
const {rotated, notRotated} =  await api.filesAdapter.rotateEncryptionKey();
console.log('Files rotated to newKey: ' + rotated);
console.log('Files that couldn't be rotated to newKey: ' + notRotated);

Rotating your encryption key

Periodically you may want to rotate your encryptionKey for security reasons. When this is the case, it is recommended to start up a development parse-server (or a separate process from your main process) that has the same configuration as your production server. On the development server, initialize the file adapter with the new key and do the following in your index.js (you will need your oldKey):

//This can take awhile depending on how many files and how large they are. It will attempt to rotate the key of all files in your filesSubDirectory
const {rotated, notRotated} =  await api.filesAdapter.rotateEncryptionKey({oldKey: oldKey});
console.log('Files rotated to newKey: ' + rotated);
console.log('Files that couldn't be rotated to newKey: ' + notRotated);

Removing file encryption

When this is the case, it is recommended to start up a development parse-server (or a separate process from your main process) that has the same configuration as your production server. Different from the previous examples, don’t initialize your fileAdapter with a encryptionKey. Pass in your oldKey to rotateEncryptionKey().

const api = new ParseServer({
  databaseURI: databaseUri || 'mongodb://localhost:27017/dev',
  cloud: process.env.PARSE_SERVER_CLOUD || __dirname + '/cloud/main.js',
  appId: process.env.PARSE_SERVER_APPLICATION_ID || 'myAppId',
  masterKey: process.env.PARSE_SERVER_MASTER_KEY || '', 
  //No encryptionKey here
  ...
});

//This can take awhile depending on how many files and how larger they are. It will attempt to rotate the key of all files in your filesSubDirectory
//It is not recommended to do this on the production server, deploy a development server to complete the process.
const {rotated, notRotated} =  await api.filesAdapter.rotateEncryptionKey({oldKey: oldKey});
console.log('Files rotated to unencrypted with noKey: ' + rotated);
console.log('Files that couldn't be rotated to unencrypted with noKey: ' + notRotated);

Rotating the key for a subset of files

This is useful if for some reason there were errors and some of the files weren’t rotated and returned in notRotated. The process is the same as the previous examples, but pass in your oldKey along with the array of fileNames to rotateEncryptionKey().

//This can take awhile depending on how many files and how large they are. It will attempt to rotate the key of all files in your filesSubDirectory
const {rotated, notRotated} =  await api.filesAdapter.rotateEncryptionKey({oldKey: oldKey, fileNames: ["fileName1.png","fileName2.png"]});
console.log('Files rotated to newKey: ' + rotated);
console.log('Files that couldn't be rotated to newKey: ' + notRotated);

Configuring S3Adapter

If you’d like to use Amazon S3, follow these instructions to configure Parse Server to use S3Adapter.

Set up your bucket and permissions

First you will create a bucket in S3 to hold these files.

1. Log into your AWS account or create a new one.
2. Head to the S3 service and choose Create Bucket
3. 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.
4. Now head to the Identity and Access Management (IAM) service.
5. Click the Users tab, then Create New User.
6. Fill out at least one user name and make sure Generate an access key for each user is selected before clicking Create.
7. Make sure to Download Credentials on the next screen.
8. Now select the Policies tab, then Create Policy.
9. Select Create Your Own Policy, fill out a Policy Name.

10. Copy the following config in Policy Document, changing BUCKET_NAME for the name of the bucket you created earlier. (note: this is a little more permissive than Parse Server needs, but it works for now)

    {
        "Version": "2012-10-17",
        "Statement": [
            {
                "Effect": "Allow",
                "Action": [
                    "s3:*"
                ],
                "Resource": [
                    "arn:aws:s3:::BUCKET_NAME",
                    "arn:aws:s3:::BUCKET_NAME/*"
                ]
            }
         ]
     }
    

11. Make sure to Validate Policy first, then click Create Policy.
12. Go back to the Users tab and select the user you created earlier.
13. In Permissions, select Attach Policy and find the policy we just created to attach it.

Configuration options

Writing to your Amazon S3 bucket from Parse Server is as simple as configuring and using the S3 files adapter.

Using environment variables

If you’re running a standalone Parse Server, you can use the following environment variables to configure the S3 adapter:

Passing as options

If you’re using Node.js/Express:

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

var api = new ParseServer({
  databaseURI: databaseUri || 'mongodb://localhost:27017/dev',
  appId: process.env.APP_ID || 'APPLICATION_ID',
  masterKey: process.env.MASTER_KEY || 'MASTER_KEY',
  ...
  filesAdapter: new S3Adapter(
    "S3_ACCESS_KEY",
    "S3_SECRET_KEY",
    "S3_BUCKET",
    {directAccess: true}
  ),
  ...
});

Don’t forget to change S3_ACCESS_KEY, S3_SECRET_KEY and S3_BUCKET to their correct value.

S3Adapter constructor options

new S3Adapter(accessKey, secretKey, bucket, options)

Configuring GCSAdapter

Unlike the S3 adapter, you must create a new Cloud Storage bucket, as this is not created automatically. See the Google Cloud guide on Authentication for more details.

To generate a private key in the Cloud Platform Console follow these instructions.

Installation

Starting 2.2.6, GCS Adapter is not provided by default by parse-server. To install run:

npm install --save parse-server-gcs-adapter

Configuration options

Writing to your Google Cloud Storage bucket from Parse Server is as simple as configuring and using the GCS files adapter.

Using environment variables

You can use Google Cloud Storage to host your static files by setting the following environment variables:

Passing as options

If you’re using Node.js/Express:

...
var GCSAdapter = require('parse-server-gcs-adapter');

var api = new ParseServer({
  databaseURI: databaseUri || 'mongodb://localhost:27017/dev',
  appId: process.env.APP_ID || 'APPLICATION_ID',
  masterKey: process.env.MASTER_KEY || 'MASTER_KEY',
  ...
  filesAdapter: new GCSAdapter(
    "GCP_PROJECT_ID",
    "GCP_KEYFILE_PATH",
    "GCS_BUCKET",
    {directAccess: true}
  ),
  ...
});

S3Adapter configuration for Digital Ocean Spaces

Spaces is an S3 equivalent prodivided by Digital Ocean. It’s use the same api as S3 so you can use it with the S3 Adapter. You just need to change the AWS Endpoint to point to your Spaces endpoint.

...
var S3Adapter = require('parse-server').S3Adapter;
var AWS = require("aws-sdk");

//Set Digital Ocean Spaces EndPoint
const spacesEndpoint = new AWS.Endpoint(process.env.SPACES_ENDPOINT);
//Define S3 options
var s3Options = {
  bucket: process.env.SPACES_BUCKET_NAME,
  baseUrl: process.env.SPACES_BASE_URL,
  region: process.env.SPACES_REGION,
  directAccess: true,
  globalCacheControl: "public, max-age=31536000",
  bucketPrefix: process.env.SPACES_BUCKET_PREFIX,
  s3overrides: {
    accessKeyId: process.env.SPACES_ACCESS_KEY,
    secretAccessKey: process.env.SPACES_SECRET_KEY,
    endpoint: spacesEndpoint
  }
};

var s3Adapter = new S3Adapter(s3Options);

var api = new ParseServer({
  databaseURI: databaseUri || 'mongodb://localhost:27017/dev',
  appId: process.env.APP_ID || 'APPLICATION_ID',
  masterKey: process.env.MASTER_KEY || 'MASTER_KEY',
  ...
  filesAdapter: s3Adapter
  ...
});

GCSAdapter constructor options

new GCSAdapter(projectId, keyfilePath, bucket, options)

Configuring FSAdapter

To use the FSAdapter, simply initialize your Parse Server in index.js by doing the following:

var FSFilesAdapter = require('@parse/fs-files-adapter');

var fsAdapter = new FSFilesAdapter({
  "filesSubDirectory": "my/files/folder" // optional, defaults to ./files
});

var api = new ParseServer({
	appId: 'my_app',
	masterKey: 'master_key',
	filesAdapter: fsAdapter
})

Using FSAdapter with multiple instances of Parse Server

When using parse-server-fs-adapter across multiple Parse Server instances it’s important to establish “centralization” of your file storage (this is the same premise as the other file adapters, you are sending/recieving files through a dedicated link). You can accomplish this at the file storage level by Samba mounting (or any other type of mounting) your storage to each of your parse-server instances, e.g if you are using Parse Server via docker (volume mount your SMB drive to - /Volumes/SMB-Drive/MyParseApp1/files:/parse-server/files). All Parse Server instances need to be able to read/write to the same storage in order for parse-server-fs-adapter to work properly with parse-server. If the file storage isn’t centralized, parse-server will have trouble locating files and you will get random behavior on client-side.

Set up file encryption

File encryption is available in parse-server-fs-adapter 1.1.0+. The FSAdapter can encrypt files at rest for local storage using AES256-GCM, allowing the adapter to detect if files are tampered with.

To use, simply do the same as above, but add a encryptionKey:

var FSFilesAdapter = require('@parse/fs-files-adapter');

var fsAdapter = new FSFilesAdapter({
  "filesSubDirectory": "my/files/folder", // optional, defaults to ./files
  "encryptionKey": "someKey" //mandatory if you want to encrypt files
});

var api = new ParseServer({
	appId: 'my_app',
	masterKey: 'master_key',
	filesAdapter: fsAdapter
})

Be sure not to lose your key or change it after encrypting files.

Enabling encryption on a server that already has unencrypted files

When this is the case, it is recommended to start up a development parse-server (or a separate process from your main process) that has the same configuration as your production server. On the development server, initialize the file adapter as above with the new key and do the following after initialization in your index.js:

//You probably want to back up your unencrypted files before doing this.
//This can take awhile depending on how many files and how large they are. It will attempt to rotate the key of all files in your filesSubDirectory
const {rotated, notRotated} =  await api.filesAdapter.rotateEncryptionKey();
console.log('Files rotated to newKey: ' + rotated);
console.log('Files that couldn't be rotated to newKey: ' + notRotated);

Rotating your encryption key

Periodically you may want to rotate your encryptionKey for security reasons. When this is the case, it is recommended to start up a development parse-server (or a separate process from your main process) that has the same configuration as your production server. On the development server, initialize the file adapter with the new key and do the following in your index.js (you will need your oldKey):

//This can take awhile depending on how many files and how large they are. It will attempt to rotate the key of all files in your filesSubDirectory
const {rotated, notRotated} =  await api.filesAdapter.rotateEncryptionKey({oldKey: oldKey});
console.log('Files rotated to newKey: ' + rotated);
console.log('Files that couldn't be rotated to newKey: ' + notRotated);

Removing file encryption

When this is the case, it is recommended to start up a development parse-server (or a separate process from your main process) that has the same configuration as your production server. Different from the previous examples, don’t initialize your fileAdapter with a encryptionKey. Pass in your oldKey to rotateEncryptionKey().

const api = new ParseServer({
  databaseURI: databaseUri || 'mongodb://localhost:27017/dev',
  cloud: process.env.PARSE_SERVER_CLOUD || __dirname + '/cloud/main.js',
  appId: process.env.PARSE_SERVER_APPLICATION_ID || 'myAppId',
  masterKey: process.env.PARSE_SERVER_MASTER_KEY || '', 
  filesAdapter: new FSFilesAdapter(), //No encryptionKey supplied
  ...
});

//This can take awhile depending on how many files and how larger they are. It will attempt to rotate the key of all files in your filesSubDirectory
//It is not recommended to do this on the production server, deploy a development server to complete the process.
const {rotated, notRotated} =  await api.filesAdapter.rotateEncryptionKey({oldKey: oldKey});
console.log('Files rotated to unencrypted with noKey: ' + rotated);
console.log('Files that couldn't be rotated to unencrypted with noKey: ' + notRotated);

Rotating the key for a subset of files

This is useful if for some reason there were errors and some of the files weren’t rotated and returned in notRotated. The process is the same as the previous examples, but pass in your oldKey along with the array of fileNames to rotateEncryptionKey().

//This can take awhile depending on how many files and how large they are. It will attempt to rotate the key of all files in your filesSubDirectory
const {rotated, notRotated} =  await api.filesAdapter.rotateEncryptionKey({oldKey: oldKey, fileNames: ["fileName1.png","fileName2.png"]});
console.log('Files rotated to newKey: ' + rotated);
console.log('Files that couldn't be rotated to newKey: ' + notRotated);

Configuring Cache Adapters

By default, parse-server provides an internal cache layer to speed up schema verifications, user, roles and sessions lookup.

In some cases, in distributed environment, you may want to use a distributed cache like Redis.

parse-server comes with an optional redis cache adapter.

Those cache adapters can be cleaned at anytime internally, you should not use them to cache data and you should let parse-server manage their data lifecycle.

RedisCacheAdapter

var RedisCacheAdapter = require('parse-server').RedisCacheAdapter;
var redisOptions = {url: 'YOUR REDIS URL HERE'}
var redisCache = new RedisCacheAdapter(redisOptions);

var api = new ParseServer({
  databaseURI: databaseUri || 'mongodb://localhost:27017/dev',
  appId: process.env.APP_ID || 'APPLICATION_ID',
  masterKey: process.env.MASTER_KEY || 'MASTER_KEY',
  ...
  cacheAdapter: redisCache,
  ...
});

The redisOptions are passed directly to the redis.createClient method. For more information refer to the redis.createClient documentation.

Note that at the moment, only passing a single argument is supported.

The cache adapter can flush the redis database at anytime. It is best to not use the same redis database for other services. A different redis database can be chosen by providing a different database number to redisOptions. By default redis has 16 databases (indexed from 0 to 15).

Live Queries

Parse.Query is one of the key concepts for Parse. It allows you to retrieve Parse.Objects by specifying some conditions, making it easy to build apps such as a dashboard, a todo list or even some strategy games. However, Parse.Query is based on a pull model, which is not suitable for apps that need real-time support.

Suppose you are building an app that allows multiple users to edit the same file at the same time. Parse.Query would not be an ideal tool since you can not know when to query from the server to get the updates.

To solve this problem, we introduce Parse LiveQuery. This tool allows you to subscribe to a Parse.Query you are interested in. Once subscribed, the server will notify clients whenever a Parse.Object that matches the Parse.Query is created or updated, in real-time.

Parse LiveQuery contains two parts, the LiveQuery server and the LiveQuery clients. In order to use live queries, you need to set up both of them.

Server Setup

The LiveQuery server should work with a Parse Server. The easiest way to setup the LiveQuery server is to make it run with the Parse Server in the same process. When you initialize the Parse Server, you need to define which Parse.Object classes you want to enable LiveQuery like this:

let api = new ParseServer({
  ...,
  liveQuery: {
    classNames: ['Test', 'TestAgain']
  }
});

After that, you need to initialize a LiveQuery server like this:

// Initialize a LiveQuery server instance, app is the express app of your Parse Server
let httpServer = require('http').createServer(app);
httpServer.listen(port);
var parseLiveQueryServer = ParseServer.createLiveQueryServer(httpServer);

The ws protocol URL of the LiveQuery server is the hostname and port which the httpServer is listening to. For example, if the httpServer is listening to localhost:8080, the ws protocol of the LiveQuery server is ws://localhost:8080/. We will allow you to customize the path of ws protocol URL of the LiveQuery server later, currently it is fixed and you can not set path.

Client Setup

We provide JavaScript, Android and iOS LiveQuery Clients for now. Lets use the JavaScript client as an example. In order to use LiveQuery, you need to initialize a Parse.Query object and subscribe to it.

let query = new Parse.Query('People');
query.equalTo('name', 'Mengyan');
let subscription = await query.subscribe();

After you get the subscription, you can use it to receive the updates of the related Parse.Object. For example, if someone creates a People object whose name field is Mengyan, then you can get the People object like this:

subscription.on('create', (people) => {
  console.log(people.get('name')); // This should output Mengyan
});

After that, if someone updates this People object like changing its score to 100, then you can get the People object like this:

subscription.on('update', (people) => {
  console.log(people.get('score')); // This should output 100
});

If you are done with the LiveQuery, you can simply unsubscribe the subscription to finish receiving events

subscription.unsubscribe();

Events

We support five types of event:

• create
• enter
• update
• leave
• delete

Further Reading

You can check the LiveQuery protocol specification to learn more about each event type.

For more details about the JavaScript LiveQuery Client SDK, check out the open source code and the Live Query section in the JavaScript Guide.

For the iOS LiveQuery Client SDK, check out the open source code.

LiveQuery Protocol

The LiveQuery Protocol is the key to the Parse LiveQuery. The clients and server communicate through WebSocket using this protocol. Clients can follow the protocol to connect to the LiveQuery server, subscribe/unsubscribe a Parse.Query and get updates from the LiveQuery server.

The LiveQuery protocol is a simple protocol that encapsulates messages in JSON strings and runs over a WebSocket connection. You can find the specification in the For the specification, check out the Parse Server wiki page.

LiveQuery Server

Configuring the server

The full configuration of the LiveQuery server should look like this:

{
  appId: 'myAppId',
  masterKey: 'myMasterKey',
  keyPairs: {
    "restAPIKey": "",
    "javascriptKey": "",
    "clientKey": "",
    "windowsKey": "",
    "masterKey": ""
  },
  serverURL: 'serverURL',
  websocketTimeout: 10 * 1000,
  cacheTimeout: 60 * 600 * 1000,
  logLevel: 'VERBOSE'
}

Options

• appId - Required. This string should match the appId in use by your Parse Server. If you deploy the LiveQuery server alongside Parse Server, the LiveQuery server will try to use the same appId.
• masterKey - Required. This string should match the masterKey in use by your Parse Server. If you deploy the LiveQuery server alongside Parse Server, the LiveQuery server will try to use the same masterKey.
• serverURL - Required. This string should match the serverURL in use by your Parse Server. If you deploy the LiveQuery server alongside Parse Server, the LiveQuery server will try to use the same serverURL.
• keyPairs - Optional. A JSON object that serves as a whitelist of keys. It is used for validating clients when they try to connect to the LiveQuery server. Check the following Security section and our protocol specification for details.
• websocketTimeout - Optional. Number of milliseconds between ping/pong frames. The WebSocket server sends ping/pong frames to the clients to keep the WebSocket alive. This value defines the interval of the ping/pong frame from the server to clients. Defaults to 10 * 1000 ms (10 s).
• cacheTimeout - Optional. Number in milliseconds. When clients provide the sessionToken to the LiveQuery server, the LiveQuery server will try to fetch its ParseUser’s objectId from parse server and store it in the cache. The value defines the duration of the cache. Check the following Security section and our protocol specification for details. Defaults to 30 * 24 * 60 * 60 * 1000 ms (~30 days).
• logLevel - Optional. This string defines the log level of the LiveQuery server. We support VERBOSE, INFO, ERROR, NONE. Defaults to INFO.

Basic Architecture

The LiveQuery server is a separate server from Parse Server. As shown in the picture, it mainly contains four components at the runtime.

• The Publisher. It is responsible for publishing the update of a Parse.Object. When a Parse.Object changes, it will publish a message to the subscribers. The message contains the original Parse.Object and the new Parse.Object. The Publisher is inside the Parse Server at the runtime.
• The Subscriber. It is responsible for receiving the messages which are sent from the Publisher. After it gets the messages, it can pass them to the LiveQuery component for processing.
• The WebSocketServer. It is responsible for maintaining the WebSocket connections with clients. It can pass the subscribe/unsubscribe messages from clients to the LiveQuery component. When the LiveQuery component finds a Parse.Object fulfills a Parse.Query, it will get the event message from LiveQuery component and send it to the clients.
• The LiveQuery. It is the key component of the LiveQuery Server. It maintains the subscription status of clients. After it gets the Parse.Object updates from the Subscriber, it can do the query matching and generate the event messages for clients.

Scalability

Based on your usage, different components of the LiveQuery server may become the bottleneck. If you app has high throughput, the Publisher/Subscriber may have problems. If you subscribe to many complex Parse.Querys, the LiveQuery component may cause issues. If you need to maintain lots of clients, the WebSocketServer may be the bottleneck. Thus, we highly recommend you to do the load testing for your app if you want to use LiveQuery server in production.

In general, our suggestion to make the LiveQuery server scalable is to separate the Parse Server with the LiveQuery server and add more LiveQuery server instances based on your need. To help you do this, we use Redis to implement a Publisher and Subscriber. If you want to use that, the only thing you need to do is to provide the Redis server address when you initialize the Parse Server and LiveQuery server like this:

let api = new ParseServer({
  ...,
  liveQuery: {
    classNames: ['Test', 'TestAgain'],
    redisURL: 'redis://localhost:6379'
  }
});

...

let httpServer = require('http').createServer(app);
httpServer.listen(port);
var parseLiveQueryServer = ParseServer.createLiveQueryServer(httpServer,  {
  ...,
  redisURL: 'redis://localhost:6379'
});

This redis database should be different from the redis database used for RedisCacheAdapter.

The architecture of the whole LiveQuery system after you use Redis should be like this:

For example, if you use Heroku to deploy your Live Query server, after you setup the Redis with the LiveQuery server, you can simply add more dynos to make your app more scalable like this:

Security with LiveQuery

The LiveQuery server provides two ways to secure your app. The first one is key matching. If you provide key pairs when you initialize the LiveQuery server, when clients try to connect to LiveQuery server, they have to provide the necessary key pairs. Otherwise, the connection will be refused.

The second one is ACL. For what is ACL, you can check the definition here. When clients try to connect and subscribe to the LiveQuery server, they can provide their sessionToken. If you give your Parse.Object proper ACL, when the LiveQuery server get the updates of the Parse.Object, it will try to match Parse.Object’s ACL with the sessionToken of clients or their subscriptions. The event will be only sent to clients whose sessionToken matches the Parse.Object’s ACL.

LiveQuery Clients

The JavaScript LiveQuery client is provided as part of the Parse JavaScript SDK as of version 1.8.0. A separate LiveQuery client library is available for iOS / OS X and Android.

• Parse JavaScript SDK
• Parse LiveQuery iOS / OS X
• Parse LiveQuery Android

LiveQuery With NGINX

Please refer to the NGINX documentation in order to allow a proper handling of the LiveQuery server that relies on web sockets

OAuth and 3rd Party Authentication

Parse Server supports 3rd party authentication with

• Apple
• Facebook
• Github
• Google
• Instagram
• Janrain Capture
• Janrain Engage
• Keycloak
• LDAP
• LinkedIn
• Meetup
• Microsoft Graph
• PhantAuth
• QQ
• Spotify
• Twitter
• vKontakte
• WeChat
• Weibo

Configuration options for these 3rd-party modules is done with the auth option passed to Parse Server:

{
  auth: {
   twitter: {
     consumer_key: "", // REQUIRED
     consumer_secret: "" // REQUIRED
   },
   facebook: {
     appIds: "FACEBOOK APP ID"
   }
  }
}

Supported 3rd party authentications

Below, you will find all expected payloads for logging in with a 3rd party auth.

Note, most of them don’t require a server configuration so you can use them directly, without particular server configuration.

Facebook authData

{
  "facebook": {
    "id": "user's Facebook id number as a string",
    "access_token": "an authorized Facebook access token for the user",
    "expiration_date": "token expiration date of the format: yyyy-MM-dd'T'HH:mm:ss.SSS'Z'"
  }
}

Learn more about Facebook login.

Twitter authData

{
  "twitter": {
    "id": "user's Twitter id number as a string",
    "consumer_key": "your application's consumer key",
    "consumer_secret": "your application's consumer secret",
    "auth_token": "an authorized Twitter token for the user with your application",
    "auth_token_secret": "the secret associated with the auth_token"
  }
}

The options passed to Parse server:

{
  auth: {
    twitter: {
     consumer_key: "", // REQUIRED
     consumer_secret: "" // REQUIRED
   },
  }
}

Learn more about Twitter login.

Anonymous user authData

{
  "anonymous": {
    "id": "random UUID with lowercase hexadecimal digits"
  }
}

Apple authData

As of Parse Server 3.5.0 you can use Sign In With Apple.

{
  "apple": {
    "id": "user",
    "token": "the identity token for the user"
  }
}

Using Apple Sign In on a iOS device will give you a ASAuthorizationAppleIDCredential.user string for the user identifier, which can be match the sub component of the JWT identity token. Using Apple Sign In through the Apple JS SDK or through the REST service will only give you the JWT identity token (id_token) which you’ll have to decompose to obtain the user identifier in its sub component. As an example you could use something like JSON.parse(atob(token.split(".")[1])).sub.

Configuring parse-server for Sign In with Apple

{
  auth: {
   apple: {
     client_id: "", // optional (for extra validation), use the Service ID from Apple.
   },
  }
}

Learn more about Sign In With Apple.

Github authData

{
  "github": {
    "id": "user's Github id (string)",
    "access_token": "an authorized Github access token for the user"
  }
}

Google authData

Google oauth supports validation of id_token’s and access_token’s.

{
  "google": {
    "id": "user's Google id (string)",
    "id_token": "an authorized Google id_token for the user (use when not using access_token)",
    "access_token": "an authorized Google access_token for the user (use when not using id_token)"
  }
}

Instagram authData

{
  "instagram": {
    "id": "user's Instagram id (string)",
    "access_token": "an authorized Instagram access token for the user",
    "apiURL": "an api url to make requests. Default: https://api.instagram.com/v1/"
  }
}

Keycloak authData

{
  "keycloak": {
    "access_token": "access token from keycloak JS client authentication",
    "id": "the id retrieved from client authentication in Keycloak",
    "roles": ["the roles retrieved from client authentication in Keycloak"],
    "groups": ["the groups retrieved from client authentication in Keycloak"]
  }
}

The authentication module will test if the authData is the same as the userinfo oauth call, by comparing the attributes.

Copy the JSON config file generated on Keycloak (tutorial) and paste it inside of a folder (Ex.: auth/keycloak.json) in your server.

The options passed to Parse Server:

{
  auth: {
    keycloak: {
      config: require(`./auth/keycloak.json`) // Required
    }
  }
}

Configuring Parse Server for LDAP

The LDAP module can check if a user can authenticate (bind) with the given credentials. Optionally, it can also check if the user is in a certain group. This check is done using a user specified query, called an LDAP Filter. The query should return all groups which the user is a member of. The cn attribute of the query results is compared to groupCn.

To build a query which works with your LDAP server, you can use a LDAP client like Apache Directory Studio.

{
  "ldap": {
    "url": "ldap://host:port",
    "suffix": "the root of your LDAP tree",
    "dn": "Bind dn.  is replaced with the id suppied in authData",
    "groupCn": "Optional. A group which the user must be a member of.",
    "groupFilter": "Optional. An LDAP filter for finding groups which the user is part of.  is replaced with the id supplied in authData."
  }
}

If either groupCN or groupFilter is not specified, the group check is not performed.

Example Configuration (this works with the public LDAP test server hosted by Forumsys):

{
  "ldap": {
    "url": "ldap://ldap.forumsys.com:389",
    "suffix": "dc=example,dc=com",
    "dn": "uid=, dc=example, dc=com",
    "groupCn": "Chemists",
    "groupFilter": "(&(uniqueMember=uid=,dc=example,dc=com)(objectClass=groupOfUniqueNames))"
  }
}

authData:

{
  "authData": {
    "ldap": {
      "id": "user id",
      "password": "password"
    }
  }
}

LinkedIn authData

{
  "linkedin": {
    "id": "user's LinkedIn id (string)",
    "access_token": "an authorized LinkedIn access token for the user",
    "is_mobile_sdk": true|false // set to true if you acquired the token through LinkedIn mobile SDK
  }
}

Meetup authData

{
  "meetup": {
    "id": "user's Meetup id (string)",
    "access_token": "an authorized Meetup access token for the user"
  }
}

Microsoft Graph authData

{
  "microsoft": {
    "id": "user's microsoft id (string)", // required
    "access_token": "an authorized microsoft graph access token for the user", // required
    "mail": "user's microsoft email (string)"
  }
}

Learn more about Microsoft Graph Auth Overview.

To get access on behalf of a user.

PhantAuth authData

As of Parse Server 3.7.0 you can use PhantAuth.

{
  "phantauth": {
    "id": "user's PhantAuth sub (string)",
    "access_token": "an authorized PhantAuth access token for the user",
  }
}

Learn more about PhantAuth.

QQ authData

{
  "qq": {
    "id": "user's QQ id (string)",
    "access_token": "an authorized QQ access token for the user"
  }
}

Spotify authData

{
  "spotify": {
    "id": "user's spotify id (string)",
    "access_token": "an authorized spotify access token for the user"
  }
}

vKontakte authData

{
  "vkontakte": {
    "id": "user's vkontakte id (string)",
    "access_token": "an authorized vkontakte access token for the user"
  }
}

Configuring parse-server for vKontakte

{
  auth: {
   vkontakte: {
     appSecret: "", // REQUIRED, your vkontakte application secret
     appIds: "" // REQUIRED, your vkontakte application id
   },
  }
}

WeChat authData

{
  "wechat": {
    "id": "user's wechat id (string)",
    "access_token": "an authorized wechat access token for the user"
  }
}

Weibo authData

{
  "weibo": {
    "id": "user's weibo id (string)",
    "access_token": "an authorized weibo access token for the user"
  }
}

Custom authentication

It is possible to leverage the OAuth support with any 3rd party authentication that you bring in.

{

  auth: {
   my_custom_auth: {
     module: "PATH_TO_MODULE" // OR object,
     option1: "",
     option2: "",
   }
  }
}

On this module, you need to implement and export those two functions validateAuthData(authData, options) {} and validateAppId(appIds, authData, options) {}.

For more information about custom auth please see the examples:

• Facebook OAuth
• Twitter OAuth
• Instagram OAuth
• Microsoft Graph OAuth

Using MongoDB Read Preference

As of ParseServer 2.5, it is possible to set a read preference for Mongo DB queries. For a discussion of Read Preference, limitations and use cases, see the Mongo documentation for Read Preference..

How to set Read Preference in ParseServer

Currently, read preference can only be set in cloud code. For an example see: cloud code examples

Development Guide

Running Parse Server for development

Normally, when you run a standalone Parse Server, the latest release that has been pushed to npm will be used. This is great if you are interested in just running Parse Server, but if you are developing a new feature or fixing a bug you will want to use the latest code on your development environment.

First, you will need to clone this repo if you haven’t done so yet.

git clone https://github.com/parse-community/parse-server.git

You can then link the parse-server module to the cloned repo and run npm install:

npm link parse-server path/to/cloned/repo
npm install

You can now start Parse Server using npm start:

npm start -- --appId APPLICATION_ID --masterKey MASTER_KEY --serverURL http://localhost:1337/parse

Notable Files

The following is a breakdown of the various files you will find in the Parse Server source code. Click on a filename to learn more about the purpose behind each file.

• index.js - exposes the ParseServer constructor and mutates Parse.Cloud
• analytics.js - handle the /events routes
• Auth.js - Auth object, created to hold config/master/user information for requests
• batch.js - batch handling implemented for PromiseRouter
• cache.js - simple caching for the app and user sessions
• classes.js - handle the /classes routes
• Config.js - Config object, storage for the application configuration and some router information
• crypto.js - uses bcrypt for password hashing and comparison
• DatabaseAdapter.js - Interface for allowing the underlying database to be changed
• ExportAdapter.js - DatabaseAdapter for MongoDB (default)
• facebook.js - helper functions for accessing the Graph API
• files.js - handle the /files routes
• FilesAdapter.js - Interface for allowing the underlying file storage to be changed
• FileLoggerAdapter.js - LoggerAdapter for logging info and error messages into local files (default)
• functions.js - handle the /functions routes
• GridStoreAdapter.js - FilesAdapter for storing uploaded files in GridStore/MongoDB (default)
• installations.js - handle the /installations routes
• LoggerAdapter.js - Interface for allowing the underlying logging transport to be changed
• middlewares.js - Express middleware used during request processing
• PromiseRouter.js - PromiseRouter uses promises instead of req/res/next middleware conventions
• push.js - handle the /push route
• rest.js - main interface for REST operations
• RestQuery.js - RestQuery encapsulates everything needed for a ‘find’ operation from REST API format
• RestWrite.js - RestWrite encapsulates everything needed for ‘create’ and ‘update’ operations from REST API format
• roles.js - handle the /roles routes
• Schema.js - Schema handles schema validation, persistence, and modification.
• sessions.js - handle the /sessions and /logout routes
• testing-routes.js - used by internal Parse integration tests
• transform.js - transforms keys/values between Mongo and Rest API formats.
• triggers.js - cloud code methods for handling database trigger events
• users.js - handle the /users and /login routes

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 notes.