Cloud Code/Web Hosting

Parse on Buddy supports both Cloud Code and Web Hosting. Cloud Code allows you to upload JavaScript to our service, and then call the JavaScript from a client. Web Hosting gives you the ability to host static files that are accessible via any web browser. Both Cloud Code and Web Hosting files are uploaded to Parse on Buddy using a command-line tool called parse-on-buddy.

Compatibility
There are some incompatibilities between the old Parse.com’s cloud code service and the open-source Parse Server upon which Parse on Buddy is based. They are detailed https://github.com/ParsePlatform/Parse-Server/wiki/Compatibility-with-Hosted-Parse#Cloud-Code. Additionally, there are a few compatibility issues detailed in Overview below. Be sure to make changes to your code accordingly.

Prerequisites


The parse-on-buddy tool depends on NPM, the Node Package Manager distributed with Node.js. Node.js/NPM installation instructions are here.

The tool depends on the following environment variables. Please set them appropriately in your environment before using the tool:

  • BUDDY_PARSE_APP_ID
  • BUDDY_PARSE_MASTER_KEY

For Windows PowerShell, use the following PowerShell commands, entering them one line at a time. Replace {Parse on Buddy App ID} and {Parse on Buddy Master Key} (including the braces { }) with the values from the dashboard, at App Settings -> Security & Keys:

$env:BUDDY_PARSE_APP_ID="{Parse on Buddy App ID}"
$env:BUDDY_PARSE_MASTER_KEY="{Parse on Buddy Master Key}"

 
For Windows cmd.exe, use the following commands, entering them one line at a time. Note that no quotes are used:

set BUDDY_PARSE_APP_ID={Parse on Buddy App ID}
set BUDDY_PARSE_MASTER_KEY={Parse on Buddy Master Key}

 
For MacOS/Linux, use the following commands, entering them one line at a time. Note that no quotes are used:

export BUDDY_PARSE_APP_ID={Parse on Buddy App ID}
export BUDDY_PARSE_MASTER_KEY={Parse on Buddy Master Key}

 

Installation

Open a command shell, and type npm install -g parse-on-buddy.

 

Overview

Directory Structure & main.js
All Cloud Code declarations (that is functions, triggers, or background jobs declarations) must live in a single .js file named main.js, which needs to be in a directory named cloud. Web hosting files need to be in a sibling directory named public. Here is an example directory structure:

.
+-- cloud
| +-- main.js
| +-- myCode.js
| +-- etc.
+-- public
| +-- sample.txt
| +-- etc.

The public directory is required even if you have no web hosting files to upload; it can remain empty.

You invoke the tool from the root of the directory structure, that is the parent directory of cloud and public.

Versions and Uploading
A combined set of cloud code and web hosting files is called a version. Use parse-on-buddy’s --createVersion command to upload the set of files to Parse on Buddy. Be sure to specify a new version number; by default all apps are preconfigured with a sample main.js at version 1, so your first uploaded version will be version 2. The last-added set of files becomes the currently active version. You can also activate older sets using the tool’s --activateVersion command.

If you are migrating from Parse.com, you can run parse-on-buddy --createVersion from the root directory of your current Cloud Code to upload (i.e. create a version). Be sure to specify a new version number. If you are creating a new app, you can use the tool’s --generate command to create cloud & public directories, a sample main.js that you can modify, and a sample web hosting file you can modify or delete. Or you can create the directory structure and main.js file manually. After generation or manual creation use parse-on-buddy --createVersion to upload your new version, specifying a new version number.

Multiple .js files
If you have multiple .js files, and reference them using require(), the default directory has changed from the parent of the cloud directory to the cloud directory itself. As a consequence your require() paths need to change. For example, require("cloud/myCode.js"); needs to be changed to require("./myCode.js");.

Currently you need to reference the Parse Server’s copy of the JavaScript SDK manually at the top of any non-main.js file like so: var Parse = require("parse/node");

Function declarations and references
When you declare your Cloud Code functions, triggers, or jobs, the declarations require a JavaScript function, vs. a reference to the function. For example, rather than this:

function helloFunction(request, response) { response.success("world");
}
Parse.Cloud.define("hello", helloFunction);


you should declare your functions/trigger/jobs with an enclosing function like this:

