parseplatform/parse-server repository overview

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

⁠ ⁠

⁠Our Sponsors

Our backers and sponsors help to ensure the quality and timely development of the Parse Platform.

🥉 Bronze Sponsors

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

The full documentation for Parse Server is available in the wiki⁠. The Parse Server guide⁠ is a good place to get started. An API reference⁠ and Cloud Code guide⁠ are also available. If you're interested in developing for Parse Server, the Development guide⁠ will help you get set up.

• Getting Started⁠
  • Running Parse Server⁠
    • Compatibility⁠
      • Node.js⁠
      • MongoDB⁠
      • PostgreSQL⁠
    • Locally⁠
    • Docker Container⁠
    • Saving an Object⁠
    • Connect an SDK⁠
  • Running Parse Server elsewhere⁠
    • Sample Application⁠
    • Parse Server + Express⁠
• Configuration⁠
  • Basic Options⁠
  • Client Key Options⁠
  • Email Verification and Password Reset⁠
  • Password and Account Policy⁠
  • Custom Routes⁠
    • Example⁠
    • Reserved Paths⁠
    • Parameters⁠
  • Custom Pages⁠
  • Using Environment Variables⁠
  • Available Adapters⁠
  • Configuring File Adapters⁠
  • Idempotency Enforcement⁠
  • Localization⁠
    • Pages⁠
      • Localization with Directory Structure⁠
      • Localization with JSON Resource⁠
      • Dynamic placeholders⁠
      • Reserved Keys⁠
      • Parameters⁠
  • Logging⁠
• Deprecations⁠
• Live Query⁠
• GraphQL⁠
  • Running⁠
    • Using the CLI⁠
    • Using Docker⁠
    • Using Express.js⁠
  • Checking the API health⁠
  • Creating your first class⁠
  • Using automatically generated operations⁠
  • Customizing your GraphQL Schema⁠
  • Learning more⁠
• Upgrading to 3.0.0⁠
• Want to ride the bleeding edge?⁠
• Contributing⁠
• Contributors⁠
• Sponsors⁠
• Backers⁠

⁠Getting Started

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

⁠Running Parse Server

Before you start make sure you have installed:

• NodeJS⁠ that includes npm
• MongoDB⁠ or PostgreSQL⁠(with PostGIS⁠ 2.2.0 or higher)
• Optionally Docker⁠

⁠Compatibility

⁠Node.js

Parse Server is continuously tested with the most recent releases of Node.js to ensure compatibility. We follow the Node.js Long Term Support plan⁠ and only test against versions that are officially supported and have not reached their end-of-life date.

⁠MongoDB

Parse Server is continuously tested with the most recent releases of MongoDB to ensure compatibility. We follow the MongoDB support schedule⁠ and only test against versions that are officially supported and have not reached their end-of-life date.

⁠PostgreSQL

Parse Server is continuously tested with the most recent releases of PostgreSQL and PostGIS to ensure compatibility, using PostGIS docker images⁠. We follow the PostgreSQL support schedule⁠ and PostGIS support schedule⁠ and only test against versions that are officially supported and have not reached their end-of-life date. Due to the extensive PostgreSQL support duration of 5 years, Parse Server drops support if a version is older than 3.5 years and a newer version has been available for at least 2.5 years.

⁠Locally

$ npm install -g parse-server mongodb-runner
$ mongodb-runner start
$ parse-server --appId APPLICATION_ID --masterKey MASTER_KEY --databaseURI mongodb://localhost/test

Note: If installation with -g fails due to permission problems (npm ERR! code 'EACCES'), please refer to this link⁠.

⁠Docker Container

$ git clone https://github.com/parse-community/parse-server
$ cd parse-server
$ docker build --tag parse-server .
$ docker run --name my-mongo -d mongo

⁠Running the Parse Server Image

$ docker run --name my-parse-server -v config-vol:/parse-server/config -p 1337:1337 --link my-mongo:mongo -d parse-server --appId APPLICATION_ID --masterKey MASTER_KEY --databaseURI mongodb://mongo/test

Note: If you want to use Cloud Code⁠, add -v cloud-code-vol:/parse-server/cloud --cloud /parse-server/cloud/main.js to the command above. Make sure main.js is in the cloud-code-vol directory before starting Parse Server.

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 --databaseURI 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 an 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 an SDK

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.

⁠Sample Application

We have provided a basic Node.js application⁠ that uses the Parse Server module on Express and can be easily deployed to various infrastructure providers:

