Cozy

Related articles

• Synchronization and backup programs

Cozy is a personal cloud platform free, and self-hostable, written in Go (the former version, v2, was written in Node.js instead).

The platform aims at simplifying the use of a personal cloud and at allowing the users to take back ownership of their privacy. Its base applications’ features include hosting, sharing and synchronising files & pictures and collecting your data from several providers. Some other apps are on the roadmap, like a contacts manager and a calendar.

Third-party apps will also be available through a marketplace soon.

Installation

Install the cozy-stack package. It provides the core plus related configuration files, as well as the minimum required dependencies.

You might also want to install nsjail to run Konnectors in isolated environments, as well as an SMTP server to let Cozy send emails to your users.

Configuration

Almost everything happens in /etc/cozy/cozy.yml. Some defaults are already set, while some placeholders will be replaced during configuration. You can also find an example file at /usr/share/cozy/cozy.example.yaml.

Configuring CouchDB

Cozy stores everything (but actual files) in a CouchDB database, and needs a CouchDB administrator to manage this database. This administrator’s credentials must be specified as part of the couchdb url setting in /etc/cozy/cozy.yml so that Cozy can use them. The following supposes you have a running CouchDB instance, if not you can follow the corresponding wiki page to setup one as single node.

You can generate the credentials with pwgen for example. Once you have them (couch_user and couch_password), edit your configuration as follow:

/etc/cozy/cozy.yml

couchdb:
  url: http://<couch_user>:<couch_password>@localhost:5984/

And register them to CouchDB (replace <couchdb_admin> and <couchdb_password> with your CouchDB admin credentials):

$ curl -X PUT http://<couchdb_admin>:<couchdb_password>@127.0.0.1:5984/_node/<node_name>/_config/admins/<couch_user> -d "\"<couch_password>\""

You can retrieve the correct node name with:

$ curl -X GET http://<couchdb_admin>:<couchdb_password>@127.0.0.1:5984/_membership

Configuring Cozy admin password

Cozy itself requires an admin password for all operations at the stack level. Create it like this:

$ sudo -u cozy cozy-stack config passwd /etc/cozy/cozy-admin-passphrase

You will be prompted to enter a passphrase.

Creating vault keys

Cozy uses a vault to store some user passwords. To create the vault keys with right ownership and permissions, just proceed like this:

$ sudo -u cozy cozy-stack config gen-keys /etc/cozy/vault

Starting the stack

At this point, you should Start/Enable the cozy-stack.service daemon.

You can check everything is right by running:

$ curl http://localhost:8080/version

Creating an instance

To add an instance (you will be prompted for your Cozy admin password, you might also pass it using COZY_ADMIN_PASSWORD env var):

$ cozy-stack instances add <instance>.example.tld --apps home,settings,store

This will output you a registration token. You can also specify an email using --email <address> at which the registration token will be sent (this require having set a smtp server in /etc/cozy/cozy.yml).

You will then need to visit https://<instance>.example.tld/?registerToken=<token>, which requires you to have setup a reverse proxy (see below).

Reverse proxying

As a security measure, Cozy needs to be served over HTTPS, which means it needs a reverse proxy in front of it. This can managed by either a proxying software like HAproxy or a webserver such as Apache HTTP Server, nginx or Caddy.

Cozy needs a full domain name for the instance (something like <instance>.example.tld) and use one domain name per application, in the form of <app>.<instance>.example.tld.

Thus, you have to setup your domain zone with something like this:

   <instance> 1h IN A x.x.x.x
   *.<instance> 1h IN CNAME <instance>

You will also need SSL certificates, either a wildcard one covering *.<instance>.example.tld and <instance>.example.tld or a certificate for <instance>.example.tld with apps domains added as SAN. Currently, the list of apps is: onboarding, settings, drive, photos, and collect. However, this may grow over time, so you could have to expand your certificate. Thus, getting a wildcard one is advised.

Below is an example configuration file for nginx.

nginx

/etc/nginx/sites-available/<instance>.conf

# Always redirect http:// to https://
server {
    listen 80;
    server_name .<instance>.example.tld <instance>.example.tld;

    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    listen [::]:443 ssl http2;
    server_name .<instance>.example.tld <instance>.example.tld; 

    ssl_certificate /etc/cozy/<instance>.crt;
    ssl_certificate_key /etc/cozy/<instance>.key;

    client_max_body_size 1g;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_http_version 1.1;
        proxy_redirect http:// https://;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header Host $http_host;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
    }

    access_log /var/log/nginx/<instance>.log;
    error_log /var/log/nginx/<instance>.error.log;
}

Note: Do not forget to symlink /etc/nginx/sites-available/<instance>.conf in /etc/nginx/sites-enabled!