From NPM #

Deployd modules are 100% compatible with node modules. This means you can install a module with npm from your project's root directory.

cd my-dpd-project
mkdir -p node_modules
npm install my-dpd-module

To find deployd modules available on npm search for dpd.

If you used the Deployd installer, you will need to download node.js in order to use npm.

If you need to use a task manager like Grunt or Gulp for your development environement, you'll have to add a package.json as explained in this page.

From Source #

You can also install a module from source by putting it in your project's node_modules folder. Even a single file is valid (eg: /node_modules/foo.js).

Accessing the Resource #

The API for your Resource is automatically generated as dpd.[resource].

Examples:

dpd.emails
dpd.addfollower
dpd.uploads

Note: If your Resource name has a dash in it (e.g. /add-follower), the dash is removed when accessing it in this way (e.g. dpd.addfollower).

You can also access your resource by using dpd(resourceName) as a function.

Examples:

dpd('emails')
dpd('add-follower')
dpd('uploads')

Callbacks #

Every function in the Dpd.js API takes a callback function (represented by fn in the docs) with the signature function(result, error).

The callback will be executed asynchronously when the API has received a response from the server.

The result argument differs depending on the function. If the result failed, it will be null and the error argument will contain the error message.

The error argument, if there was an error, is an object:

• status (number): The HTTP status code of the request. Common codes include:
  • 400 - Bad Request: The request contained invalid data and could not be completed
  • 401 - Unauthorized: The current session is not authorized to perform that action
  • 500 - Internal Server Error: Something went wrong on the server
• message (string): A message describing the error. Not always present.
• errors (object): A hash of error messages corresponding to the properties of the object that was sent - usually indicates validation errors. Not always present.

Examples of errors:

{
    "status": 401,
    "message": "You are not allowed to access that resource!"
}

{
    "status": 400,
    "errors": {
        "title": "Title must be less than 100 characters",
        "category": "Not a valid category"
    }
}

dpd.todos.post({message: "Hello world"}).then(function(todo) {
    // do something with todo
    console.log(todo); // display {id: "###", message: 'Hello world'}
}, function(err) {
    // do something with the error
    console.log(err); // display an error if the request failed
});

dpd.todos.get('1234324324').then(function(todo) {
    // do something with todo
    console.log(todo); // display {id: "###", message: 'Hello world'}
}, function(err) {
    // do something with the error
    console.log(err.errors.message); // display the error message
});

dpd.[resource].get([func], [path], [query], fn)

dpd.[resource].post([path], [query], body, fn)

dpd.[resource].put([path], [query], body, fn)

dpd.[resource].del([path], [query], fn)

dpd.[resource].exec(func, [path], [body], fn)

Background #

Custom Resources may load event scripts to allow you to inject business logic during requests to the resource. For example, the collection resource exposes an event called validate. Given the following todo resource folder:

/my-app
  /resources
    /todos
      validate.js

The collection resource would load the contents of validate.js as the validate event.

Default Event Script Domain #

Event scripts do not share a global scope with other modules in your app. Instead each time an event script is run, a new scope is created for it.

The following functions and objects are available to all event scripts.

// Example:
if (ctx && ctx.req && ctx.req.headers && ctx.req.headers.host !== '192.168.178.34:2403') {
  cancel("You are not authorized to do that", 401);
}

isMe(id)

cancel(message, [statusCode])

cancelIf(condition, message, [statusCode])
cancelUnless(condition, message, [statusCode])

emit([userCollection, query], message, [data])

Installation #

In your app's root directory, type npm install dpd-email into the command line or download from source. This should create a dpd-email directory in your app's node_modules directory.

See Installing Modules for details.

Configuration #

Before using the email resource, you must go to its Dashboard page and configure it.

These settings are required:

• host: The hostname of your SMTP provider.
• port: The port number of your SMTP provider. Defaults to 25; 587 is also common.
• ssl: If checked, use SSL to communicate with your SMTP provider. Unneeded for port 587; as it will automatically upgrade to a secure connection.
• username: The SMTP username for your app.
• password: The SMTP username for your app.

These settings are optional:

• defaultFromAddress: A "from" email address to provide by default. If this is not provided, you will need to provide this address in every request.
• internalOnly: If checked, only allow internal requests (such as those from events) to send emails. Recommended for security.
• productionOnly: If checked, attempting to send an email in the development environment will simply print it to the Deployd console.

Usage #

To send an email, call dpd.email.post(options, callback) (replacing email with your resource name). The options argument is an object:

