Installing Datawrapper locally on Debian 8.1

As part of our exploration of new data visualization solutions and tools at Studio V2, I was tasked to install a local instance of datawrapper for evaluation purposes. Datawrapper is a nice web-based data visualisation tool that generates little interactive graphs from raw data.

While the official project’s wiki includes some instructions on how to install your local instance of datawrapper, I didn’t find the instructions to be detailed nearly enough. As such, I’m making this little article to clarify some aspects of the installation process.

Installing Debian

This post is meant to be a much more detailed and foolproof version of this one, however the “installing debian” part, aren’t covered here. It assumes you’ve already done that. If you haven’t, it’s just a matter of downloading the latest official CD image, loading it up in a virtual machine (like VirtualBox for instance) or actual hardware and pressing return a bunch of times. You can find more detailed informations on that process everywhere else online.

I made the choice of installing the latest Debian version on a virtual machine.

Pre-installation decisions

Before starting the installation process, there are a few things you must think about.

The Domain Names

You need to think a bit about the domain names you want to use for your local instance. As long as you’re doing everything locally, the name themselves don’t really matter, just write them down or use these as reference because these will be used several times during the installation process.

You will need one name for the datawrapper application and one for the graph hosting. This is what I picked

debian-datawrapper.local
static.debian-datawrapper.local

Once you’ve decided of the domain names, you may want to configure the host file of the client machine running the browser that you will use to connect to the datawrapper instance. For this, you need to get the IP address of your debian machine.

sudo ip addr

or

sudo ifconfig

Once you’ve found the IP adress, edit the host file of the client machine by adding the following lines to your existing host file. For this example, my local IP address was 192.168.1.83. Replace this with your own local address.

192.168.1.83    debian-datawrapper.local
192.168.1.83    static.debian-datawrapper.local

The Installation Location

This represent where you want to put your datawrapper installation on your debian machine.

Personally I like to put everything that isn’t made of static webpages in /srv. This isn’t too different from putting it in /var/www. The choice is up to you, however, if you decide to change that location to something like /var/www, just replace all references to the installation path accordingly.

Installing the dependencies

Datawrapper needs a few dependencies to work. Install them as root on your fresh debian box.

apt-get install apache2 mysql-server mysql-client php5 php5-mysql pdepend phploc phpmd phpunit

When installing the mysql server, you will be asked to input a password for the root user. Don’t forget it, this is important. You will need it later on.

You’ll also need some tools on your machine, they are not dependencies per say, but they are needed anyway, so you might as well do that now.

apt-get install git curl make

If you haven’t done so already, install and configure sudo on your machine. This will make things easier for you.

apt-get install sudo

Cloning the sources

As root, go where you want to install your instance of datawrapper.

sudo su
cd /srv

Here, clone datawrapper from the official git repository.

git clone https://github.com/datawrapper/datawrapper.git

Change the ownership of the content of the datawrapper folder recursively to avoid any possible complications with apache down the line.

chown -R www-data datawrapper

Configuring Apache

Add the domain names to your host file.

/etc/hosts

127.0.1.1       debian-datawrapper
127.0.1.1       debian-datawrapper.local
127.0.1.1       static.debian-datawrapper.local

Disable the default apache configuration.

sudo a2dissite 000-default

Write the new config files in /etc/apache2/sites-available as two new individual configuration files named 000-static.debian-datawrapper.local.conf and 010-debian.datawrapper.local.conf.

000-static.debian-datawrapper.local.conf:

<VirtualHost *:80>
    ServerName static.debian-datawrapper.local
    DocumentRoot /srv/datawrapper/charts/static
    <Directory />
            Options Indexes FollowSymLinks Includes ExecCGI
            AllowOverride All
            Order deny,allow
            Allow from all
            Require all granted
    </Directory>
</VirtualHost> 

010-debian-datawrapper.local.conf:

<VirtualHost *:80>
        ServerName debian-datawrapper.local
        DocumentRoot /srv/datawrapper/www
        <Directory />
                Options Indexes FollowSymLinks Includes ExecCGI
                AllowOverride All
                Order deny,allow
                Allow from all
                Require all granted
        </Directory>
</VirtualHost> 

Enable the new sites configurations.

sudo a2ensite 000-static.debian-datawrapper.local 010-debian-datawrapper.local

Enable some apache modules.

sudo a2enmod rewrite authz_host

Once this is done, reload apache:

service apache2 reload

If you made any mistake in the configuration files, apache will fail to reload. You can learn more about the errors you may have made by typing

sudo systemctl status apache2.service

or

sudo journalctl -xn

Not done yet!

By pointing your client browser to debian-datawrapper.local, you should see something like that, it’s perfectly normal, we’re not done yet.

Edit datawrapper’s configuration file

In the datawrapper directory, copy the default configuration file to create a new configuration file:

cp config.template.yaml config.yaml

Edit the config file to reflect the chosen domain names:

domain: debian-datawrapper.local
chart_domain: static.debian-datawrapper.local

Creating the MySQL database

Go into the /lib/core/build/sql/ subdirectory of the datawrapper folder.

cd /srv/datawrapper/lib/core/build/sql/

Open the mysql client as the root user using the password you defined during mysql’s install process.

mysql -u root -p

From there, create a new database. I choose to call it “datawrapper”.

mysql> create database datawrapper;
mysql> quit;

Load the database schema.

mysql -u root -p datawrapper < schema.sql

The few remaining steps

Copy /srv/datawrapper/lib/core/build/conf/datawrapper-conf.php.master to /srv/datawrapper/lib/core/build/conf/datawrapper-conf.php.

sudo cp /srv/datawrapper/lib/core/build/conf/datawrapper-conf.php.master /srv/datawrapper/lib/core/build/conf/datawrapper-conf.php

Edit the new configuration file to point to the local instance of mysql. If you picked “datawrapper” as a database name, the only thing you will have to edit is the 'password' => '' line. Fill in with the root password of your mysql instance.

Go back to the datawrapper’s installation folder’s root.

cd /srv/datawrapper

Run the following command:

sudo php scripts/plugin.php install "*"

And finally, run make.

sudo make    

In theory, you should be done now. This is what you should see when going to debian-datawrapper.local on your browser

Done!

Last minute modification

For some reason I ran into a bug. Every time I tried to generate a new visualisation I ran into this screen.

Oooops

Running make at the last part didn’t seem to actually do anything. This seems to be a known issue (there are several Issues reported on the official Github page, here and here).

I managed to fix that issue by copying dw-2.0.js to dw-2.0.min.js.

In the datawrapper directory, do the following:

sudo cp dw.js/dw-2.0.js dw.js/dw-2.0.min.js
sudo cp dw.js/dw-2.0.js www/static/js/dw-2.0.js

I’ll try to update this final section once this issue is fixed, bur for now, you should be done.



Enter your desired user name/password and after your comment has been reviewed by an admin it will be posted and your account will be enabled. If you are already registered please login before posting.