docs/webui.rst @ c631e35b5827 initial-docs

Web Interface
=============

The web interface of hg-review is probably what you're going to use the most.

Running Locally
---------------

To start the web interface for a local repository that you want to review you
can run ``hg review --web``. Visit http://localhost:8080/ to use it.

When you add comments or signoffs hg-review will use your normal Mercurial
username as the author.

This command can take a few extra options:

``--address ADDRESS``
    The address to bind to. Use ``0.0.0.0`` if you want other people to be able
    to access it.

    **Be careful!** Because the web interface uses your Mercurial username by
    default, binding to ``0.0.0.0`` will let anyone add comments and signoffs
    in your name! You'll probably want to use the ``--read-only`` option to
    prevent this.

    Default: ``127.0.0.1``

``--port PORT``
    The port to listen on.

    Default: ``8080``

``--read-only``
    Run the server in read-only mode. This will not allow data to be pushed or
    pulled, comments to be made or signoffs to be added.

    This can be useful when combined with ``--address`` to let other people
    view the UI without letting them add comments in your name.

    Default: ``false``

``--allow-anon``
    Allow comments (not not signoffs) to be added even if ``--read-only`` is
    used, and set the username to ``Anonymous <anonymous@example.com>`` instead
    of your Mercurial username.

    This option is most useful when you're deploying a permanent web interface
    to a server and want to allow anonymous viewers to add comments. See the
    :ref:`deployment` section for more information.

    Default: ``false``


.. _deployment:

Deployment to a Server
----------------------

Although hg-review is built for *distributed* code review it's sometimes nice
to provide a public interface. This will let people can comment easily without
using the extension (or even cloning your project).

You can use any WSGI server you like to provide a public instance of hg-review.
Before you start you'll need to have Mercurial installed on your web server.

Once you've got Mercurial running on the server you'll need to clone copies of
hg-review, your project, and your project's review data to the web server.
First create a directory where everything will live::

    mkdir /var/www/myproject-review-interface/
    cd /var/www/myproject-review-interface/

Then grab a copy of hg-review::

    hg clone http://bitbucket.org/sjl/hg-review/

Grab a copy of your project and configure it to use the hg-review extension::

    hg clone http://bitbucket.org/you/yourproject/
    cd yourproject

    echo '[extensions]' >> .hg/hgrc
    echo 'review = /var/www/myproject-review-interface/hg-review/review' >> .hg/hgrc

Use hg-review to pull down the review data::

    hg review --init

Now that you've got all the necessary data you can set up the WSGI script.
Start by copying the included sample script::

    cd /var/www/myproject-review-interface/
    cp hg-review/contrib/deploy/wsgi.py wsgi.py

Edit the script to configure your project to your liking. For reference, the
relevant part of the script should look something like this::

    # An example WSGI script for serving hg-review's web UI.
    # Edit as necessary.

    # If hg-review is not on your webserver's PYTHONPATH, uncomment the lines
    # below and point it at the hg-review directory.
    import sys
    sys.path.insert(0, "/var/www/myproject-review-interface/hg-review")

    REPO = '/var/www/myproject-review-interface/myproject'
    READ_ONLY = True
    ALLOW_ANON_COMMENTS = False
    ANON_USER = 'Anonymous <anonymous@example.com>'
    SITE_ROOT = 'http://yoursite.com/optional/path'
    TITLE = 'Your Project'

All that's left is to point your WSGI server at this script and fire it up. How
you do that depends on your WSGI server. A sample configuration file for
`Gunicorn <http://gunicorn.org/>`_ is provided in
``contrib/deploy/gunicorn.conf.py``.