Installing celutz

System requirements

Python version 2 (at least 2.6) or version 3 (at least 3.2)
At least 10 GB of disk space. You should provision 100 MB for each panorama: panoramic pictures can be pretty big to start with, and celutz generates a lot of tiles during the initial upload.
At least 1.5G of RAM, mainly for tile generation. If you generate tiles on another computer, then you need much less, probably as little as 512 MB of RAM. Celutz is a quite simple Django application.
a fast CPU, again for tile generation. Having multiple CPU will not be useful in most cases, because tile generation is single-threaded.

For reference, generating tiles for a quite large panorama (30000x3487 pixels, amounting to 105 Mpixels, storing in JPEG) took 855 MB of RAM using Python 3.5 with Pillow 3.0.0 on a x86_64 Linux system.

Installation

Celutz is a fairly standard Django application: refer to the Django documentation for deployment methods. The initial installation for development should look like this:

# Debian jessie with python3, adapt to your OS
apt install build-essential python3-dev libjpeg-dev libtiff5-dev zlib1g-dev libopenjp2-7-dev
virtualenv -p /usr/bin/python3 ~/mycelutzvenv
. ~/mycelutzvenv/bin/activate
pip install -r requirements.txt

Configuration

To configure the application, don't edit celutz/settings.py directly, but instead create a file celutz/local_settings.py with your local modifications.

Some Django things you should really configure:

SECRET_KEY
ALLOWED_HOSTS
DEBUG
database configuration

There are also celutz-specific settings:

LOGIN_REQUIRED: is celutz public or are users required to login first?
PANORAMA_TILES_DIR: where the tiles are, relatively to MEDIA_ROOT and MEDIA_URL
PANORAMA_MAX_DISTANCE: maximum distance (in meters) for reference points to be displayed when viewing a panorama
LOCATE_POINT_MAX_DISTANCE: when locating a reference point, only consider panoramas that are closer than this maximum distance, in meters.
MAP_BOUNDS: if defined, limit the view of the main map to the given rectangle. By default, the view is fitted to display all points. See celutz/settings.py for an example.

Then run the migrations:

python manage.py migrate

And create a superuser:

python manage.py createsuperuser

Lastly, you should collect static files to serve them:

python manage.py collectstatic

Development

Just run the builtin Django server:

./manage.py runserver

Alternatively, you can use gunicorn exactly like in production.

You also need to launch a celery worker (see below).

Production

To run the WSGI server, for instance gunicorn:

gunicorn celutz.wsgi:application

Internally, dj_static is used to serve static and media files (including tiles).

As an alternative, you may wish to serve media files (everything in media/) with your web server directly.

You probably also need to configure your webserver to allow to send very large files in a POST request. An upper limit of 200 MB should be enough, even for very large pictures in raw format.

Updating a production installation

There is a script, update_prod.sh, that handles updating an existing production installation. It install new dependencies and collect static files.

Tile generation

Tile generation uses Celery, because it is quite a heavy task CPU-wise.

To launch a celery worker, run this in your virtualenv:

celery -c 1 -A celutz.celery worker --loglevel=info

This tells celery to handle at most one task at a time: -c 1. Indeed, generating tiles for a single panorama can take quite a lot of RAM. If you have enough RAM (2GB+) and multiple CPU, you can increase this parameter to generate tiles for multiple panoramas in parallel.

The default parameters use the Django database as a message queue, to ask a celery woker to generate tiles for a panorama. This is far from efficient, but since there are very few messages, it is not worth the trouble to configure a real message queue such as RabbitMQ.

Importing reference points

Gathering reference points can be a bit of a hassle.

Some reference points are provided alongside celutz, in panorama/fixtures. To import one set of reference points into the database, run:

python manage.py loaddata refpoints_mycity

Upgrading from the PHP version of celutz

Were you previously using the PHP version of celutz? You can import all your old data! See UPGRADE.md.

INSTALL.md 4.6 KB Permalink History Raw