Parse Server Tutorial with iOS

Update 3/6/17: Updated for Swift 3, Xcode 8, and current state of Parse Server. Original tutorial by Marius Horga.

About a year ago, Parse, one of the most popular backend solutions for mobile apps, announced it was shutting down their hosted service and instead open sourcing their SKs.

Since that time, many developers have migrated their apps over to the open source Parse Server. The parse platform is quite active, with 143 contributors and ~13K stars on GitHub.

Even if you didn’t use Parse in the old days, the Parse Server is a nice easy-to-use option to set up a backend for your apps, since it’s open source and well maintained.

In this tutorial, we’ll show you how you can set up and host your very own Parse Server. Let’s dive in!

Note: This Parse server tutorial focuses on setting up the server itself, and not on the Parse SDK. We assumes you know the basics of developing iOS apps using the Parse SDK, and have worked through the Parse Tutorial: Getting Started with Web Backends.

If you haven’t gone through it, that’s fine, you can still read and make quite a bit of progress.

Getting Started

First, you need an existing iOS app that uses Parse so you can follow the steps in this Parse server tutorial. Feel free to use your own demo app, or download this Parse Starter project. It’s set up to work with Swift 3, iOS 10 and includes the latest Parse SDK (at the time of writing v1.14.2).

Build and run the project in Xcode to see the following:

About Parse Server & Prerequisites

In this Parse server tutorial, you’ll install your own Parse Server that can be maintained through the Parse SDK. It’s open source, thus (almost) guaranteeing it’ll never cease to exist. It can be hosted on all major web service providers, such as Heroku, Amazon AWS or Azure.

There are, however, a few features from Parse.com that have not been implemented on Parse Server, such as jobs, analytics and config. Moreover, with Parse Server, you do all of the work of installing and hosting the service either locally or in the cloud.

Parse made all the necessary tools available to help developers set up their server: an open source application server, Push Notification guide and a Parse Dashboard for local development.

Parse further recommends that you use mLab (formerly known as MongoLab) and Heroku to host the database and server, respectively.

The minimum requirements to install Parse Server are:

• Homebrew, latest version
• Node 4.3
• MongoDB version 2.6.X or newer
• Python 2.x
• For deployment, Heroku Toolbelt

The MongoDB requirements for Parse Server are:

• About 10 times the space you used with Parse, because it heavily compressed your content.
• The failIndexKeyTooLong parameter must be set to false to accommodate indexed fields larger than 1024 bytes and collections larger than 1 million documents.
• An SSL connection — although it’s not required, it’s strongly recommended.
• For minimal latency, host your MongoDB servers in the US-East region.

Creating a New Database

Go to the mLab website and create an account if you don’t have one already, and then watch for the confirmation email that will let you activate your new account. Once activated, under MongoDB Deployments, click the Create New button:

Choose Amazon AWS, US East, Single-node and Sandbox — these are the recommended free options:

Your database name can be anything, but for now, just use tutorial-app. Click on Create new MongoDB deployment and wait for your new database to be created.

Next, select tutorial-app and go to Users / Add database user. Enter a username and password then click Create. Save your Database URI somewhere that’s easy to reference, because you’ll need it several times throughout this Parse server tutorial. It should look similar to the one below, but your database ID will be unique:

mongodb://<dbuser>:<dbpassword>@ds017678.mlab.com:17678/tutorial-app

Install the Prerequisites

Open Terminal and run through the below steps to make sure the required support is in place.

Homebrew

If you don’t have Homebrew, enter this command:

$ /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

If you already have Homebrew, make sure it’s up to date by entering this command:

$ brew update

MongoDM

Next, install MongoDB — this can take a few minutes:

$ brew install mongodb --with-openssl

Create a local MongoDB database by running the following:

$ mkdir -p /data/db

Make sure that the /data/db directory has the right permissions by running the following:

$ sudo chown -R `id -un` /data/db

To allow connections to your local MongoDB daemon, run the following:

$ mongod --config /usr/local/etc/mongod.conf

Now you just need to verify that you have the required MongoDB version: v2.6.X or newer. In a new Terminal window run the following:

$ mongo
MongoDB shell version v3.4.0
connecting to: mongodb://127.0.0.1:27017
MongoDB server version: 3.4.0

Press Control + C to quit MongoDB.

Python

It’s usually installed on all major OS versions, but check if you have it first:

$ python -V
Python 2.7.10

If you get a no, install Python by running this:

$ brew install python

Node

Install the latest version of Node:

$ brew install node

Confirm that you have the required version — v4.3 or newer:

$ node --version
V7.2.0

Installing the Parse Server

To make life a little easier for developers, Parse created a local version of its server and pushed it to GitHub. Make a clone of it on your system:

$ git clone https://github.com/ParsePlatform/parse-server-example.git Parse

Change the directory to the freshly cloned Parse directory:

$ cd Parse

Install Parse Server in this directory:

$ npm install

Start Parse Server:

$ npm run start

Check if it was successful by copying and pasting http://localhost:1337 into your browser:

Well, at least it dreams of being something. Rather progressive for a server, don’t you think? :]
Quit the server by pressing Control + C.

Next, in the root folder of the Parse project, open index.js and replace the default database string with your MongoDB database URI:

// Replace this
var databaseUri = process.env.DATABASE_URI || process.env.MONGOLAB_URI;

// With this
var databaseUri = 'mongodb://<dbuser>:<dbpassword>@ds017678.mlab.com:17678/tutorial-app';

This configures Parse Server to talk to your mLab database.

You also need to specify your Application ID. This is a unique ID that identifies your app. Sounds familliar? You’re right, it’s pretty much like your app’s Bundle Identifier. Copy your app’s bundle identifier and open index.js again:

// Replace this
appId: process.env.APP_ID || 'myAppId',

// With this, the value that actually represents your Application ID
appId: process.env.APP_ID || '<myAppId>',

Now that you’ve wired it up, you need to test if the Parse Server is talking to the remote database. First, start the server again by running:

$ npm run start

Next, in a new Terminal window, run the following command. Remember to insert your Application ID from the Parse.com dashboard:

$ curl -X GET \
-H "X-Parse-Application-Id: <myAppId>" \
-H "Content-Type: application/json" \
-d '{}' \
http://localhost:1337/parse/classes/WallPost

The server shouldn’t return any results for now, but that will change once you set up and run the iOS app.

{"results":[]}

You now have a functioning Parse Server.