[DEPRECATION NOTICE]

This project is no longer under active development or maintenance by Mozilla.

MakeDrive

An offline-first, always available, syncing filesystem for the web. MakeDrive gives web pages and apps a complete filesystem that can be used offline, and also synced with the cloud.

See this blog post which introduces MakeDrive, and demonstrates what it can do.

Any assistance in adding new features or enhancing current ones, as well as resolving issues is greatly appreciated. Please refer to our CONTRIBUTING.md document for more information.

If you have questions or want to help, we are available on irc in the #makedrive channel on moznet.

Compatibility

Desktop Browsers

   Google Chrome: 31+, Android 4.2+ (IndexedDB, WebSQL)

   Mozilla Firefox: 26+, Firefox OS 1.3+ (IndexedDB)

   Opera: 19+ (IndexedDB, WebSQL)

   Safari: 7.0+, iOS 7.x+ (WebSQL)

   Internet Explorer: 10+ (IndexedDB)

Engines/Platforms

• Node.js: v0.10+

MakeDrive Server

Installation and Use

1. Install and run redis, which MakeDrive uses for distributed locks.

2. Clone the MakeDrive repository.

$ git clone https://github.com/mozilla/makedrive.git

3. In your MakeDrive directory, install all of the necessary MakeDrive dependencies:

If you don't already have grunt-cli and bower installed globally, do so:

$ npm install bower -g
$ npm install grunt-cli -g

If you're interested in running the tests, also install Mocha globally:

$ npm install mocha -g

Afterwards, install the npm modules

$ npm install

Next, bower's dependencies

$ bower install

4. Copy the distributed environment file via command line, or manually using a code editor:

$ cp env.dist .env

Many aspects of the server can be altered via the .env file. See env.dist.

5. Run the MakeDrive server at the default log level ('info'):

$ npm start

The server's log level can be set in the environment or the .env file using LOG_LEVEL=* with one of fatal, error, warn, info, debug, trace. If none is given info is used.

You will now have MakeDrive running on localhost via port 9090 - http://localhost:9090

Authentication

MakeDrive uses a swappable authenticaiton mechanism based on Passport.js. Detailed docs are available in the server/authentication directory. A number of Authentication Providers are supplied by default:

To use one of the above providers you can set the environment variable AUTHENTICATION_PROVIDER. For example, using passport-github in env:

export AUTHENTICATION_PROVIDER="passport-github"
export GITHUB_CLIENTID="clientId"
export GITHUB_CLIENTSECRET="clientSecret"
export GITHUB_CALLBACKURL="http://callbackurl"

You can also check other providers listed in the providers directory for more information.

Filer Data Provider

MakeDrive needs to store user filesystem data in some kind of data store. Filesystem data is stored as key/value pairs, representing blocks and nodes in a POSIX filesystem (see Filer for more details).

MakeDrive uses Filer for all filesystem features, and can therefore use any Filer Data Provider. The provider is configured in the env using the FILER_PROVIDER variable.

By default MakeDrive uses filer-fs and the server's filesystem to store data. This solution won't scale, since you can't share data across multiple instances of MakeDrive, but is useful for development.

Other providers are also available, or can be easily written:

• filer-sql - Supports MySQL, MariaDB, SQLite, and PostgreSQL via Sequelize.
• filer-s3 - Supports Amazon S3 storage

HTTP Routes

MakeDrive has various HTTP REST endpoints for retrieving user filesystem data in different formats. All of these routes require authentication and are not meant for public use, but for users and apps to allow easy access to data when logged in. Each one is accessed by simply being appended to the URL that presently hosts MakeDrive (eg. https://localhost:9090/p/):

  /api/sync - Used to initiate a sync session by a client (not meant for users/browsers).
  /p/* - Serves as a path for a user's Filer filesystem. You can currently view anything that has been synced inside of the user's project directory tree.
  /j/* - Similar to the /p/ route, but serves the path information in JSON format for APIs.
  /z/* - Used to export the current user's project data in compressed ZIP format.
  /s/:username - Similar to the /p/ route, but meant for server-to-server HTTP access and requiring HTTP BASIC AUTH. Disabled by default, but can be enabled by adding a "username:password" pair to the .env file for the BASIC_AUTH_USERS variable.
  /images - Provides an image gallery of all images contained anywhere in a user's filesystem.

All routes can be enabled or disabled via the env.dist file.

MakeDrive Client

Built on top of the Filer filesystem interface, MakeDrive adds cloud-like syncing functionality that allows for multiple clients to share and interact with an active project directory from different browsers or platforms. There are features and options for both manual and auto syncing.

Below is a simple way to create and initiate a MakeDrive instance in client-side code:

var fs = MakeDrive.fs();

Multiple calls to MakeDrive.fs() will return the same instance.

API Reference

####Constructor

var fs = MakeDrive.fs({
  manual: true,
  memory: true,
  forceCreate: true
  // etc.
});

A number of configuration options can be passed to the fs() function. These include:

Various bits of Filer are available on MakeDrive, including:

MakeDrive.Buffer
MakeDrive.Path
MakeDrive.Errors

See Filer's docs for more information.

MakeDrive Instance Methods

Events

The filesystem instance returned by MakeDrive.fs() includes the property sync. The fs.sync property is an EventEmitter which emits the following events:

Sync

The sync property also exposes a number of methods, including:

Finally, the sync property also exposes a "state", which is the current sync state and can be one of:

 sync.SYNC_DISCONNECTED = "SYNC DISCONNECTED" /* also the initial state */
 sync.SYNC_CONNECTING = "SYNC CONNECTING"
 sync.SYNC_CONNECTED = "SYNC CONNECTED"
 sync.SYNC_SYNCING = "SYNC SYNCING"
 sync.SYNC_ERROR = "SYNC ERROR"

MakeDrive Client Logging

MakeDrive provides various levels of logging. By default it is disabled, but it can be enabled using MakeDrive.log.level():

// Use debug logging
MakeDrive.log.level('debug');

// Use info logging
MakeDrive.log.level('info');

// Disable logging after it was turned on
MakeDrive.log.level('disabled');

In addition to using level name strings, you can use MakeDrive.log.INFO, MakeDrive.log.DEBUG, MakeDrive.log.WARN, MakeDrive.log.ERROR, etc.

Developer Demo

An independent and lightweight front-end instance has been added to test MakeDrive's functionality on its own. The NODE_ENV variable must be set to development in your .env file for this page to be enabled. It currently resides on and can be visited at localhost:9090/demo/?makedrive=ws://localhost:9090.

NOTE: For connecting the demo with another MakeDrive server, the localhost address and port of the above demo page must be added to the ALLOWED_CORS_DOMAINS variable in the .env file of the instance you are trying to connect to in order to avoid cross-origin resource errors.