NAV
JavaScript

Introduction

Welcome to the Cozy Developer Space.

Here you will find everything you need to understand Cozy technically and to develop applications and konnectors.

The technical level required to read and understand this documentation is not over 9,000; you will roughly have to:

console.log(" ╰(◕‿◕)╯ ");

Why & How we made Cozy

Home Screenshot

Cozy is a personal web deployment platform, which enables you to quickly bootstrap applications and interact with your data. It stands on a server - between your application and the operating system - easing the pain of system administration, web development and security. Get your data back home!

Data-oriented

The initial idea was to create a space where developers can experiment and play with their data, while remaining in control of the platform. A friendly centralized point to fetch data from Things-Of-Internet, devices and personal services.

Cloud Connected

More than a simple Platform-as-a-Service, Cozy puts the cloud back where it belongs: at home.

Find out more on the Architecture section

Tools

Cozy also became our daily working environment, and we want it to be as comfortable as possible. It means that we require it to be flexible, extensible and usable. We use Node.js and CouchDB as our main technologies.

Node JS

Node.js is a great and modern engine with a huge community of module creators. It has evolved along with the GitHub’s Open-Source popularization and is now wide-spread in the Web industry. Aside from being heavily maintained, it remains fun to extend and play with.

CouchDB

CouchDB is surely less-known, but definitely reliable. As a proper Erlang program, it has proven its strength and stability. A consistent, well-documented API, plus wonderful replication capabilities: the recipe of what we love of a database engine.

Developing with Cozy

Cozy has been a great opportunity for me to start coding. Now I run a decent business.Bill Getas - Startup entrepreneur

Thanks to Cozy, I successfully managed to build a working web application without a hassle.Tim Bernee-Lers - enthusiast web developer

I’m sorry Dave, I’m afraid I can’t do that.HAL 9000 - CoffeeScript compiler

But to be honest, we don’t need these fancy references to convince you to develop on Cozy.

To the future, Marty!

Cozy is a modern web platform that abstracts a lot of complexity out of personal data manipulation. If you are planning on developing a tool to fetch, visualize or mix data, a Cozy Application or a Konnector may be a good way to start.

By developing on Cozy, you will:

And whatever the reason, you will always find a friendly team member to help you dealing with your struggles and questions on the IRC channel.

So let’s dive into it!

Getting Started

This section is a quick tutorial showing the different steps to start using Cozy as a development environment, making a simple app, and interact with your data.

Set up the Development Environment

Since Cozy is made from several pieces, we wrapped it into an easy-to-use Virtual Machine, so you don’t clutter your local system. This also means you can use the operating system you like! Well, there are obviously issues on Windows, so we will assume here that you use a GNU/Linux system or Mac OS X.

The environment is made of two parts: the Virtual Machine itself - a fully installed Cozy platform - and a local Node.js tool called cozy-dev which will help you getting started and deploying your app to your Cozy.

1. Install Git

On GNU/Linux, just install Git with your package manager

apt-get install git

On Mac OS, download the software here:
http://git-scm.com/download/mac

# To check if Git is installed
git --version

The first step is obviously to install the development dependencies. Git is the SCM we use at Cozy, and if you don’t know how to use it yet, don’t worry: we will give example commands in the following tutorial.

2. Install Node.js

On Debian GNU/Linux Jessie, one of the proper version of Node.js (0.10.29) is available in the official repositories

apt-get install nodejs nodejs-legacy npm

On other GNU/Linux systems, you can install Node.js manually by following instructions from https://nodejs.org/en/download/package-manager/

On Mac OS X, simply download the package, and install it
https://nodejs.org/dist/v4.3.0/node-v4.3.0.pkg

# To check the Node.js version
node --version

Installing Node.js on your local environment is necessary to run your app and use cozy-dev. Cozy runs well on Node.js v0.10 and Node.js 4.3, and you should install one of those versions.

