Deploying the Zotero WebDAV server on heroku for development and tests

Monday, 9 September 2013 in dev journal by Damien Mathieu

At shazino, we love playing around with all science things.

Lately, we released our Objective-C SDK for Zotero.
This SDK allows you to build awesome applications for iOS and OSX around the Zotero APIs.

One of the things we love about Zotero is the possibility to decentralize your data there.
You don’t need to host all your publications on their platform. But you can host them and synchronize them with the WebDav protocol.

If you’re poking around the SZNZotero SDK, you will probably need your own WebDAV server to develop and test your applications.
That’s probably not something you have on your desk.

Fortunately for us, there is phpZoteroWebDav. Written in PHP, it’s a quick and easy solution to deploy a WebDav server on any HTTP server and synchronize your Zotero library with it.

The original phpZoteroWebDav repository is not maintained anymore.
So we’re using ddean’s fork on github. Thanks to him.

For our development and test purposes, we wanted to facilitate even more the deployment of this application, without the hassle to configure a web server with PHP and run an application there.
This is exactly the type of need where we find Heroku to be an excellent solution. It allows us to quickly provision a new server with only what we need on it, run our tests and have it kept running for later use.

This is not for production use

Heroku is awesome for production use of course. However, the way phpZoteroWebDav is built makes the usage of the filesystem.
Heroku has a Read-Only Filesystem. The only writable directories are ./tmp and ./log.
Obviously, both of these directories aren’t reliable for long-term data storage.

Hosting a WebDav server on heroku is technically possible, as demonstrated by phpZoteroWebDav. The data will then need to be stored in an other media.
The Heroku PostgreSQL database could be a solution. Amazon S3 could also be an interesting choice. There are other of course.

Getting to it

Let’s install our WebDav server now.

You should start by cloning the git repository on your local machine.

git clone git://github.com/krueschan/phpZoteroWebDAV.git
cd phpZoteroWebDAV

Next, create an heroku application which will host the server

heroku create

You will also need to create a new private API key on Zotero.

There are now a few things to configure in the configuration of the application. Open the file settings.php.
This file contains several configuration variables used by the application.

Here are what we need to configure :

$API_key : the private API key you previously created on Zotero.
$user_ID : your user id on Zotero. This can be found on the page where you created your API key.
$data_dir : The directory where all your library will be stored. Set this to tmp/data/zotero.
$cache_dir : The internal cache used by the application. Set this to tmp/cache.

Create the data and cache directories, and add a hidden file inside, so they are versioned in git.

mkdir tmp tmp/data tmp/data/zotero tmp/cache
touch tmp/data/zotero/.gitkeep
touch tmp/cache/.gitkeep

And you can now commit all this in your local repository.

git add .
git commit -m "configuration for heroku"

Your application is now fully configured and ready to roll. Let’s deploy it !

git push heroku -u master

That’s all ! You can now go and browse your heroku application

Setting up the client

The client configuration is quite similar to what you would have with any other installation of phpZoteroWebDav.
In your zotero client, open the preferences window and go to the “Sync” section.

In the URL field, set your heroku URL, and end it with /webdav_server.php.
For example :

zotero-webdav-rox.herokuapp.com/webdav_server.php

In the username field, you can set whatever you want. But you need to set something.
In the password field, you can also set whatever you want, but also need to set something.

Verify the server, and all should work.
You can now use those same settings to deploy your own applications around Zotero using the SZNZotero SDK.
Happy Coding !

Authentication

This part is optional as you can use the WebDav server without it. However, if you intend to test on authenticated WebDav servers, I’d recommand to follow it.
Heroku, in it’s PHP layer, allows you to add basic HTTP authentication with the well-known .htaccess/htpasswd mecanism.

Create a file names .htaccess at the root of the application with the following content :

AuthUserFile /app/www/.htpasswd
AuthType Basic
AuthName "Restricted Access"
Require valid-user

Then, in your console, create a .htpasswd file with the following command :

htpasswd -c .htpasswd <username>

Where username is the login users will have to enter to access the application.
You will then be asked for a password.

Commit the changes, push them and you’re good to go with authentication.

git add .
git commit -m "add authentication"
git push heroku