Work in progress:

This article is a work in progress, it may contain incomplete or inaccurate information. There may be additional information on the talk page.

Note:

Report issues and suggestions to the Vines server at https://github.com/diaspora/vines/issues

Note:

The pull request integrating this with Diaspora is at https://github.com/diaspora/diaspora/pull/5073

This wiki-page is about setting up Vines on your Diaspora installation.

Vines is an XMPP chat server that connects you with large clusters of machines as easily as chatting with a friend.
It's a new, simpler way to manage your servers in the cloud or the data center.
— http://www.getvines.org/

Installation

Set up branch

Checkout or merge XMPP chat feature branch from zauberstuhl/diaspora.git:

 git remote add zauberstuhl https://github.com/Zauberstuhl/diaspora.git
 git fetch zauberstuhl && git checkout -b xmpp_chat_feature zauberstuhl/xmpp_chat_feature

Warning:

xmpp_chat_feature-branch is based upon Diaspora develop-branch!

Update

All required dependencies are included in your Gemfile. The only thing you have to do now is follow the Update guide! In short, execute following:

 export RAILS_ENV=development
 bundle install
 bundle exec rake db:migrate

Configuration

You'll find all required configuration parameters in diaspora.yml.example. If you'd like to activate the chat feature you have to copy paste the chat section from diaspora.yml.example to your actual diaspora.yml configuration file and activate the chat globally:

  chat:
    enabled: true

If you have already a working XMPP server and need only the front-end:

  chat:
    enabled: true
    server:
      enabled: false

It is also possible to configure the port and address of the client-to-server, server-to-server and the BOSH service. You'll also find the required parameters in diaspora.yml.example with a small description.

Certificates

Warning:

For encrypted communication we need a cerificate and the related key.

Put your files in the vines-cert folder, you can configure the path in diaspora.yml under the chat section.

The default path is /path_to_diaspora_installation/config/vines/.
Also the domain name should be included in the file name e.g.:

example.com.crt
example.com.key

If you have no certificate and want to generate a self-signed you can do that with vines, too. Just execute in you diaspora environment bundle exec vines cert example.com and you should be good to go ..

Note:

If you use your server in a development mode, think about enabling acceptance of self-signed certificates in your diaspora.yml!

Run it

If you are finished configuring the chat server you can start Diaspora as normal:

 ./script/server

Log into Diaspora and you should see the web client in the right corner. You can also log into it with your favorite desktop client like Pidgin.

For that use your Diaspora ID and your Diaspora password.

FAQ

Invalid byte sequence in UTF-8

You enabled the chat feature but haven't configured BOSH

*****************************************************************
You enabled the chat feature but haven't configured BOSH! That
could lead to mixed-content problems with the http clients. Please
think about editing your proxy configuration as described in:

diaspora.yml.example
*****************************************************************

The internal xmpp server does not support https and
even if we implement it, we would ran into certificate issues.
The problem with mixed-content is described here: https://github.com/Zauberstuhl/diaspora/issues/6

The easiest way of avoiding certificate and mixed-content issues is to use a proxy (see apache and nginx section below)!

If you finished configuring your proxy settings you also have to adjust diaspora.yml!
For my examples below, it would look like this:

  chat:
    server:
      bosh:
        proxy: true
        bind: '/http-bind'

Apache2

RewriteEngine On
 
RewriteCond %{REQUEST_URI} ^/http-bind
RewriteRule ^/(http\-bind.*)$ balancer://chat%{REQUEST_URI} [P,QSA,L]
 
RewriteCond %{DOCUMENT_ROOT}/%{REQUEST_FILENAME} !-f
RewriteRule ^/(.*)$ balancer://diaspora%{REQUEST_URI} [P,QSA,L]
 
<Proxy balancer://diaspora>
  BalancerMember http://127.0.0.1:3000
</Proxy>
 
<Proxy balancer://chat>
  BalancerMember http://0.0.0.0:5280
</Proxy>

Nginx

This is NOT tested. Please let me know if there are any problems with the configuration settings!

upstream chat_cluster {
  server localhost:5280;
}
 
location /http-bind {
  proxy_set_header X-Real-IP $remote_addr;
  proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  proxy_set_header Host $http_host;
  proxy_set_header X-Forwarded-Proto https;
  proxy_redirect off;
  client_max_body_size 4M;
  client_body_buffer_size 128K;
 
  proxy_pass http://chat_cluster;
}

Debugging

On default Vines will log to log/vines.log and has a log level of info set. Set the logging level to debug, info, warn, error, or fatal. The debug level logs all XML sent and received by the server.

  chat:
    server:
      log:
        file: 'log/vines.log'
        level: 'debug'