docs/webui.rst @ e8d49fb98199 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).

Initial Deployment
''''''''''''''''''

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 as
well as the built-in `fetch
<http://mercurial.selenic.com/wiki/FetchExtension>`_ extension (to
automatically merge updates)::

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

    echo '[extensions]' >> .hg/hgrc
    echo 'review = /var/www/myproject-review-interface/hg-review/review' >> .hg/hgrc
    echo 'fetch = ' >> .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'
    PROJECT_URL = 'http://bitbucket.org/your/project/' # or None

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``.

Updating the Data
'''''''''''''''''

You'll want to keep the review data for this interface current so users can see
all the latest comments and signoffs.

To do this you simply need to pull in the main repository (to receive new
changesets in your project) and fetch in the review data repository (to receive
new comments and signoffs)::

    hg -R /var/www/myproject-review-interface/ pull
    hg -R /var/www/myproject-review-interface/.hg/review fetch

New comments and signoffs will be visible immediately -- you don't need to
restart your WSGI server.

You'll probably want to set this up as a cron job or use a hook of some kind
to automate the updates.

If you allow anonymous comments and want people that are using the extension
locally (instead of this public instance) to see these comments, you'll need to
*fetch and push* the review data repo as well::

    hg -R /var/www/myproject-review-interface/.hg/review/ fetch
    hg -R /var/www/myproject-review-interface/.hg/review/ push

hg-review is designed to never encounter merge conflicts with its data, but
there's always the chance that someone has done something manually that could
cause a problem.

If your interface doesn't seem to be receiving new comments/signoffs you'll
want to take a look at the review data repository to see what's wrong::

    cd /var/www/myproject-review-interface/.hg/review
    hg heads

There should only ever be one head in this repository. If there are more you'll
need to merge them (and push back to your public review data repo so others
won't encounter the same problem).