You can find detailed instructions of installation on the official page.

3. Install VirtualBox and Vagrant

VirtualBox is used to emulate a full Operating System in a Virtual Machine. You can download it from The Virtualbox website. Make sure you have the latest version installed!

Vagrant is a Command-Line Interface to interact with VirtualBox and handle development environment easily. You can download it from The Vagrant website. Make sure you have the latest version installed!

4. Install cozy-dev

# Use the -g option to install system-wide
sudo npm install -g cozy-dev

As mentionned above, cozy-dev is a set of tools aiming to help you managing your app deployment and your development environment. It is recommended to install it system-wide.

The full documentation of cozy-dev can be found below on the related section.

5. Download and start the environment

# Create a development directory
mkdir cozy && cd cozy

# Download the environment
cozy-dev vm:init

# Start the environment
cozy-dev vm:start

# Check that the environment is properly started
cozy-dev vm:status

# Update the environment (strongly recommended)
cozy-dev vm:update

Use cozy-dev to initialize the environment. It is recommended to update it at the end because we do not necessarily maintain the raw image in an up-to-date state, as a new version of Cozy can be released every couple of weeks ☺

Introduction to Cozy Cloud architecture

Before writing code, let’s have an overview of the Cozy Cloud architecture. The platform is made of 3 main components:

The Cozy Cloud architecture is detailed in a specific part.

Write your own application

From this point onward, you have a choice to make:

Client-side application

If you want to make a simple app that only manipulates data inside the Cozy (no sharing, no accessing an external API), head over to the Client-side apps section.

Node.js application

If you want to make a powerful app using node.js, which manipulates files, accesses remote APIs or allows access to a cozy visitor with complex rules, go to the Node.js app.

Understanding the platform

Architecture and Components

Understanding how the platform is built is essential to be able to work with it.

The following figure displays the different parts of Cozy, that we are going to describe.

Cozy platform

Cozy is made of three main components: a persistent layer, the Data System, the personal Platform as a service and the platform interface.

The Data System

Gihub repository

Personal data is at the core of Cozy, therefore the Data System is the central piece of Cozy where all your data is safely stored and ready to be used.

The Data System is a unified API which consists of: - the database itself, CouchDB, where all your personal data and Cozy data is stored as document, each document having a type depending on the data it contains (a contact, an email, a setting) - binaries, stored in CouchDB too, that in particular allow to authenticate and authorize requests made by Cozy so that resources (apps for example) can only access the document types they are allowed to access - the indexer

It is important to emphasize here that the Data System owns the data, and decides whether the requests made by the Cozy platform are allowed or not.

You can find the complete API and details about the Data System on the dedicated cookbook.

The pPaas

Github repository

The personal Platform as a service, or pPaas, is an execution environment for applications collaborating around personal data. It consists mainly of the Controller, which installs, runs, updates and removes applications within Cozy. You can call the Controller using the Home, which is itself an application installed by the Controller. There is also a command line interface, cozy-monitor, that allows you to call the Controller if you have root privileges on your server.

Making the most of the Data System using applications

The Controller therefore manages applications. These applications will store their data in the Data System. As we have seen, the Data System, not the application, owns the data. Therefore, when installing or updating an application, the user will be prompted to grant the application access to certain document types. This paradigm enables easy and straightforward collaboration between the applications: granting access to the “Contact” document type to both the Contacts application and the Emails one will allow to send an message in Emails to someone the user will have informed the contact details in Contacts. And this is a common, nearly boring example, but it can be done with any document type and any data!

Moreover, uninstalling or breaking an application will not erase your data, you will be able to recover it.

The platform interface

The platform interface consists of the Home (Gihub repository) and the Proxy (Gihub repository).

As we have seen above, Home is an interface to the Controller which allows the user to manage applications in Cozy.

