invenio-devserver 0.4

About
-----
``invenio-devserver'' is an HTTP server for Invenio with automatic code reloading,
useful when developing for [[http://invenio-software.org/][Invenio]]. It also
includes a mail debug server which prints all incoming emails to the console.

Invenio is a free software suite enabling you to run your own digital library
or document repository on the web. See more on http://invenio-software.org/.

Installation
------------
You can install invenio-devserver with ``pip install invenio-devserver``, or you
can use ``easy_install``.

Requirements
------------
* `Invenio <http://invenio-software.org/wiki/Installation>`_
* ``Werkzeug''
* ``mock'' (optional): to intercept errors and display them on stdout

Both ``Werkzeug'' and ``mock'' will be automatically installed when using PIP.

Configuration
-------------
You need to tell ``invenio-devserver'' where your Invenio source code and
installation lives. Add config_local.py to your site-packages directory with
the following::

SRC_PATH = [
"~/src/invenio",
"~/src/inspire", # (only needed if you have several project)
]
INSTALL_PATH = "/opt/invenio"

If you don't specify ``SRC_PATH'' or ``INSTALL_PATH'' they will be guessed:

* If you are in an activated virtualenv the ``INSTALL_PATH'' is set to
``VIRTUAL_ENV'' environment variable.
* ``SRC_PATH'' defaults to ``~/src/invenio/''.
* If you are using ``invenio-devscripts'', ``SRC_PATH'' and ``INSTALL_PATH''
will be set to the environment variables ``CFG_INVENIO_SRC'' and
``CFG_INVENIO_PREFIX' respectively.

Please see ``src/invenio_devserver/config.py'' for further possible settings.

Usage ``serve''
---------------
If the Invenio installation is in a virtualenv, activate it and run::

$ serve
HTTP Server mode with reload mode
* Running on http://localhost:4000/
* Spawning worker
* Ready

If the Invenio installation is under your user run::

$ python serve.py

If the Invenio installation is under another user (e.g wwww), you can use

$ sudo -u www python serve.py

The following options for ``serve'' are available::

$ serve --help
Usage: python serve.py [-bp]

Invenio web server for development

Options:
-h, --help show this help message and exit
-b BIND_ADDRESS Address to bind to
-p BIND_PORT Port to bind to
--no-reload Disable automatic reloading when a source file is changed
--no-http Disable http server, only update invenio install
--pdb Drop to python debugger on errors
-s SRC_PATH Source folder (one or more)
-o INSTALL_PATH Path to Invenio installation.


Usage ``mailserve''
-------------------
If the Invenio installation is in a virtualenv, activate it and run::

$ mailserve
Remember to set the two following settings in invenio-local.conf:

CFG_MISCUTIL_SMTP_HOST=127.0.0.1
CFG_MISCUTIL_SMTP_PORT=1025

Now accepting mail at 127.0.0.1:1025 (hit CONTROL-C to stop)


The following options for ``mailserve'' are available::
Usage: mailserve [-bp]

Invenio mail server for development

Options:
-h, --help show this help message and exit
-b BIND_ADDRESS Address to bind to
-p BIND_PORT Port to bind to