.. thumbor usage


Thumbor thumbnail server usage
==============================

`Thumbor`_ can be used as a thumbnail server to deliver
images to the XMM frontend and other destinations.

.. _Thumbor: http://thumbor.readthedocs.io


Installation
------------

1. Install Thumbor as usual (as a docker container, system package or in a new Python 2 virtual environment).
2. Generate the boilerplate configuration file somewhere you can reference it::

   $ thumbor-config > /path/to/thumbor_conf.py

3. You should modify this file to accomodate in the very least these settings:

   .. code::

         LOADER = 'thumbor.loaders.file_loader'
         SECURITY_KEY = 'put a random secure string here'
         FILE_LOADER_ROOT_PATH = '/path/to/xmm/media/root'

   You can check all other settings and configure them as needed.

4. In your XMM project, install the ``libthumbor`` Python package, we need this to generate basic URLs to the thumbnails::

   $ pip install libthumbor==1.3.2

5. Configure your *project settings* with the Thumbor server credentials:

   .. code::

      THUMBOR_URL = os.getenv('THUMBOR_URL', None)
      THUMBOR_KEY = os.getenv('THUMBOR_KEY', 'MY_SECURE_KEY')

   By default you can overwrite these environment variables and do not have to change
   the ``settings.py`` file.

6. Configure the Thumbor settings in the ``src/config/dev/index.js`` files:

   .. code-block:: javascript

      var API = {
          // [...] existing values
          THUMBOR: {
              URL: 'http://localhost:8888',
              KEY: null,
          },
      };


Running
-------

Locally, you can run the Thumbor server with a simple command::

   $ thumbor -c path/to/thumbor_config.py

For deployment, this should run as a managed service and/or in a container.
The appropriate read permissions should be taken care of and added to a pre-launch checklist.

Running in a production environment also requires you to set the ``THUMBOR`` configuration
accordingly in the ``src/config/production/index.js`` file!