Guide to Building your own Parse Server

Parse is a great toolset for mobile developers. It provides a node server, a MongoDB database, an interactive dashboard, and native SDKs that makes it easy to write apps that require a server. They have since open-sourced all of those components. This is a guide to help you take the open-sourced code and set up your own Parse server.

Hosting your Server

I’m going to use DigitalOcean for this setup, but you can use any server provider¹.

Login or Create a DigitalOcean account.

Create a new Droplet (a virtual private server).

Click on One-Click Apps, and choose Docker 1.11.0 on Ubuntu 14.04

Docker is an open-source toolset that enables you to put the different parts of your app into containers and connect them together when needed. We are going to use it because it helps automate a lot of the setup required for us.

For size, choose at least the $10/month option. (We need at least 1GB RAM for the installation process)

You will need to login to the server, add a SSH key to it(or get an email from Digital Ocean with the password)².

Hit create and wait a couple seconds till you get the IP address for your server.

Open up terminal and log into your server with the following command.

ssh root@IP.AD.DR.ESS

Once logged in to your server, let’s make sure everything is up to date by running the following two lines:

apt-get update -y
apt-get upgrade -y

Then, let’s install docker-compose

apt-get install python-pip -y
pip install docker-compose

Alright, we are ready to add the source code for Parse server. The line below clones a repo that is a fork of Parse’s server. The fork adds a docker-compose.yml file that we will talk about below. We use the --recursive tag below because the project also has a fork of the Parse’s dashboard included in it.

git clone https://github.com/dmathewwws/parse-server-example --recursive

Go into the directory you just cloned and edit the docker-compose.yml file³.

cd parse-server-example/
vim docker-compose.yml

Inside this file, we see there are three services, each service is a set of instructions to set up its own docker container, let go over each one so we understand what is going on:

1) parse-server, is our server and therefore contains logic to access different parts of our database. The build argument of ‘.’ tells us that there is a Dockerfile in the current directory. If you look it up, it shows you a set of instructions for installing node and then installing parse-server. The ports argument gives us the port at which this container will be available (1337). Lastly, we do need to change a couple things, the environment argument sets a bunch of environment variables, we should pick a new APP_ID, MASTER_KEY, CLIENT_KEY. Use a password generator to get secure passwords to use for each key⁴.

 parse-server:
   build: .
   ports:
     — “1337:1337”
   environment:
     APP_ID: XXXX
     MASTER_KEY: YYYY
     CLIENT_KEY: ZZZZ
     DATABASE_URI: mongodb://mongo:27017/dev

2) mongo, is our database, which contains all out data. In this case, it is a MongoDB. It locally exposes port 27017 which is where our Parse server is looking for it at. There is nothing we need to changed here.

mongo:
  image: mongo:3.2.1
  expose:
    — “27017”
  volumes:
    — /data/db
 command: “ —- setParameter failIndexKeyTooLong=false”

3) parse-dashboard, is Parse’s dashboard which is a great way to view and edit data in our database. The build argument shows us that it has a Dockerfile in the folder ‘parse-dashboard/’. The ports arguments tells us that the port at which this container will be available is 4040. There are a couple things we should change: change the IP.AD.DR.ESS in PARSE_DASHBOARD_SERVER_URL to match your server’s IP Address, change PARSE_DASHBOARD_APP_ID and PARSE_DASHBOARD_MASTER_KEY to match the variables you picked above, edit PARSE_DASHBOARD_USER_ID and PARSE_DASHBOARD_USER_PASSWORD to pick a secure username and password for the dashboard.

parse-dashboard:
  build: parse-dashboard/
  ports:
    — “4040:4040”
  environment:
    PARSE_DASHBOARD_SERVER_URL: http://IP.AD.DR.ESS:1337/parse
    PARSE_DASHBOARD_APP_ID: XXXX
    PARSE_DASHBOARD_MASTER_KEY: YYYY
    PARSE_DASHBOARD_APP_NAME: setAppName
    PARSE_DASHBOARD_ALLOW_INSECURE_HTTP: Y
    PARSE_DASHBOARD_USER_ID: admin
    PARSE_DASHBOARD_USER_PASSWORD: password
    MOUNT_PATH: /dashboard

Save and Quit. Now, to create these 3 containers, run the following command. It will take a couple minutes.

docker-compose up -d --build

Once done, you should check if it is working by going to http://IP.AD.DR.ESS:1337. You should see the below on your browser.

