Services/Sync/Server/Archived/0.3/Setup

Pre-Setup Considerations

It is strongly recommended that the Weave Server be set up under https, or behind a firewall with an https proxy in front of it, especially if you are planning to use Apache basic authorization for access control.

The Weave Server requires PHP with PDO and JSON support installed. This should be the case if you are running PHP 5.1+. PDO will need drivers for whatever storage and authentications engines are used.

Setting up the Server

1) Unzip the server-directory into the location you plan to serve the files from. You can get the latest server from http://hg.mozilla.org/labs/weaveserver (there you can download it in different formats). Be aware this code is always in development and may contain bugs.

2) Edit your apache conf files to add the following:

Alias /0.3/user <full path to weave directory>/index.php
Alias /weave/register <full path to weave directory>/register.php

Don't forget to set up the weave directory in a virtual-host-directive (or similar), or else php will not work.

3) Edit the weave_constants.php file as described below, and move it into a directory in the php include path.

Setting up Weave Authentication

In weave_constants.php at the beginning (e.g. directly after the license-block)

define('WEAVE_AUTH_ENGINE', '[sqlite|mysql|none]');

so for example

define('WEAVE_AUTH_ENGINE', 'mysql');

Sqlite

define('WEAVE_SQLITE_AUTH_DIRECTORY, '<path to stores directory>');

additionally, create the users table

$ sqlite3 <path to stores directory>/_users
SQLite version 3.4.0
sqlite> create table users (username text primary key, md5 text, email text, location text);
sqlite> .quit

Change the owner of the _users db file to the account your webserver runs under.

Mysql

Create the mysql database. Add the following tables:

create table users 
(
 username varchar(32) primary key, 
 md5 varchar(32),
 email varchar(64),
 location text
) engine=InnoDB;

Constants:

define('WEAVE_MYSQL_AUTH_HOST', '<db host>');
define('WEAVE_MYSQL_AUTH_DB', '<db name>');
define('WEAVE_MYSQL_AUTH_USER', '<db username>');
define('WEAVE_MYSQL_AUTH_PASS', '<db password>');

You can create users directly in mysql with the following command:

insert into users values ('[username]', md5('[password]'));

Setting up Weave Storage

define('WEAVE_STORAGE_ENGINE', '[sqlite|mysql]');

Sqlite

Edit the following constant:

define('WEAVE_SQLITE_STORE_DIRECTORY', '<path to stores directory>');

Easiest way to create a user is to go through the admin server process below.

Mysql

Create the mysql database. Add the following tables:

create table wbo
(
 username varchar(32),
 collection varchar(64),
 id varchar(64),
 parentid varchar(64),
 modified bigint,
 sortindex int,
 depth tinyint,
 payload longtext,
 primary key(username, collection, id),
 index parentindex(username, collection, parentid),
 index modified(username, collection, modified)
) engine=InnoDB;

Edit your constant file:

define('WEAVE_MYSQL_STORE_HOST', '<db host>');
define('WEAVE_MYSQL_STORE_DB', '<db name>');
define('WEAVE_MYSQL_STORE_USER', '<db username>');
define('WEAVE_MYSQL_STORE_PASS', '<db password>');

Other Constants

define('WEAVE_PAYLOAD_MAX_SIZE', '<bytes>');

Caps the size (in bytes - watch out for large unicode characters!) of a payload.

define('WEAVE_SHARE_DBH', '1');

If both the storage engine and authentication engine are using the same database, setting this makes both engines use the same database handler rather than opening different ones. Note that SQLite cannot use the same db for authentication and storage.

define('WEAVE_REGISTER_USE_CAPTCHA', '1');

Requires use of a captcha for users creating accounts. (See registration spec)

Setting up Weave Admin

You can create, update passwords and delete users through the Server Admin API. Using the admin server is optional and is offered as a convenience rather than a requirement.

Add the following to your apache conf:

Alias /weave/admin <path to the admin.php script>

Due to the security concerns, this script should be additionally protected, either through denying most IPs, or using htaccess. Additionally, the following constant, if set, is required to be passed in for all transactions to the server:

define('WEAVE_USER_ADMIN_SECRET', '<secret>');

Testing the Weave Server

The load_data.pl script will run a series of tests against your server, creating, modifying, selecting from and deleting a collection. Make sure to change the parameters at the top before running it. Also, the script requires the libwww-perl module and the weave admin server above to be set up. It currently does not work with http-authentication, so also be sure to have your web-directory unprotected during the tests.

Sample virtual host config

server-config (for debian placed in /etc/apache2/sites-enabled/): ssl enabled, http-login required

<VirtualHost *:88 *:89>

ServerName weave.my.domain
DocumentRoot /var/www/weaveserver/server/

ErrorLog /var/log/apache2/weaveserver-error.log
CustomLog /var/log/apache2/weaveserver-access.log combined

SSLENgine on
SSLCertificateKeyFile /etc/apache2/server.cert.key
SSLCertificateFile /etc/apache2/server.cert.crt

<Directory "/var/www/weaveserver/server/">


Options Indexes FollowSymLinks
AllowOverride none
Order allow,deny
Allow from all
AuthType Basic
AuthName "Weave Server"
AuthUserFile /var/www/pws
require valid-user

</Directory>

Alias /weave/0.3 /var/www/weaveserver/server/index.php
Alias /weave/register /var/www/weaveserver/server/register.php
Alias /weave/admin /var/www/weaveserver/server/admin.php

Alias /0.3/user /var/www/weaveserver/server/index.php

</VirtualHost>