• from: The email address of the sender. Required if defaultFromAddress is not configured. All e-mail addresses can be plain (sender@server.com) or formatted (Sender Name <sender@server.com>)
• to: Comma separated list of recipients e-mail addresses that will appear on the To: field
• cc: Comma separated list of recipients e-mail addresses that will appear on the Cc: field
• bcc: Comma separated list of recipients e-mail addresses that will appear on the Bcc: field
• subject: The subject of the e-mail.
• text: The plaintext version of the message
• html: The HTML version of the message

Example Usage #

// On POST /users

dpd.email.post({
  to: this.email,
  from: "deployd-server@example.com", 
  subject: "MyApp registration",
  text: this.username + ",\n\n" +
        "Thank you for registering for MyApp!"
}, function() {});

Installation #

In your app's root directory, type npm install dpd-event into the command line or download the source. This should create a dpd-event directory in your app's node_modules directory.

See Installing Modules for details.

Usage #

The On POST event will be executed when the resource's route (or a subroute) receives a POST request, and likewise with the On GET event.

It is strongly recommended that you reserve the On GET event for operations that return a value, but don't have any side effects of modifying the database or performing some other operation.

If your resource is called /add-follower, you can trigger its POST event from dpd.js:

dpd.addfollower.post('320d6151a9aad8ce', {userId: '6d75e75d9bd9b8a6'}, function(result, error) {
  // Do something
})

And over HTTP:

POST /add-follower/320d6151a9aad8ce
Content-Type: application/json
{
  "userId": "6d75e75d9bd9b8a6"
}

Event API #

In addition to the generic custom resource event API, the following functions and variables are available while scripting the Event resource:

// On GET /top-score
dpd.scores.get({$limit: 1, $sort: {score: -1}, function(result) {
  setResult(result[0]);
});

// On GET /statistics
// Get the top score
if (url === '/top-score') {
  dpd.scores.get({$limit: 1, $sort: {score: -1}, function(result) {
    setResult(result[0]);
  });
}

// On POST /add-score
// Give the specified user (/add-score/:userId) 5 points
var userId = parts[0];
if (!userId) cancel("You must provide a user");

dpd.users.put({id: userId}, {score: {$inc: 5}}, function(result, err) {
  if (err) cancel(err);
});

// On GET /sum
// Return the sum of the a and b properties (/sum?a=5&b=1)

setResult(query.a + query.b);

// On POST /sum
// Return the sum of the a and b properties {a: 5, b: 1}

setResult(body.a + body.b);

Installation #

Create a project. Then install the dpd-importer module.

dpd create my-app
cd my-app
mkdir node_modules
npm install dpd-importer
dpd -d

In your dashboard - click the green new resource button and choose Importer.

Give the new resource the default name "/importer". Open it by clicking "IMPOTER" in the left menu.

Enter the information of your old MongoDB server. Clicking on Start Import will start creating deployd collections from data in the provided db by streaming data directly from the old db into your new deployd db. The importer will do its best to create properties based on the types it infers from your data.

Installation #

In your app's root directory, type npm install s3-bucket-resource into the command line or download the source. This should create a dpd-s3 directory in your app's node_modules directory.

See Installing Modules for details.

Configuration #

Before you can use the S3 Bucket resource, you must set the three properties on its "Config" page:

• bucket: The name of your S3 Bucket
• key: The security key of your S3 Bucket
• secret: The secret key of your S3 Bucket

Usage #

POST /my-bucket/README.txt
Content-Type: text/plain
Hello, world!

200 OK

<form action="/installer-downloads" enctype="multipart/form-data" method="post">
    <input type="file" name="upload" multiple="multiple" />
    <button type="submit">Upload</button>
</form>

GET /my-bucket/README.txt

200 OK
Content-Type: text/plain
Hello, world!

DELETE /my-bucket/README.txt

200 OK

dpd.mybucket.del('README.txt', function(response, error) {
    // Do something
});

Creating an instance of a Custom Resource Type #

Once the module is properly installed, you can add the custom resource just like a Collection. Custom Resources will usually have an asterisk icon.

Note: After adding any module, you will have to restart the Deployd server to see its effects. If you don't see the custom resource type in the list, you may have to restart the server and refresh the dashboard.

Configuring a Custom Resource Type #

See the documentation of your Custom Resource Type module for details on configuration options. Most custom resource types implement a "Config" page and an "Events" page.

The "Config" page can take different forms. For very basic modules, it's often a simple JSON editor where you can enter optional values. Others will list their available configuration values in a form.

The "Events" page is similar to the Collection "Events" page.

Depending on the complexity of the custom resource type, it may have different configuration pages.