Up to now, we have seen that the Data System owns the data, that the Controller can manage applications and that applications can interact with data in the Data System. How can the user access all this data? The Proxy will enable it, and is the last part of the Cozy platform. It handles authentication and authorization in Cozy. It manages registration, login, logout and password reset. It also handles all the routing of Cozy (to send the right request to the right application).

If you want to learn more about authentication and authorization in Cozy, there is a dedicated cookbook on the subject.

What you should remember

As a developer, you are going to create an application that will be run by Cozy’s pPaaS. That application will access the data through the Data System. Also, you won’t have to bother with user authentication and authorization because it is all handled by the Proxy.

Keep in mind you’re developing for a personal environment. It might be something you are not used to at first. It changes the relationship to data we had until now!

With these three presentations, you have a clear view on the architecture of the Cozy platform, and we will now details a bit more several subjects.

Authentication and permissions

We haven’t moved all the resources to the new documentation website. For the time being, we advise you to check the old documentation website.

Encryption management

We haven’t moved all the resources to the new documentation website. For the time being, we advise you to check the old documentation website.

Konnectors

Konnectors is an application that allows small module of code to retrieve data from the outside world like invoices, activity tracker, or whatever you want. It is actively developed and maintained by the community, and generally a good way to start coding for Cozy: you write a piece of application, not a complete application.

You can find the documentation to write a connector on the repository’s wiki.

Sharing data between Cozy

We’ve been working on a protocol to share data between Cozy. It’s still a work in progress, but the relevant documentation can be found here.

References

You can find the old documentation here.

Data System API

We haven’t moved all the resources to the new documentation website. For the time being, we advise you to check the old documentation website.

Cozy DB API

We haven’t moved all the resources to the new documentation website. For the time being, we advise you to check the old documentation website.

Cozy Browser SDK

It’s the same as cozy-db, except for the browser so you can directly interact with the data-system from there. You will find the documentation here.

Devices API

If you want to build an application that is not run by Cozy, like a mobile or a desktop application, you can use the Devices API to manage authentication. You will find the documentation here.

Cozy Development Environment

We haven’t moved all the resources to the new documentation website. For the time being, we advise you to check the old documentation website.

Cozy Desktop

If you’d like to get technical documentation on cozy-desktop, you can find it here.

Controller API

We haven’t moved all the resources to the new documentation website. For the time being, we advise you to check the old documentation website.

You can also check the configuration documentation if you’d like to understand how to play with it.

Main document types

All Cozy apps produce many data as JSON document that can be reused in your own application. The main document types available are the following ones:

Doc Type Main Fields
BankOperation title, date, amount
Bill type, vendor, date, amount
BloodPressure systolic, diastolic
Bookmark title, url, tag
Commit sha, parent, tree, url, author, email, message, additions, deletions, files
Contact datapoints, n, fn, org, title, bday, department
Event start, end, description, place, rrule
File name, path, class, lastModification, creationDate, size, mime, checksum
Folder name, path, lastModification, creationDate
Email headers, from, to, cc, bcc, replyTo, subject, text, html, date, attachments, inReplyTo
Note title, content, creationDate, lastModificationDate
Photo title, description, orientation, binary
Sleep deepSleepDuration, lightSleepDuration, sleepDuration
Steps distance, steps
UseTracker dateStart, dateEnd, duration, app
Weight weight, leanWeight, fatWeight
Tasky creationDate, completionDate, description, tags

Getting help

IRC

You can find help from the team or from a loving member of our community on irc.freenode.net, channel #cozycloud. You can use the webchat if you like!

Forum

Our community is quite active on our forum, mostly users willing to report bugs or ask for features. As a developer, no doubt you will get constructive feedbacks if you ask there!

Email

You can always contact the team by sending an email at contact[at]cozycloud.cc.

GitHub

You will find all the repositories under the cozy organization and the cozy-labs organization.

Mentorship

We have a special mentoring program for developers looking for help! A member of Cozy’s team will spend 2 hours a week with you to help you developing your application! You can find all the details here.