function helloFunction(request, response) { response.success("world");
}
Parse.Cloud.define("hello", function(request, response) {
helloFunction(request, response);
});

 
JSHint
We highly recommend putting your Cloud Code through a JavaScript linter, like http://jshint.com/ or http://eslint.org/.

JavaScript Dependencies
You can add dependencies by using NPM. At the command line, cd to the cloud directory. Then type npm install <depdendency>, where <dependency> is the name of the dependency as listed at https://npmjs.org. For example, if you want to use Mailgun, type npm install mailgun. This will create a node_modules folder containing the package, which will be automatically uploaded when you create a new version using parse-on-buddy’s --createVersion command. Package.json is optional, but recommended, to make it easier for you to remember which dependencies you are using.

Web Hosting
All the files in the public directory are publicly available at URLs that are of the following format: https://parse.buddy.com/public/{app ID}/{directory structure under the public folder}/{file}. Using the above directory structure example, and a sample app ID of 98d29ee6-0b40-4296-9665-10d36b9ae0ad, the resulting URL would be https://parse.buddy.com/public/98d29ee6-0b40-4296-9665-10d36b9ae0ad/sample.txt.

 

Use

For help, run without arguments:

$ parse-on-buddy
Options
-h, --help
-g, --generate (generates sample directory structure for a new app)
-V, --version (displays version of the CLI tool)
-l, --listVersions
-c, --createVersion number
-a, --activateVersion number
-v, --currentVersion


Here is an example walkthrough:

$ mkdir ExampleParseApp

$ cd ExampleParseApp

# Note that this step is only needed for new apps. If you are migrating, just cd to your local cloud code/web hosting directory.
$ parse-on-buddy --generate
Generating template public and cloud directories…

$ ls -l cloud public
cloud:
total 8
-rw-r--r-- 1 parse staff 89 10 Nov 15:49 main.js

public:
total 8
-rw-r--r-- 1 parse staff 12 10 Nov 15:49 hello.txt

$ cat cloud/main.js
Parse.Cloud.define("hello", function(request, response) { response.success("world"); });

# All apps are initialized with the sample content generated by the --generate switch, with a starting version of 1.
$ parse-on-buddy -l
Listing application versions…
1

$ curl -X POST -H "X-Parse-Application-Id: {Parse on Buddy App ID}" https://parse.buddy.com/parse/functions/hello"
{"result": "world" }

$ curl https://parse.buddy.com/public/{Parse on Buddy App ID}/hello.txt
hello world


Let’s change `main.js` to do something different.

$ cat > cloud/main.js
Parse.Cloud.define("something", function(request, response) { response.success("different"); });

$ parse-on-buddy -c 2
Listing application versions…
Walking local public directory subtree…
Listing existing hash blobs…
1 public assets already synchronized!
Uploading cloud code…
Uploading name → hash mapping…
Setting active version…
All done!$ parse-on-buddy -l
Listing application versions…
1 2

$ parse-on-buddy -v
Fetching current version…
2

$ curl -X POST -H "X-Parse-Application-Id: {Parse on Buddy App ID}" https://parse.buddy.com/parse/functions/something
{ "result": "different" }


Finally, let’s revert to the initial version.

$ parse-on-buddy -a 1
Listing application versions…
Setting active version…$ curl -X POST -H "X-Parse-Application-Id: {your app ID}" https://parse.buddy.com/parse/functions/hello
{ "result": "world" }

 

FAQ

Q. Why do I need a public directory, even if I’m not using web hosting?
A. Due to legacy reasons, an empty `public` directory is necessary.

 

Q. How can I view/verify different versions of cloud code, after uploading?
A. You can use the curl tool to download a .zip that contains your cloud code for any particular version. In the following curl example make sure to replace {Parse on Buddy App ID} with the app ID of your app, {Parse on Buddy App Master Key} with your app’s master key, and {version number} with the specific version of cloud code you’d like to view:

curl -L -o {version number}.zip -H "X-Parse-Application-Id: {Parse on Buddy App ID}" -H "X-Parse-Master-Key: {Parse on Buddy App Master Key}" https://parse.buddy.com/app/cloudcode/{version number}.zip

 

Q. I am trying to query the Installation class, but am receiving an error. Help!
A. In order to query the Installation class, you must pass up your app’s master key with the request.