parse-server-ac
v2.3.9
Published
An express module providing a Parse-compatible API server
Downloads
8
Readme
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
April 2016 - We created a series of video screencasts, please check them out here: http://blog.parse.com/learn/parse-server-video-series-april-2016/
The fastest and easiest way to get started is to run MongoDB and Parse Server locally.
Running Parse Server
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.
Inside a Docker container
$ docker build --tag parse-server .
$ docker run --name my-mongo -d mongo
$ docker run --name my-parse-server --link my-mongo:mongo -d parse-server --appId APPLICATION_ID --masterKey MASTER_KEY --databaseURI mongodb://mongo/test
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 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 to various infrastructure providers:
- Heroku and mLab
- AWS and Elastic Beanstalk
- Google App Engine
- Microsoft Azure
- SashiDo
- Digital Ocean
- Pivotal Web Services
- Back4app
- Gomix
- 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: '/home/myApp/cloud/main.js', // Absolute 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
.
Logging
Parse Server will, by default, log:
- to the console
- daily rotating files as new line delimited JSON
Logs are also be viewable in Parse Dashboard.
Want to log each request and response? Set the VERBOSE
environment variable when starting parse-server
. Usage :- VERBOSE='1' parse-server --appId APPLICATION_ID --masterKey MASTER_KEY
Want logs to be in placed in other folder? Pass the PARSE_SERVER_LOGS_FOLDER
environment variable when starting parse-server
. Usage :- PARSE_SERVER_LOGS_FOLDER='<path-to-logs-folder>' parse-server --appId APPLICATION_ID --masterKey MASTER_KEY
Want new line delimited JSON error logs (for consumption by CloudWatch, Google Cloud Logging, etc.)? Pass the JSON_LOGS
environment variable when starting parse-server
. Usage :- JSON_LOGS='1' parse-server --appId APPLICATION_ID --masterKey MASTER_KEY
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.
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
. 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 codemain.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
Advanced options
fileKey
- For migrated apps, this is necessary to provide access to files already hosted on Parse.allowClientClassCreation
- Set to false to disable client class creation. Defaults to true.enableAnonymousUsers
- Set to false to disable anonymous users. Defaults to true.auth
- Used to configure support for 3rd party authentication.facebookAppIds
- An array of valid Facebook application IDs that users may authenticate with.mountPath
- Mount path for the server. Defaults to/parse
.filesAdapter
- The default behavior (GridStore) can be changed by creating an adapter class (seeFilesAdapter.js
).maxUploadSize
- Max file size for uploads. Defaults to 20 MB.loggerAdapter
- The default behavior/transport (File) can be changed by creating an adapter class (seeLoggerAdapter.js
).sessionLength
- The length of time in seconds that a session should be valid for. Defaults to 31536000 seconds (1 year).revokeSessionOnPasswordReset
- When a user changes their password, either through the reset password email or while logged in, all sessions are revoked if this is true. Set to false if you don't want to revoke sessions.accountLockout
- Lock account when a malicious user is attempting to determine an account password by trial and error.passwordPolicy
- Optional password policy rules to enforce.customPages
- A hash with urls to override email verification links, password reset links and specify frame url for masking user-facing pages. Available keys:parseFrameURL
,invalidLink
,choosePassword
,passwordResetSuccess
,verifyEmailSuccess
.middleware
- (CLI only), a module name, function that is an express middleware. When using the CLI, the express app will load it just before mounting parse-server on the mount path. This option is useful for injecting a monitoring middleware.
Logging
Use the PARSE_SERVER_LOGS_FOLDER
environment variable when starting parse-server
to save your server logfiles to the specified folder.
Usage:
PARSE_SERVER_LOGS_FOLDER='<path-to-logs-folder>' parse-server --appId APPLICATION_ID --masterKey MASTER_KEY
Email verification and password reset
Verifying user email addresses and enabling password reset via email requires an email adapter. As part of the parse-server
package we provide an adapter for sending email through Mailgun. To use it, sign up for Mailgun, and add this to your initialization code:
var server = ParseServer({
...otherOptions,
// Enable email verification
verifyUserEmails: true,
// if `verifyUserEmails` is `true` and
// if `emailVerifyTokenValidityDuration` is `undefined` then
// email verify token never expires
// else
// email verify token expires after `emailVerifyTokenValidityDuration`
//
// `emailVerifyTokenValidityDuration` defaults to `undefined`
//
// email verify token below expires in 2 hours (= 2 * 60 * 60 == 7200 seconds)
emailVerifyTokenValidityDuration: 2 * 60 * 60, // in seconds (2 hours = 7200 seconds)
// set preventLoginWithUnverifiedEmail to false to allow user to login without verifying their email
// set preventLoginWithUnverifiedEmail to true to prevent user from login if their email is not verified
preventLoginWithUnverifiedEmail: false, // defaults to false
// The public URL of your app.
// This will appear in the link that is used to verify email addresses and reset passwords.
// Set the mount path as it is in serverURL
publicServerURL: 'https://example.com/parse',
// Your apps name. This will appear in the subject and body of the emails that are sent.
appName: 'Parse App',
// The email adapter
emailAdapter: {
module: 'parse-server-simple-mailgun-adapter',
options: {
// The address that your emails come from
fromAddress: '[email protected]',
// Your domain from mailgun.com
domain: 'example.com',
// Your API key from mailgun.com
apiKey: 'key-mykey',
}
},
// account lockout policy setting (OPTIONAL) - defaults to undefined
// if the account lockout policy is set and there are more than `threshold` number of failed login attempts then the `login` api call returns error code `Parse.Error.OBJECT_NOT_FOUND` with error message `Your account is locked due to multiple failed login attempts. Please try again after <duration> minute(s)`. After `duration` minutes of no login attempts, the application will allow the user to try login again.
accountLockout: {
duration: 5, // duration policy setting determines the number of minutes that a locked-out account remains locked out before automatically becoming unlocked. Set it to a value greater than 0 and less than 100000.
threshold: 3, // threshold policy setting determines the number of failed sign-in attempts that will cause a user account to be locked. Set it to an integer value greater than 0 and less than 1000.
},
// optional settings to enforce password policies
passwordPolicy: {
// Two optional settings to enforce strong passwords. Either one or both can be specified.
// If both are specified, both checks must pass to accept the password
// 1. a RegExp object or a regex string representing the pattern to enforce
validatorPattern: /^(?=.*[a-z])(?=.*[A-Z])(?=.*[0-9])(?=.{8,})/, // enforce password with at least 8 char with at least 1 lower case, 1 upper case and 1 digit
// 2. a callback function to be invoked to validate the password
validatorCallback: (password) => { return validatePassword(password) },
doNotAllowUsername: true, // optional setting to disallow username in passwords
maxPasswordAge: 90, // optional setting in days for password expiry. Login fails if user does not reset the password within this period after signup/last reset.
maxPasswordHistory: 5, // optional setting to prevent reuse of previous n passwords. Maximum value that can be specified is 20. Not specifying it or specifying 0 will not enforce history.
//optional setting to set a validity duration for password reset links (in seconds)
resetTokenValidityDuration: 24*60*60, // expire after 24 hours
}
});
You can also use other email adapters contributed by the community such as:
- parse-server-postmark-adapter
- parse-server-sendgrid-adapter
- parse-server-mandrill-adapter
- parse-server-simple-ses-adapter
- parse-server-mailgun-adapter-template
- parse-server-mailjet-adapter
- simple-parse-smtp-adapter
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
.
Available Adapters
Parse Server Modules (Adapters)
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; orGCSAdapter
, 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 Google Cloud Storage, additional configuration information is available in the Parse Server guide.
Support
For implementation related questions or technical support, please refer to the Stack Overflow and Server Fault communities.
If you believe you've found an issue with Parse Server, make sure these boxes are checked before reporting an issue:
[ ] You've met the prerequisites.
[ ] You're running the latest version of Parse Server.
[ ] You've searched through existing issues. Chances are that your issue has been reported or resolved before.
Want to ride the bleeding edge?
The latest
branch in this repository is automatically maintained to be the last
commit to master
to pass all tests, in the same form found on npm. It is
recommend to use builds deployed npm for many reasons, but if you want to use
the latest not-yet-released version of parse-server, you can do so by depending
directly on this branch:
npm install parseplatform/parse-server.git#latest
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.
As of April 5, 2017, Parse, LLC has transferred this code to the parse-community organization, and will no longer be contributing to or distributing this code.