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 \ python-requests % pip install ModestMaps % pip install BlobDetector % pip install celery % pip install raven % 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/libproj.so.0 /usr/lib/libproj.so
Download the Field Papers project to
% git clone -b v2.0.0 https://github.com/stamen/fieldpapers.git /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
and reload the configuration.
% sudo sed -i 's/DocumentRoot.*/DocumentRoot \/usr\/local\/fieldpapers\/site\/www/' /etc/apache2/sites-available/default % /etc/init.d/apache2 reload
You'll also want to disable PHP for anything under
sudo sensible-editor /etc/apache2/sites-available/default and add these lines before the last
<Location /files> php_flag engine off </Location>
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'; EOF % 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. You will need to edit the following:
- DB_DSN - Whitch should look like
- chosen API password
- Add a GEOPLANET_APPID
- Add a FLICKR_KEY as well as any other details you wish to customize.
% 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 % pip install raven % pip install redis % celery -A tasks 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 (really, you should actually do these steps too)
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
upload_max_filesizeto accept file uploads larger than the default 2MB.
post_max_sizeto allow room for larger uploaded files.
Add Redis to the list of registered PHP extensions and use its bundled session handler:
% cat <<EOF > /etc/php5/conf.d/20-redis.ini extension=redis.so session.save_handler = redis session.save_path = "tcp://localhost" EOF
PHP sessions are brief by default, but a few tweaks can make them more durable.
session.gc_maxlifetimeto days or weeks so that visitors stay logged-in for longer periods of time.
After making these any of these changes to
php.ini, should should restart apache:
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