Difference between revisions of "Cozy"

From ArchWiki
Jump to navigation Jump to search
(Full rewrite for Cozy v3.)
Line 5: Line 5:
 
{{Related articles end}}
 
{{Related articles end}}
  
[https://cozy.io Cozy] is a personal cloud platform free, and self-hostable, written in [[Node.js]] (the future version, v3, will be written in [[Go]] instead).
+
[https://cozy.io 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, contacts and calendars, along with an email client.
+
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 are available through a marketplace and can be used to extend Cozy's default features, with task management, blog hosting, bank account overview, etc.
+
Third-party apps will also be available through a marketplace soon.
  
 
== Installation ==
 
== Installation ==
  
Just install the {{AUR|cozy}} package. It provides the core (cozy-controller and cozy-monitor) plus related configuration files, as well as the required dependencies.
+
Install the {{pkg|cozy-stack}} package. It provides the core plus related configuration files, as well as the minimum required dependencies.
  
{{Note|This will install Node.js version 4.x provided by {{Pkg|nodejs-lts-argon}}. While Cozy '''may''' totally work with newer versions (e.g. 6.x, 8.x), they are not officially supported, as Cozy officially supports only Node.js v4.x.
+
You might also want to install {{pkg|nsjail}} to run Konnectors in isolated environments, as well as an SMTP server to let Cozy send emails to your users.
If you still want to use the Node.js version currently in Archlinux's official repository, you will need to change the dependency in the PKGBUILD.}}
 
  
=== Pre-configuration ===
+
== Configuration ==
  
You will need to add two users accounts manually:
+
Almost everything happens in {{ic|/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 {{ic|/usr/share/cozy/cozy.example.yaml}}.
 
 
# useradd -MU cozy-data-system
 
# useradd -MU cozy-home
 
  
 
=== Configuring CouchDB ===
 
=== Configuring CouchDB ===
  
We will now configure the database. Cozy stores almost everything in a [[CouchDB]] database, and needs a CouchDB administrator to manage this database. This administrator’s credentials must be specified as part of the {{ic|couchdb url}} setting in {{ic|/etc/cozy/cozy.yml}} so that Cozy can use them. This suppose you have a running [[CouchDB]] instance, you can follow the corresponding wiki page to setup one in single node mode.
+
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 {{ic|couchdb url}} setting in {{ic|/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 {{pkg|pwgen}} for example. Once you have them ({{ic|couch_user}} and {{ic|couch_password}}), edit your configuration as follow:
 
You can generate the credentials with {{pkg|pwgen}} for example. Once you have them ({{ic|couch_user}} and {{ic|couch_password}}), edit your configuration as follow:
 
{{hc|/etc/cozy/cozy.yaml|2=
 
{{hc|/etc/cozy/cozy.yaml|2=
 
couchdb:
 
couchdb:
   url: http://<couch_user>:<couch_password>@127.0.0.1/
+
   url: http://<couch_user>:<couch_password>@localhost:5984/
 
}}
 
}}
  
 
And register them to CouchDB (replace {{ic|<couchdb_admin>}} and {{ic|<couchdb_password>}} with your CouchDB admin credentials):
 
And register them to CouchDB (replace {{ic|<couchdb_admin>}} and {{ic|<couchdb_password>}} with your CouchDB admin credentials):
  
  # curl -X PUT <couchdb_admin>:<couchdb_password>@127.0.0.1:5984/_node/couchdb@localhost/_config/admins/<couch_user> -d "\"<couch_password>\""
+
  $ curl -X PUT http://<couchdb_admin>:<couchdb_password>@127.0.0.1:5984/_node/couchdb@localhost/_config/admins/<couch_user> -d "\"<couch_password>\""
 
 
=== Starting the controller ===
 
 
 
Cozy needs its controller (cozy-controller) up and running in order to work. As it is supposed to run as a background task, it is better to run it in systemd.
 
The service file is provided by the package, and has couchdb in its dependencies so that starting/enabling cozy-controller.service is enough.
 
 
 
=== Installing the Cozy stack ===
 
  
You can now use cozy-monitor to install and start each component of Cozy's base stack:
+
=== Configuring Cozy admin password ===
  
  # cozy-monitor install-cozy-stack
+
Cozy itself requires an admin password for all operations at the stack level.
 +
Create it like this:
 +
  # cozy-stack config passwd /etc/cozy/cozy-admin-passphrase
 +
You will be prompted to enter a passphrase.
 +
Then fix the ownership:
 +
# chown cozy:cozy /etc/cozy/cozy-admin-passphrase
  
=== Configuring ===
+
=== Starting the stack ===
  
Cozy will now need some basic configuration, in order to know the homepage's background and on which domain it will be accessed by the user.
+
At this point, you should [[Systemd#Using units|Start/Enable]] the {{ic|cozy-stack.service}} daemon.
  
==== Configuring the domain ====
+
You can check everything is right by running:
 +
$ curl http://localhost:8080/version
  
# coffee /var/lib/cozy/apps/home/commands.coffee setdomain <your domain>
+
== Creating an instance ==
  
{{Note|Because of the way it works, it is recommended to use a whole domain (or sub-domain) for Cozy, such as {{ic|cozy.example.tld}}.}}
+
To add an instance (you will be prompted for your Cozy admin password, you might also pass it using COZY_ADMIN_PASSWORD env var):
  
==== Configuring the background ====
+
$ cozy-stack instances add <instance>.example.tld --apps onboarding,settings,drive,photos,collect
  
# curl -X POST http://localhost:9103/api/instance -H "Content-Type: application/json" -d '{"background":"background-07"}'
+
This will output you a registration token. You can also specify an email using {{ic|--email <address>}} at which the registration token will be sent.
  
{{Note|This setting can be changed at any time in the "Settings" page in the Cozy instance.}}
+
You will then need to visit {{ic|1=https://<instance>.example.tld/?registrationToken=<token>}}, which requires you to have setup a reverse proxy (see below).
  
== Reverse proxying ==
+
=== 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]], [[nginx]] or [https://caddyserver.com/ Caddy].
 
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]], [[nginx]] or [https://caddyserver.com/ Caddy].
  
You will also need SSL certificates, either self-signed or provided by a trusted authority.
+
Cozy needs a full domain name for the instance (something like {{ic|<instance>.example.tld}}) and use one domain name per application, in the form of {{ic|<app>.<instance>.example.tld}}.
  
Below are example configuration files for some common web servers.
+
Thus, you have to setup your domain zone with something like this:
  
=== Apache ===
+
    <instance> 1h IN A x.x.x.x
 +
    *.<instance> 1h IN CNAME <instance>
  
{{hc|1='''/etc/httpd/conf/extra/cozy.conf'''|2=<IfModule mod_ssl.c>
+
You will also need SSL certificates, either a wildcard one covering {{ic|*.<instance>.example.tld}} and {{ic|<instance>.example.tld}} or a certificate for {{ic|<instance>.example.tld}} with apps domains added as SAN.
<VirtualHost *:443>
+
Currently, the list of apps is: onboarding,settings,drive,photos,collect.
        ServerName      cozy.example.tld
+
But this will grow over time, so you will have to expand your certificate regularly.
        ServerAdmin    admin@server
+
Thus, getting a wildcard one is advised.
  
        SSLEngine              On
+
Below is an example configuration file for nginx.
        SSLCertificateFile      /etc/cozy/server.crt
 
        SSLCertificateKeyFile  /etc/cozy/server.key
 
  
        RewriteEngine          On
+
==== nginx ====
        RewriteCond            %{REQUEST_URI} ^/.*socket\.io [NC]
 
        RewriteCond            %{THE_REQUEST} websocket [NC]
 
        RewriteRule            /(.*)          ws://127.0.0.1:9104/$1 [P,L]
 
  
        ProxyPass              / http://127.0.0.1:9104/ retry=0 Keepalive=On timeout=1600
+
{{hc|1='''/etc/nginx/sites-available/<instance>.conf'''|2=
        ProxyPassReverse        / http://127.0.0.1:9104/
 
        setenv proxy-initial-not-pooled 1
 
  
        CustomLog              /var/log/apache2/cozy-access.log "%t %h %{SSL_PROTOCOL}x %{SSL_CIPHER}x \"%r\" %b"
+
# Always redirect http:// to https://
        ErrorLog                /var/log/apache2/cozy-error.log
+
server {
 +
    listen 80;
 +
    server_name .<instance>.example.tld <instance>.example.tld;
  
</VirtualHost>
+
    return 301 https://$host$request_uri;
 +
}
  
<VirtualHost *:80>
+
server {
        ServerName      cozy.example.tld
+
    listen 443 ssl http2;
        ServerAdmin    admin@server
+
    listen [::]:443 ssl http2;
 +
    server_name .<instance>.example.tld <instance>.example.tld;
  
Redirect permanent / https://cozy.example.tld/
+
     ssl_certificate /etc/cozy/<instance>.crt;
 
+
     ssl_certificate_key /etc/cozy/<instance>.key;
</VirtualHost>
 
</IfModule>}}
 
 
 
=== nginx ===
 
 
 
{{hc|1='''/etc/nginx/cozy.conf'''|2=server {
 
    listen 443;
 
 
 
    server_name cozy.example.tld;
 
 
 
     ssl_certificate /etc/cozy/server.crt;
 
     ssl_certificate_key /etc/cozy/server.key;
 
    ssl_dhparam /etc/cozy/dh.pem;
 
    ssl_session_cache shared:SSL:10m;
 
    ssl_session_timeout 10m;
 
    ssl_prefer_server_ciphers on;
 
    ssl on;
 
 
 
    gzip_vary on;
 
    client_max_body_size 1024M;
 
 
 
    add_header Strict-Transport-Security max-age=2678400;
 
  
 
     location / {
 
     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 X-Forwarded-For $proxy_add_x_forwarded_for;
 
         proxy_set_header Host $http_host;
 
         proxy_set_header Host $http_host;
        proxy_redirect http:// https://;
 
        proxy_pass http://127.0.0.1:9104;
 
        proxy_http_version 1.1;
 
 
         proxy_set_header Upgrade $http_upgrade;
 
         proxy_set_header Upgrade $http_upgrade;
         proxy_set_header Connection "upgrade";
+
         proxy_set_header Connection $connection_upgrade;
 
     }
 
     }
  
     access_log /var/log/nginx/cozy.log;
+
     access_log /var/log/nginx/<instance>.log;
}
+
    error_log /var/log/nginx/<instance>.error.log;
 
 
# Always redirect http:// to https://
 
server {
 
    listen 80;
 
    server_name cozy.example.tld;
 
 
 
    return 301 https://$host$request_uri;
 
 
}
 
}
 
}}
 
}}
  
{{Note|Do not forget to include {{ic|/etc/nginx/cozy.conf}} in {{ic|/etc/nginx/nginx.conf}}!}}
+
{{Note|Do not forget to symlink {{ic|/etc/nginx/sites-available/<instance>.conf}} in {{ic|/etc/nginx/sites-enabled}}!}}
 
 
=== Caddy ===
 
 
 
{{hc|1='''/etc/caddy/Caddyfile'''|2=cozy.example.tld {
 
    tls admin@server
 
    proxy / 127.0.0.1:9104 {
 
        transparent
 
        websocket
 
    }
 
}
 
}}
 
 
 
== Troubleshooting ==
 
 
 
=== Upgrading to CouchDB 2.x from an existing install ===
 
 
 
If you are updating CouchDB from version 1.x to version 2.x, Cozy may not be able to run because of CouchDB's sharding (which is not supported by Cozy yet). This updates changes the default database directory, making Cozy's database not found by CouchDB. Here is the path to follow to make Cozy work again.
 
 
 
* Stop the {{ic|couchdb}} service. Backup {{ic|/var/lib/couchdb/cozy.couch}} somewhere else and remove everything under {{ic|/var/lib/couchdb}} (don’t do this if you happen to use couchdb for anything else than Cozy! In that case, you probably need to check carefully what’s in there, and find the appropriate migration process for every database).
 
 
 
* Edit {{ic|/etc/couchdb/local.ini}} and add the following:
 
{{hc|1='''/etc/couchdb/local.ini'''|2=[cluster]
 
q=1
 
n=1
 
}}
 
 
 
* Start the {{ic|couchdb}} service. At this point, you should have files under {{ic|/var/lib/couchdb}} again, and especially {{ic|/var/lib/couchdb/shards/00000000-ffffffff/cozy.<unix time of creation>.couch}}.
 
 
 
* Stop the {{ic|couchdb}} service again, copy (don’t move, rather be safe) your backuped {{ic|cozy.couch}} to {{ic|/var/lib/couchdb/shards/00000000-ffffffff/cozy.<unix time of creation>.couch}}.
 
 
 
* Start the {{ic|couchdb}} service. Now, everything should be working.
 

Revision as of 17:03, 19 April 2018

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.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/couchdb@localhost/_config/admins/<couch_user> -d "\"<couch_password>\""

Configuring Cozy admin password

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

# cozy-stack config passwd /etc/cozy/cozy-admin-passphrase

You will be prompted to enter a passphrase. Then fix the ownership:

# chown cozy:cozy /etc/cozy/cozy-admin-passphrase

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 onboarding,settings,drive,photos,collect

This will output you a registration token. You can also specify an email using --email <address> at which the registration token will be sent.

You will then need to visit https://<instance>.example.tld/?registrationToken=<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, 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,collect. But this will grow over time, so you will have to expand your certificate regularly. 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;

    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!