Connecting to a Client

Awesome, you now you’ve got our server up and running, it’s time to access it through a native app. The below is Swift code but Parse Server’s open-source guide has examples in other languages as well.

let configuration = ParseClientConfiguration {
    $0.applicationId = "YOUR_APP_ID"
    $0.clientKey = "YOUR_CLIENT_KEY"
    $0.server = "http://IP.AD.DR.ESS:1337/parse"
}
Parse.initializeWithConfiguration(configuration)
let testObject = PFObject(className: “Test”)
testObject[“foo”] = “bar”
testObject.saveInBackgroundWithBlock { (success, error) in 
    if success {
        print(“Yah, saved to parse!”)
    }
}

Next, you should check that your dashboard shows this saved information. Go to http://IP.AD.DR.ESS:4040/dashboard. Type in your username and password and you should see data from your database.

HTTPS

Yay! You have setup your own Parse server. However, if you want to use this for a production app you should use HTTPS and SSL to make sure all communication between your app and your server is secure and encrypted.

First of all, to see all the containers we have running on our server, type:

docker ps

To stop all three containers, type each line below:

docker stop parseserverexample_parse-dashboard_1
docker stop parseserverexample_parse-server_1
docker stop parseserverexample_mongo_1

Next, we need to have a domain that has HTTPS certificates (or get certificates for our domain using Let’s Encrypt⁵).

This is a good time to make sure your domain routes to your IP.AD.RE.ESS. Each domain name registrar is different but check that you set the IP.AD.RE.ESS as the Value for both @ and www. This will route your-domain.com and www.your-domain.com to your IP.AD.RE.ESS.

Next, we need to install nginx.

Ngnix allows us to setup a server where we can enable SSL for secure communication and allows up to map ports to routes ex) instead of using yourserver.com:1337, we can now use yourserver.com/parse-server

To install nginx, type:

apt-get install nginx -y

Next, remove the default nginx configuration

cd /etc/nginx/sites-available/
rm default

Next, we are going to create our own server config.

vim /etc/nginx/sites-available/your-domain.com

Copy/Paste the below gist into it:

Let’s go over the file you copy/pasted

There is a line server_name your-domain.com www.your-domain.com Change it to be your own domain.

There are also a couple lines for where you should put the .pem and .key files that Let’s Encrypt generated.

ssl_certificate /etc/nginx/ssl/chained.pem;
ssl_certificate_key /etc/nginx/ssl/domain.key;

For me this involved making the ssl directory and then adding the two files to the directory

mkdir /etc/nginx/ssl/ 

Lastly, let’s go over what the ‘location /parse-server/’ and ‘location /dashboard/’ parts do.

For ‘location /parse-server/’ it routes anything from http://your-domain.com:1337 to https://your-domain.com/parse-server/

‘location /dashboard/’ does something similar, it routes http://your-domain.com:4040 to https://your-domain.com/dashboard/

Woah!

Run the below commands to enable the config file you have written and to restart nginx

ln -s /etc/nginx/sites-available/your-domain.com /etc/nginx/sites-enabled/your-domain.com
service nginx restart

Lastly, we need to change a couple lines in our docker-compose.yml file and we are all done.

Go to the parse-server-example directory and edit docker-compose.yml

Under parse-dashboard, updated PARSE_DASHBOARD_SERVER_URL to be https://your-domain.com/parse-server/parse

Save and quit, then run:

docker-compose up -d --build

Wait and minute for it to set up. then try to save something to your parse server. The configuration would change like so:

let configuration = ParseClientConfiguration {
    $0.applicationId = "YOUR_APP_ID"
    $0.clientKey = "YOUR_CLIENT_KEY"
    $0.server = "https://your-domain.com/parse-server/parse"
}

If you get a success message, check that you see the updated information on https://your-domain.com/dashboard/

Great work! You have set up your own Parse server!

This is the basic Parse server setup, if you want to add Push Notifications, hosting images/videos on Amazon S3, check out Parse server’s documentation

Links for more resources

1. If you are starting with a blank server, you will need to install git and docker, see this helpful gist
2. Adding an SSH Key is more secure, see this guide
3. If you need some help using a text editor (like vim) on a server, refer to this. TLDR: press i to add text and :wq to save and quit.
4. Looking for a password generator? Check out LastPass’s.
5. Setting up SSL certificates can be a cumbersome process but http://gethttpsforfree.com walks you through each step in generating your certificates for Let’s Encrypt.