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:

    virtualenv ~/mycelutzvenv
    . ~/mycelutzvenv/bin/activate
    pip install -r requirements.txt
    # Configure database if needed
    python manage.py migrate
    python manage.py createsuperuser

One specific information for production usage: you **really** want to serve
the `media/` directory with a real webserver, and **not** with Django itself.
Hundreds of tiles (small image files) will be served from this directory each
time a client visualises a panorama.

You probably also want 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.

Tile generation
---------------

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

To launch a celery worker while developping, 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.

Upgrading from the PHP version of celutz
----------------------------------------

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