Add an installation guide

INSTALL.md

@@ -0,0 +1,57 @@
+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.
+
+Installation
+------------
+
+Celutz is a fairly standard Django application: refer to the Django
+documentation for deployment methods.  The initial installation 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: 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 ztulec.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.