Introduction

Parse is a Mobile Backend as a Service platform, owned by Facebook since 2013. In January of 2016, Parse announced that its hosted services would shut down completely on January 28, 2017.

Fortunately, Parse has also released an open source API server, compatible with the hosted service’s API, called Parse Server. Parse Server is under active development, and seems likely to attract a large developer community. It can be be deployed to a range of environments running Node.js and MongoDB.

This guide focuses on migrating a pre-existing Parse application to a standalone instance of Parse Server running on Ubuntu 14.04. It uses TLS/SSL encryption for all connections, using a certificate provided by Let’s Encrypt, a new Certificate Authority which offers free certificates. It includes a few details specific to DigitalOcean and Ubuntu 14.04, but should be broadly applicable to systems running recent Debian-derived GNU/Linux distributions.

<$>[warning]
Warning: It is strongly recommended that this procedure first be tested with a development or test version of the app before attempting it with a user-facing production app. It is also strongly recommended that you read this guide in conjunction with the official migration documentation.
<$>

The target server should have enough storage to handle all of your app’s data. Since Parse compresses data on their end, they officially recommend that you provision at least 10 times as much storage space as used by your hosted app.

Step 1 – Install Let’s Encrypt and Retrieve a Certificate

Let’s Encrypt is a new Certificate Authority that provides an easy way to obtain free TLS/SSL certificates. Because a certificate is necessary to secure both the migration of data to MongoDB and your Parse Server API endpoint, we’ll begin by retrieving one with the letsencrypt client.

Install Let’s Encrypt and Dependencies

You must own or control the registered domain name that you wish to use the certificate with. If you do not already have a registered domain name, you may register one with one of the many domain name registrars out there (e.g. Namecheap, GoDaddy, etc.).

If you haven’t already, be sure to create an A Record that points your domain to the public IP address of your server. This is required because of how Let’s Encrypt validates that you own the domain it is issuing a certificate for. For example, if you want to obtain a certificate for example.com, that domain must resolve to your server for the validation process to work.

Next, clone the letsencrypt repository from GitHub to /opt/letsencrypt. The /opt/ directory is a standard location for software that’s not installed from the distribution’s official package repositories:

Retrieve Initial Certificate

Run letsencrypt with the Standalone plugin:

./letsencrypt-auto certonly --standalone

You’ll be prompted to answer several questions, including your email address, agreement to a Terms of Service, and the domain name(s) for the certificate. Once finished, you’ll receive notes much like the following:

IMPORTANT NOTES:
- Congratulations! Your certificate and chain have been saved at
/etc/letsencrypt/live/<^>your_domain_name<^>/fullchain.pem. Your cert will expire
on <^>2016-05-16<^>. To obtain a new version of the certificate in the
future, simply run Let's Encrypt again.
- If you like Let's Encrypt, please consider supporting our work by:
Donating to ISRG / Let's Encrypt: https://letsencrypt.org/donate
Donating to EFF: https://eff.org/donate-le

Note the path and expiration date of your certificate, highlighted in the example output. Your certificate files should now be available in /etc/letsencrypt/<^>your_domain_name<^>/.

Set Up Let’s Encrypt Auto Renewal

<$>[warning]
Warning: You can safely complete this guide without worrying about certificate renewal, but you will need to address it for any long-lived production environment.
<$>

You may have noticed that your Let’s Encrypt certificate is due to expire in 90 days. This is a deliberate feature of the Let’s Encrypt approach, intended to minimize the amount of time that a compromised certificate can exist in the wild if something goes wrong.

Step 2 – Configure MongoDB for Migration

Parse provides a migration tool for existing applications. In order to make use of it, we need to open MongoDB to external connections and secure it with a copy of the TLS/SSL certificate from Let’s Encrypt. Start by combining fullchain1.pem and privkey1.pem into a new file in /etc/ssl:

<$>[note]
You will have to repeat the above command after renewing your Let’s Encrypt certificate. If you configure auto-renewal of the Let’s Encrypt certificate, remember to include this operation.
<$>

Make sure mongo.pem is owned by the mongodb user, and readable only by its owner:

Once connected, choose a name for the database to store your app’s data. For example, if you’re migrating an app called Todo, you might use todo. You’ll also need to pick another strong password for a user called parse.

For example, if you are using the domain example.com, with the user parse, the password foo, and a database called todo, your connection string would look like this:

mongodb://parse:foo@example.com:27017/todo?ssl=true

Don’t forget ?ssl=true at the end, or the connection will fail. Enter the connection string into the dialog like so:

Click Begin the migration. You should see progress dialogs for copying a snapshot of your Parse hosted database to your server, and then for syncing new data since the snapshot was taken. The duration of this process will depend on the amount of data to be transferred, and may be substantial.

Verify Data Migration

Once finished, the migration process will enter a verification step. Don’t finalize the migration yet. You’ll first want to make sure the data has actually transferred, and test a local instance of Parse Server.

Return to your mongo shell, and examine your local database. Begin by accessing <^>database_name<^> and examining the collections it contains:

Your specific output will be different, but you should see data for your app. Once satisfied, exit mongo and return to the shell:

exit

Step 3 – Install and Configure Parse Server and PM2

With your app data in MongoDB, we can move on to installing Parse Server itself, and integrating with the rest of the system. We’ll give Parse Server a dedicated user, and use a utility called PM2 to configure it and ensure that it’s always running.

Install Parse Server and PM2 Globally

Use npm to install the parse-server utility, the pm2 process manager, and their dependencies, globally:

sudo npm install -g parse-server pm2

Create a Dedicated Parse User and Home Directory

Instead of running parse-server as root or your sudo user, we’ll create a system user called parse:

Alternatively, you can migrate any cloud code defined for your application by copying it from the Cloud Code section of your app’s settings on the Parse Dashboard.

Exit and save.

Retrieve Keys and Write /home/parse/ecosystem.json

PM2 is a feature-rich process manager, popular with Node.js developers. We’ll use the pm2 utility to configure our parse-server instance and keep it running over the long term.

You’ll need to retrieve some of the keys for your app. In the Parse dashboard, click on App Settings followed by Security & Keys:

Of these, only the Application ID and Master Key are required. Others (client, JavaScript, .NET, and REST API keys) may be necessary to support older client builds, but, if set, will be required in all requests. Unless you have reason to believe otherwise, you should begin by using just the Application ID and Master Key.

With these keys ready to hand, edit a new file called /home/parse/ecosystem.json:

If you have instead migrated your own custom cloud code, you can test with a known function from main.js.

Step 6 – Configure Your App for Parse Server and Finalize Migration

Your next step will be to change your client application itself to use the Parse Server API endpoint. Consult the official documentation on using Parse SDKs with Parse Server. You will need the latest version of the SDK for your platform. As with the curl-based tests above, use this string for the server URL:

https://<^>your_domain_name<^>/parse

Return to the Parse dashboard in your browser and the Migration tab:

Click the Finalize button:

Your app should now be migrated.

Conclusion and Next Steps

This guide offers a functional starting point for migrating a Parse-hosted app to a Parse Server install on a single Ubuntu system, such as a DigitalOcean droplet. The configuration we’ve described should be adequate for a low-traffic app with a modest userbase. Hosting for a larger app may require multiple systems to provide redundant data storage and load balancing between API endpoints. Even small projects are likely to involve infrastructure considerations that we haven’t directly addressed.

In addition to reading the official Parse Server documentation and tracking the GitHub issues for the project when troubleshooting, you may wish to explore the following topics: