Skip to content
This repository
Fetching contributors…

Cannot retrieve contributors at this time

file 161 lines (122 sloc) 5.451 kb

Installing Field Papers

This guide has been tested on Ubuntu 12.10 (and was previously used to install Field Papers on Ubuntu 10.04).


There are a few packages that you will need to install: some base material, packaged for use by the offline image decoder, and packages to help run the public-facing website. During the steps below, you'll be asked to create a root MySQL password a few times, it's fine to leave this blank.

% apt-get update
% apt-get install build-essential gdal-bin git-core screen \
                  mysql-server default-jre-headless \
                  redis-server \
                  libapache2-mod-php5 php-pear php5-gd php5-mysql \
                  python-beautifulsoup python-cairo python-dev \
                  python-gdal python-imaging python-numpy python-pip \

% pip install ModestMaps
% pip install BlobDetector
% pip install celery

% pecl install redis

Field Papers uses server packages from PHP's PEAR collection. The can be installed via the pear utility. Some of the packages below will throw warnings about deprecation, don't worry about those.

% pear install Crypt_HMAC HTTP_Request DB
% pear install Crypt_HMAC2 MDB2 MDB2#mysql

A few other details...

% ln -s /usr/lib/ /usr/lib/

Field Papers

Download the Field Papers project to /usr/local/fieldpapers.

% git clone -b v2.0.0 /usr/local/fieldpapers
% cd /usr/local/fieldpapers/site && make

Apache's default configuration will need to be edited slightly. This will set the default virtual host's DocumentRoot to /usr/local/fieldpapers/site/www and reload the configuration.

% sed -i 's/DocumentRoot.*/DocumentRoot \/usr\/local\/fieldpapers\/site\/www/' /etc/apache2/sites-available/default
% /etc/init.d/apache2 reload

Set up a new MySQL database for the site.

% cat <<EOF | mysql -u root
create database fieldpapers character set='utf8';
grant select, insert, update, delete, lock tables on fieldpapers.* to fieldpapers@localhost identified by 'w4lks';

% mysql -u root fieldpapers < /usr/local/fieldpapers/site/doc/create.mysql

Finally, set up site configuration by duplicating a new init.php and modifying the settings to match your own database, chosen API password, Yahoo and Flickr API keys, and other details.

% cp /usr/local/fieldpapers/site/lib/init.php.txt /usr/local/fieldpapers/site/lib/init.php
% sensible-editor /usr/local/fieldpapers/site/lib/init.php


Field Papers uses Celery to manage asynchronous tasks like creating prints and decoding scans. (Celery in turn used Redis to communicate between the PHP front-end and the Python tasks.)

Now try Field Papers in a browser to see it work. If you try to make a new print, you'll see a note that Field Papers is "Preparing your print". Leave the window open for now. You will need to start Celery for print tasks to run:

% cd /usr/local/fieldpapers/decoder
% celery -A poll worker

You'll see a few messages scroll by, and eventually the print page will be replaced by an image of your selected area and a PDF download link. Print it, scan it, or just convert it to a JPEG, and post the image back to your instance of Field Papers.

If you've made it this far, you should have a complete working instance of Field Papers. As a last step, add Celery to upstart so it will start on boot:

% cp conf/celery.conf /etc/init
% start celery

(It will be running in a screen session as the ubuntu user, so you can use screen -r celery to inspect the queue's status.)

That's it - you're done!

Tweaks, Gotchas

Many of PHP's internal settings are restrictive by default, for safety. You'll want to modify these for yourself, in Apache's .htaccess files or the file /etc/php5/apache2/php.ini on Ubuntu systems. See PHP documentation on runtime configuration for more information.

Add Redis to the list of registered PHP extensions and use its bundled session handler:

% cat <<EOF > /etc/php5/conf.d/20-redis.ini
session.save_handler = redis
session.save_path = "tcp://localhost"

PHP sessions are brief by default, but a few tweaks can make them more durable.

  • Increase session.gc_maxlifetime to days or weeks so that visitors stay logged-in for longer periods of time.

When atlases or snapshots fail, the /tmp directory can fill up. Add a few find-and-delete commands to /etc/crontab to keep these files from piling up and filling the disk:

10 *    * * *   ubuntu  find /tmp -cmin +360 -name 'preblobs-*.jpg' -delete
20 *    * * *   ubuntu  find /tmp -cmin +360 -name 'highpass-*.jpg' -delete
30 *    * * *   ubuntu  find /tmp -cmin +360 -name 'postblob-*.png' -delete
40 *    * * *   ubuntu  find /tmp -cmin +360 -name 'cairoutils-*.???' -delete
Something went wrong with that request. Please try again.