A client implementation for Rackspace CloudFIles in node.js
Clone or download
Pull request Compare This branch is 10 commits ahead, 43 commits behind nodejitsu:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.



A client implementation for Rackspace CloudFiles in node.js


Installing npm (node package manager)

  curl http://npmjs.org/install.sh | sh

Installing node-cloudfiles

  npm install cloudfiles

Getting Rackspace Account


The node-cloudfiles library is compliant with the Rackspace CloudFiles API. Using node-cloudfiles is easy for a variety of scenarios: authenticating, creating and working with both containers and storage objects.

Getting Started

Before we can do anything with cloudfiles, we have to create a client with valid credentials. Cloudfiles will authenticate for you automatically:

  var cloudfiles = require('cloudfiles');
  var config = {
    auth : {
      username: 'your-username',
      apiKey: 'your-api-key'
  var client = cloudfiles.createClient(config);

Working with Containers

Rackspace Cloudfiles divides files into 'Containers'. These are very similar to S3 Buckets if you are more familiar with Amazon. There are a couple of simple operations exposed by node-cloudfiles:

  // Creating a container
  client.createContainer('myContainer', function (err, container) {
    // Listing files in the Container 
    container.getFiles(function (err, files) {

Uploading and Downloading Files

Each Container has a set of 'StorageObjects' (or files) which can be retrieved via a Cloudfiles client. Files are downloaded to a local file cache that can be configured per client.

  // Uploading a file
  client.addFile('myContainer', 'remoteName.txt', 'path/to/local/file.txt', function (err, uploaded) {
    // File has been uploaded
  // Downloading a file
  client.getFile('myContainer', 'remoteName.txt', function (err, file) {
    // File has been downloaded
    // Save it to a location outside the cache
    file.save({ local: 'path/to/local/file.txt' }, function (err, filename) {
      // File has been saved.

Authentication Service

Use the 'host' key in the auth configuration to specify the url to use for authentication:

  var cloudfiles = require('cloudfiles');
  var config = {
    auth : {
      username: 'your-username',
      apiKey: 'your-api-key',
      host : "lon.auth.api.rackspacecloud.com"
  var client = cloudfiles.createClient(config);


  1. Implement Storage Object metadata APIs.

Run Tests

All of the node-cloudservers tests are written in vows, and cover all of the use cases described above. You will need to add your Rackspace API username and API key to test/data/test-config.json before running tests:

    "auth": {
      "username": "your-username",
      "apiKey": "your-apikey"

Once you have valid Rackspace credentials you can run tests with vows:

  vows test/*-test.js --spec

Author: Charlie Robbins

Contributors: Fedor Indutny, aaronds