Browse Source

cloud code, some additional warnings, conclusion

master
Brennen Bearnes 5 years ago
parent
commit
8ba6df78d9
2 changed files with 177 additions and 44 deletions
  1. +92
    -23
      README.md
  2. +85
    -21
      index.html

+ 92
- 23
README.md View File

@ -7,7 +7,7 @@ Fortunately, Parse has also released [an open source API server][parse-server],
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.
**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][parse-server-guide-migrating].
<$>
## Prerequisites
@ -274,7 +274,15 @@ exit
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.
### Create a Dedicated Parse User
### Install Parse Server and PM2 Globally
Use `npm` to install the `parse-server` utility, the `pm2` process manager, and their dependencies, globally:
```command
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**:
@ -290,17 +298,48 @@ sudo passwd parse
You'll be prompted to enter a password twice.
### Install Parse Server and PM2 Globally
Use `npm` to install the `parse-server` utility, the `pm2` process manager, and their dependencies, globally:
Now, use the `su` command to become the **parse** user:
```command
sudo npm install -g parse-server pm2
sudo su parse
```
Change to **parse**'s home directory:
```custom_prefix(parse\s$)
cd ~
```
### Write or Migrate a Cloud Code File
Create a cloud code directory:
```custom_prefix(parse\s$)
mkdir -p ~/cloud
```
Edit `/home/parse/cloud/main.js`:
```custom_prefix(parse\s$)
nano ~/cloud/main.js
```
For testing purposes, you can paste the following:
```
[label /home/parse/cloud/main.js]
Parse.Cloud.define('hello', function(req, res) {
res.success('Hi');
});
```
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.
[PM2][pm2] is a feature-rich process manager, popular with Node.js developers. We'll use the `pm2` utility to run a simple wrapper script which configures our `parse-server` instance.
Exit and save.
### Retrieve Keys and Write ecosystem.json
### Retrieve Keys and Write /home/parse/ecosystem.json
[PM2][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**:
@ -310,8 +349,8 @@ Of these, only the **Application ID** and **Master Key** are required. Others (
With these keys ready to hand, edit a new file called `/home/parse/ecosystem.json`:
```command
sudo nano /home/parse/ecosystem.json
```custom_prefix(parse\s$)
nano ecosystem.json
```
Paste the following, changing configuration values to reflect your MongoDB connection string, Application ID, and Master Key:
@ -325,7 +364,7 @@ Paste the following, changing configuration values to reflect your MongoDB conne
"merge_logs" : true,
"cwd" : "/home/parse",
"env": {
// "PARSE_SERVER_CLOUD_CODE_MAIN": "/home/parse/cloud/main.js",
"PARSE_SERVER_CLOUD_CODE_MAIN": "/home/parse/cloud/main.js",
"PARSE_SERVER_DATABASE_URI": "mongodb://<^>parse<^>:<^>password<^>@<^>your_domain_name<^>:27017/<^>database_name<^>?ssl=true",
"PARSE_SERVER_APPLICATION_ID": "<^>your_application_id<^>",
"PARSE_SERVER_MASTER_KEY": "<^>your_master_key<^>",
@ -347,14 +386,9 @@ The `env` object is used to set environment variables. If you need to configure
Exit and save `ecosystem.json`.
Now, use the `su` command to become the **parse** user, and run the script with `pm2`:
```command
sudo su parse
```
Now, run the script with `pm2`:
```custom_prefix(parse\s$)
cd ~
pm2 start ecosystem.json
```
@ -495,7 +529,7 @@ At this stage, you should have the following:
- `pm2` managing the `parse-server` process under the **parse** user, and a startup script to restart `pm2` on boot
- `nginx`, secured with the Let's Encrypt certificate, and configured to proxy connections to `https://<^>your_domain_name<^>/parse` to the `parse-server` instance
It should be possible to test reads and writes using `curl`.
It should now be possible to test reads, writes, and cloud code execution using `curl`.
<$>[note]
**Note:** The `curl` commands in this section should be harmless when used with a test or development app. Be cautious when writing data to a production app.
@ -540,19 +574,53 @@ curl -H "X-Parse-Application-Id: <^>your_application_id<^>" https://p1k3.com/par
{"results":[{"objectId":"BNGLzgF6KB","score":1337,"playerName":"Sammy","cheatMode":false,"updatedAt":"2016-02-17T20:53:59.947Z","createdAt":"2016-02-17T20:53:59.947Z"},{"objectId":"0l1yE3ivB6","score":1337,"playerName":"Sean Plott","cheatMode":false,"updatedAt":"2016-02-18T03:57:00.932Z","createdAt":"2016-02-18T03:57:00.932Z"},{"objectId":"aKgvFqDkXh","score":1337,"playerName":"Sean Plott","cheatMode":false,"updatedAt":"2016-02-18T04:44:01.275Z","createdAt":"2016-02-18T04:44:01.275Z"},{"objectId":"zCKTgKzCRH","score":1337,"playerName":"Sean Plott","cheatMode":false,"updatedAt":"2016-02-18T16:56:51.245Z","createdAt":"2016-02-18T16:56:51.245Z"},{"objectId":"YpxFdzox3u","score":1337,"playerName":"Sean Plott","cheatMode":false,"updatedAt":"2016-02-18T18:03:43.188Z","createdAt":"2016-02-18T18:03:43.188Z"}]}
```
## Step 6 – Configure Your App for Parse Server
### Executing Example Cloud Code
A simple POST with no real data to `https://<^>your_domain_name<^>/parse/functions/hello` will run the `hello()` function defined in `/home/parse/cloud/main.js`:
```
curl -X POST \
-H "X-Parse-Application-Id: <^>your_application_id<^>" \
-H "Content-Type: application/json" \
-d '{}' \
https://<^>your_domain_name<^>/parse/functions/hello
```
```
[label Sample Output]
{"result":"Hi"}
```
tk tk tk
If you have instead migrated your own custom cloud code, you can test with a known function from `main.js`.
## Step 7 – Finalize Migration
## Step 6 – Configure Your App for Parse Server and Finalize Migration
tk tk tk
Your next step will be to change your client application itself to use the Parse Server API endpoint. Consult the [official documentation][parse-server-sdks] 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:
![Parse App: Migration Process](https://assets.digitalocean.com/articles/parse_migration/small-004.png)
Click the **Finalize** button:
![Parse Migration Finalization Dialog](https://assets.digitalocean.com/articles/parse_migration/small-005.png)
Your app should now be migrated.
## Conclusion and Next Steps
tk tk tk
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 are not addressed directly by this document.
In addition to reading the official Parse Server documentation and tracking the [GitHub issues for the project](https://github.com/ParsePlatform/parse-server/issues) when troubleshooting, you may wish to explore the following topics:
* [The DigitalOcean New Ubuntu 14.04 Server Checklist](https://www.digitalocean.com/community/tutorial_series/new-ubuntu-14-04-server-checklist)
* [Securing Nginx with Let's Encrypt on Ubuntu 14.04][howto-letsencrypt]
* [Installing Node.js on Ubuntu 14.04](https://www.digitalocean.com/community/tutorials/how-to-install-node-js-on-an-ubuntu-14-04-server)
* [DigitalOcean Droplet Backups](https://www.digitalocean.com/community/tutorials/understanding-digitalocean-droplet-backups)
[env-vars]: https://www.digitalocean.com/community/tutorials/how-to-read-and-set-environmental-and-shell-variables-on-a-linux-vps
[howto-hostname]: https://www.digitalocean.com/community/tutorials/how-to-set-up-a-host-name-with-digitalocean
@ -567,6 +635,7 @@ tk tk tk
[parse-server-example]: https://github.com/ParsePlatform/parse-server-example.git
[parse-server-guide]: https://parse.com/docs/server/guide
[parse-server-guide-migrating]: https://parse.com/docs/server/guide#migrating
[parse-server-sdks]: https://github.com/ParsePlatform/parse-server/wiki/Parse-Server-Guide#using-parse-sdks-with-parse-server
[parse-server]: https://github.com/ParsePlatform/parse-server
[pm2]: http://pm2.keymetrics.io/
[run-parse-server]: https://www.digitalocean.com/community/tutorials/how-to-run-parse-server-on-ubuntu-14-04


+ 85
- 21
index.html View File

@ -16,7 +16,7 @@
<p>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&rsquo;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.</p>
<p>&lt;$>[warning]
<strong>Warning:</strong> 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.
<strong>Warning:</strong> 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 <a href="https://parse.com/docs/server/guide#migrating">official migration documentation</a>.
&lt;$></p>
<h2>Prerequisites</h2>
@ -262,7 +262,14 @@ system.indexes
<p>With your app data in MongoDB, we can move on to installing Parse Server itself, and integrating with the rest of the system. We&rsquo;ll give Parse Server a dedicated user, and use a utility called <strong>PM2</strong> to configure it and ensure that it&rsquo;s always running.</p>
<h3>Create a Dedicated Parse User</h3>
<h3>Install Parse Server and PM2 Globally</h3>
<p>Use <code>npm</code> to install the <code>parse-server</code> utility, the <code>pm2</code> process manager, and their dependencies, globally:</p>
<pre><code class="command">sudo npm install -g parse-server pm2
</code></pre>
<h3>Create a Dedicated Parse User and Home Directory</h3>
<p>Instead of running <code>parse-server</code> as <strong>root</strong> or your <code>sudo</code> user, we&rsquo;ll create a system user called <strong>parse</strong>:</p>
@ -276,16 +283,43 @@ system.indexes
<p>You&rsquo;ll be prompted to enter a password twice.</p>
<h3>Install Parse Server and PM2 Globally</h3>
<p>Now, use the <code>su</code> command to become the <strong>parse</strong> user:</p>
<p>Use <code>npm</code> to install the <code>parse-server</code> utility, the <code>pm2</code> process manager, and their dependencies, globally:</p>
<pre><code class="command">sudo su parse
</code></pre>
<pre><code class="command">sudo npm install -g parse-server pm2
<p>Change to <strong>parse</strong>&rsquo;s home directory:</p>
<pre><code class="custom_prefix(parse\s$)">cd ~
</code></pre>
<h3>Write or Migrate a Cloud Code File</h3>
<p>Create a cloud code directory:</p>
<pre><code class="custom_prefix(parse\s$)">mkdir -p ~/cloud
</code></pre>
<p>Edit <code>/home/parse/cloud/main.js</code>:</p>
<pre><code class="custom_prefix(parse\s$)">nano ~/cloud/main.js
</code></pre>
<p>For testing purposes, you can paste the following:</p>
<pre><code><strong>/home/parse/cloud/main.js</strong><br>
Parse.Cloud.define('hello', function(req, res) {
res.success('Hi');
});
</code></pre>
<p><a href="http://pm2.keymetrics.io/">PM2</a> is a feature-rich process manager, popular with Node.js developers. We&rsquo;ll use the <code>pm2</code> utility to run a simple wrapper script which configures our <code>parse-server</code> instance.</p>
<p>Alternatively, you can migrate any cloud code defined for your application by copying it from the <strong>Cloud Code</strong> section of your app&rsquo;s settings on the Parse Dashboard.</p>
<p>Exit and save.</p>
<h3>Retrieve Keys and Write ecosystem.json</h3>
<h3>Retrieve Keys and Write /home/parse/ecosystem.json</h3>
<p><a href="http://pm2.keymetrics.io/">PM2</a> is a feature-rich process manager, popular with Node.js developers. We&rsquo;ll use the <code>pm2</code> utility to configure our <code>parse-server</code> instance and keep it running over the long term.</p>
<p>You&rsquo;ll need to retrieve some of the keys for your app. In the Parse dashboard, click on <strong>App Settings</strong> followed by <strong>Security &amp; Keys</strong>:</p>
@ -295,7 +329,7 @@ system.indexes
<p>With these keys ready to hand, edit a new file called <code>/home/parse/ecosystem.json</code>:</p>
<pre><code class="command">sudo nano /home/parse/ecosystem.json
<pre><code class="custom_prefix(parse\s$)">nano ecosystem.json
</code></pre>
<p>Paste the following, changing configuration values to reflect your MongoDB connection string, Application ID, and Master Key:</p>
@ -308,7 +342,7 @@ system.indexes
"merge_logs" : true,
"cwd" : "/home/parse",
"env": {
// "PARSE_SERVER_CLOUD_CODE_MAIN": "/home/parse/cloud/main.js",
"PARSE_SERVER_CLOUD_CODE_MAIN": "/home/parse/cloud/main.js",
"PARSE_SERVER_DATABASE_URI": "mongodb://<span style="color: red;">parse</span>:<span style="color: red;">password</span>@<span style="color: red;">your_domain_name</span>:27017/<span style="color: red;">database_name</span>?ssl=true",
"PARSE_SERVER_APPLICATION_ID": "<span style="color: red;">your_application_id</span>",
"PARSE_SERVER_MASTER_KEY": "<span style="color: red;">your_master_key</span>",
@ -333,13 +367,9 @@ system.indexes
<p>Exit and save <code>ecosystem.json</code>.</p>
<p>Now, use the <code>su</code> command to become the <strong>parse</strong> user, and run the script with <code>pm2</code>:</p>
<p>Now, run the script with <code>pm2</code>:</p>
<pre><code class="command">sudo su parse
</code></pre>
<pre><code class="custom_prefix(parse\s$)">cd ~
pm2 start ecosystem.json
<pre><code class="custom_prefix(parse\s$)">pm2 start ecosystem.json
</code></pre>
<pre><code><span style="color: gray;">Sample Output</span><br>
@ -471,7 +501,7 @@ server {
</ul>
<p>It should be possible to test reads and writes using <code>curl</code>.</p>
<p>It should now be possible to test reads, writes, and cloud code execution using <code>curl</code>.</p>
<p>&lt;$>[note]
<strong>Note:</strong> The <code>curl</code> commands in this section should be harmless when used with a test or development app. Be cautious when writing data to a production app.
@ -533,18 +563,52 @@ server {
{"results":[{"objectId":"BNGLzgF6KB","score":1337,"playerName":"Sammy","cheatMode":false,"updatedAt":"2016-02-17T20:53:59.947Z","createdAt":"2016-02-17T20:53:59.947Z"},{"objectId":"0l1yE3ivB6","score":1337,"playerName":"Sean Plott","cheatMode":false,"updatedAt":"2016-02-18T03:57:00.932Z","createdAt":"2016-02-18T03:57:00.932Z"},{"objectId":"aKgvFqDkXh","score":1337,"playerName":"Sean Plott","cheatMode":false,"updatedAt":"2016-02-18T04:44:01.275Z","createdAt":"2016-02-18T04:44:01.275Z"},{"objectId":"zCKTgKzCRH","score":1337,"playerName":"Sean Plott","cheatMode":false,"updatedAt":"2016-02-18T16:56:51.245Z","createdAt":"2016-02-18T16:56:51.245Z"},{"objectId":"YpxFdzox3u","score":1337,"playerName":"Sean Plott","cheatMode":false,"updatedAt":"2016-02-18T18:03:43.188Z","createdAt":"2016-02-18T18:03:43.188Z"}]}
</code></pre>
<h2>Step 6 – Configure Your App for Parse Server</h2>
<h3>Executing Example Cloud Code</h3>
<p>A simple POST with no real data to <code>https://<span style="color: red;">your_domain_name</span>/parse/functions/hello</code> will run the <code>hello()</code> function defined in <code>/home/parse/cloud/main.js</code>:</p>
<p>tk tk tk</p>
<pre><code>curl -X POST \
-H "X-Parse-Application-Id: <span style="color: red;">your_application_id</span>" \
-H "Content-Type: application/json" \
-d '{}' \
https://<span style="color: red;">your_domain_name</span>/parse/functions/hello
</code></pre>
<pre><code><strong>Sample Output</strong><br>
{"result":"Hi"}
</code></pre>
<h2>Step 7 – Finalize Migration</h2>
<p>If you have instead migrated your own custom cloud code, you can test with a known function from <code>main.js</code>.</p>
<p>tk tk tk</p>
<h2>Step 6 – Configure Your App for Parse Server and Finalize Migration</h2>
<p>Your next step will be to change your client application itself to use the Parse Server API endpoint. Consult the <a href="https://github.com/ParsePlatform/parse-server/wiki/Parse-Server-Guide#using-parse-sdks-with-parse-server">official documentation</a> on using Parse SDKs with Parse Server. You will need the latest version of the SDK for your platform. As with the <code>curl</code>-based tests above, use this string for the server URL:</p>
<pre><code>https://<span style="color: red;">your_domain_name</span>/parse
</code></pre>
<p>Return to the Parse dashboard in your browser and the <strong>Migration</strong> tab:</p>
<p><img src="https://assets.digitalocean.com/articles/parse_migration/small-004.png" alt="Parse App: Migration Process" /></p>
<p>Click the <strong>Finalize</strong> button:</p>
<p><img src="https://assets.digitalocean.com/articles/parse_migration/small-005.png" alt="Parse Migration Finalization Dialog" /></p>
<p>Your app should now be migrated.</p>
<h2>Conclusion and Next Steps</h2>
<p>tk tk tk</p>
<p>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&rsquo;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 are not addressed directly by this document.</p>
<p>In addition to reading the official Parse Server documentation and tracking the <a href="https://github.com/ParsePlatform/parse-server/issues">GitHub issues for the project</a> when troubleshooting, you may wish to explore the following topics:</p>
<ul>
<li><a href="https://www.digitalocean.com/community/tutorial_series/new-ubuntu-14-04-server-checklist">The DigitalOcean New Ubuntu 14.04 Server Checklist</a></li>
<li><a href="https://www.digitalocean.com/community/tutorials/how-to-secure-nginx-with-let-s-encrypt-on-ubuntu-14-04">Securing Nginx with Let&rsquo;s Encrypt on Ubuntu 14.04</a></li>
<li><a href="https://www.digitalocean.com/community/tutorials/how-to-install-node-js-on-an-ubuntu-14-04-server">Installing Node.js on Ubuntu 14.04</a></li>
<li><a href="https://www.digitalocean.com/community/tutorials/understanding-digitalocean-droplet-backups">DigitalOcean Droplet Backups</a></li>
</ul>
</body>
</html>

Loading…
Cancel
Save