Parse Server Deployment and Usage Guide

Prerequisites

Before deploying Parse Server, ensure you have the following:

• Node.js: Version 20, 22, or 24 (required)
• Database:
  • MongoDB: Version 7 or 8 (required for default storage)
  • PostgreSQL: Version 16, 17, or 18 (optional, for PostgreSQL storage)
• Package Manager: npm (comes with Node.js)
• Git: For cloning the repository

Installation

1. Clone the repository:

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

2. Install dependencies:

   npm install
   

3. Install Parse Server globally (for CLI usage):

   npm install -g parse-server
   

Configuration

Parse Server can be configured using environment variables or a configuration object. Key configuration options include:

Basic Configuration

# Required
export APP_ID="your_app_id"
export MASTER_KEY="your_master_key"
export DATABASE_URI="mongodb://localhost:27017/dev"

# Optional
export SERVER_URL="http://localhost:1337/parse"
export FILE_KEY="optional_file_key"
export CLIENT_KEY="optional_client_key"
export REST_API_KEY="optional_rest_api_key"
export DOTNET_KEY="optional_dotnet_key"
export JAVASCRIPT_KEY="optional_javascript_key"
export WINDOWS_KEY="optional_windows_key"
export REVOKE_SESSION_ON_PASSWORD_RESET="true"

Database Configuration

For MongoDB:

export DATABASE_URI="mongodb://localhost:27017/parse"

For PostgreSQL:

export DATABASE_URI="postgres://username:password@localhost:5432/parse"
export DATABASE_ADAPTER="parse-server/lib/Adapters/Storage/PostgreSQL"

Email Configuration (for password reset and verification)

export EMAIL_ADAPTER="parse-server/lib/Adapters/Email/MailgunAdapter"
export MAILGUN_API_KEY="your_mailgun_api_key"
export MAILGUN_DOMAIN="your_mailgun_domain"

Build & Run

Running Locally

Using the CLI

parse-server --appId YOUR_APP_ID --masterKey YOUR_MASTER_KEY --databaseURI mongodb://localhost:27017/dev

Using Node.js

Create a server.js file:

const { ParseServer } = require('parse-server');
const express = require('express');
const app = express();

const api = new ParseServer({
  databaseURI: 'mongodb://localhost:27017/dev',
  appId: 'my_app_id',
  masterKey: 'my_master_key',
  serverURL: 'http://localhost:1337/parse'
});

app.use('/parse', api);

app.listen(1337, () => {
  console.log('Parse Server running on port 1337.');
});

Run the server:

node server.js

Production

For production, use environment variables and a process manager like PM2:

npm install -g pm2
pm2 start server.js --name parse-server

Deployment

Parse Server can be deployed to various platforms:

Heroku

1. Create a Heroku app:

   heroku create your-app-name
   

2. Add MongoDB (using mLab add-on):

   heroku addons:create mongolab:sandbox
   

3. Set environment variables:

   heroku config:set APP_ID=your_app_id
   heroku config:set MASTER_KEY=your_master_key
   heroku config:set SERVER_URL=https://your-app-name.herokuapp.com/parse
   

4. Deploy:

   git push heroku main
   

Docker

Create a Dockerfile:

FROM node:20
WORKDIR /usr/src/app
COPY package*.json ./
RUN npm install
COPY . .
EXPOSE 1337
CMD ["npm", "start"]

Build and run:

docker build -t parse-server .
docker run -p 1337:1337 parse-server

AWS Elastic Beanstalk

1. Create a new Node.js environment
2. Upload your application code
3. Configure environment variables in the Elastic Beanstalk console
4. Deploy

Troubleshooting

Common Issues

1. MongoDB Connection Error:

   • Ensure MongoDB is running and accessible
   • Check the DATABASE_URI format
   • Verify network connectivity

2. Port Already in Use:

   # Check what's using the port
   lsof -i :1337
   
   # Kill the process
   kill -9 <PID>
   

3. Missing Environment Variables:

   • Ensure all required environment variables are set
   • Check for typos in variable names

4. Authentication Issues:

   • Verify APP_ID and MASTER_KEY match between client and server
   • Check that the client SDK is configured correctly

Debug Mode

Enable debug logging by setting:

export DEBUG=parse-server:*

Health Check

Parse Server provides a health endpoint at /parse/health that returns status information about the server's operational state.

Live Query Issues

If Live Query isn't working:

• Ensure Redis is configured and running
• Check that the Live Query server is started
• Verify client SDK configuration

GraphQL Issues

For GraphQL-related problems:

• Check that the GraphQL endpoint is enabled
• Verify schema generation
• Ensure proper authentication for queries

Performance Issues

• Monitor MongoDB query performance
• Consider adding indexes for frequently queried fields
• Use connection pooling for database connections
• Implement caching where appropriate