• Heroku and mLab⁠
• AWS and Elastic Beanstalk⁠
• Google App Engine⁠
• Microsoft Azure⁠
• SashiDo⁠
• Digital Ocean⁠
• Pivotal Web Services⁠
• Back4app⁠
• Glitch⁠
• Flynn⁠

⁠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();

var api = new ParseServer({
  databaseURI: 'mongodb://localhost:27017/dev', // Connection string for your MongoDB database
  cloud: './cloud/main.js', // Path to your Cloud Code
  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.');
});

For a full list of available options, run parse-server --help or take a look at Parse Server Configurations⁠.

⁠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 or take a look at Parse Server Configurations⁠.

⁠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. Be sure to URL encode your password⁠ if your password has special characters.
• port - The default port is 1337, specify this parameter to use a different port.
• serverURL - URL to your Parse Server (don't forget to specify http:// or https://). This URL will be used when making requests to Parse Server from Cloud Code.
• cloud - The absolute path to your cloud code main.js file.
• push - Configuration options for APNS and GCM push. See the Push Notifications quick start⁠.

⁠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

⁠Email Verification and Password Reset

Verifying user email addresses and enabling password reset via email requires an email adapter. There are many email adapters provided and maintained by the community. The following is an example configuration with an example email adapter. See the Parse Server Options⁠ for more details and a full list of available options.

const server = ParseServer({
  ...otherOptions,

  // Enable email verification
  verifyUserEmails: true,

  // Set email verification token validity to 2 hours
  emailVerifyTokenValidityDuration: 2 * 60 * 60,

  // Set email adapter
  emailAdapter: {
    module: 'example-mail-adapter',
    options: {
      // Additional adapter options
      ...mailAdapterOptions
    }
  },
});

Email adapters contributed by the community:

• parse-server-api-mail-adapter⁠ (localization, templates, universally supports any email provider)
• parse-smtp-template⁠ (localization, templates)
• parse-server-postmark-adapter⁠
• parse-server-sendgrid-adapter⁠
• parse-server-mandrill-adapter⁠
• parse-server-simple-ses-adapter⁠
• parse-server-mailgun-adapter-template⁠
• parse-server-sendinblue-adapter⁠
• parse-server-mailjet-adapter⁠
• simple-parse-smtp-adapter⁠
• parse-server-generic-email-adapter⁠

⁠Password and Account Policy

Set a password and account policy that meets your security requirements. The following is an example configuration. See the Parse Server Options⁠ for more details and a full list of available options.

const server = ParseServer({
  ...otherOptions,

  // The account lock policy
  accountLockout: {
    // Lock the account for 5 minutes.
    duration: 5,
    // Lock an account after 3 failed log-in attempts
    threshold: 3,
    // Unlock the account after a successful password reset
    unlockOnPasswordReset: true,
  },

  // The password policy
  passwordPolicy: {    
    // Enforce a password of at least 8 characters which contain at least 1 lower case, 1 upper case and 1 digit
    validatorPattern: /^(?=.*[a-z])(?=.*[A-Z])(?=.*[0-9])(?=.{8,})/,
    // Do not allow the username as part of the password
    doNotAllowUsername: true,
    // Do not allow to re-use the last 5 passwords when setting a new password
    maxPasswordHistory: 5,
  },
});

⁠Custom Routes

Caution, this is an experimental feature that may not be appropriate for production.

Custom routes allow to build user flows with webpages, similar to the existing password reset and email verification features. Custom routes are defined with the pages option in the Parse Server configuration:

⁠Example

const api = new ParseServer({
  ...otherOptions,

  pages: {
    enableRouter: true, // Enables the experimental feature; required for custom routes
    customRoutes: [{
      method: 'GET',
      path: 'custom_route',
      handler: async request => {
        // custom logic
        // ...
        // then, depending on the outcome, return a HTML file as response
        return { file: 'custom_page.html' };
      }
    }]
  }
}

The above route can be invoked by sending a GET request to: https://[parseServerPublicUrl]/[parseMount]/[pagesEndpoint]/[appId]/[customRoute]

The handler receives the request and returns a custom_page.html webpage from the pages.pagesPath directory as response. The advantage of building a custom route this way is that it automatically makes use of Parse Server's built-in capabilities, such as page localization⁠ and dynamic placeholders⁠.

⁠Reserved Paths

The following paths are already used by Parse Server's built-in features and are therefore not available for custom routes. Custom routes with an identical combination of path and method are ignored.

⁠Parameters