Cozy - ArchWiki

# Cozy

From ArchWiki
Jump to navigation Jump to search
The printable version is no longer supported and may have rendering errors. Please update your browser bookmarks and please use the default browser print function instead.

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

This article or section needs expansion.

Reason: Mention cozy-desktop. (Discuss in Talk:Cozy#)

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.yaml

    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`!
Category:

- File sharing

Hidden category:

- Pages or sections flagged with Template:Expansion