view contrib/docker/apache-server/README.rst @ 50336:cf4d2f31660d stable

chg: populate CHGHG if not set

Normally, chg determines which `hg` executable to use by first consulting the
`$CHGHG` and `$HG` environment variables, and if neither are present defaults
to the `hg` found in the user's `$PATH`. If built with the `HGPATHREL` compiler
flag, chg will instead assume that there exists an `hg` executable in the same
directory as the `chg` binary and attempt to use that.

This can cause problems in situations where there are multiple actively-used
Mercurial installations on the same system. When a `chg` client connects to a
running command server, the server process performs some basic validation to
determine whether a new command server needs to be spawned. These checks include
things like checking certain "sensitive" environment variables and config
sections, as well as checking whether the mtime of the extensions, hg's
`__version__.py` module, and the Python interpreter have changed.

Crucially, the command server doesn't explicitly check whether the executable it
is running from matches the executable that the `chg` client would have
otherwise invoked had there been no existing command server process. Without
`HGPATHREL`, this still gets implicitly checked during the validation step,
because the only way to specify an alternate hg executable (apart from `$PATH`)
is via the `$CHGHG` and `$HG` environment variables, both of which are checked.

With `HGPATHREL`, however, the command server has no way of knowing which hg
executable the client would have run. This means that a client located at
`/version_B/bin/chg` will happily connect to a command server running
`/version_A/bin/hg` instead of `/version_B/bin/hg` as expected. A simple
solution is to have the client set `$CHGHG` itself, which then allows the
command server's environment validation to work as intended.

I have tested this manually using two locally built hg installations and it
seems to work with no ill effects. That said, I'm not sure how to write an
automated test for this since the `chg` available to the tests isn't even built
with the `HGPATHREL` compiler flag to begin with.

====================
Apache Docker Server
====================

This directory contains code for running a Mercurial hgweb server via
mod_wsgi with the Apache HTTP Server inside a Docker container.

.. important::

   This container is intended for testing purposes only: it is
   **not** meant to be suitable for production use.

Building Image
==============

The first step is to build a Docker image containing Apache and mod_wsgi::

  $ docker build -t hg-apache .

.. important::

   You should rebuild the image whenever the content of this directory
   changes. Rebuilding after pulling or when you haven't run the container
   in a while is typically a good idea.

Running the Server
==================

To run the container, you'll execute something like::

  $ docker run --rm -it -v `pwd`/../../..:/var/hg/source -p 8000:80 hg-apache

If you aren't a Docker expert:

* ``--rm`` will remove the container when it stops (so it doesn't clutter
  your system)
* ``-i`` will launch the container in interactive mode so stdin is attached
* ``-t`` will allocate a pseudo TTY
* ``-v src:dst`` will mount the host filesystem at ``src`` into ``dst``
  in the container. In our example, we assume you are running from this
  directory and use the source code a few directories up.
* ``-p 8000:80`` will publish port ``80`` on the container to port ``8000``
  on the host, allowing you to access the HTTP server on the host interface.
* ``hg-apache`` is the container image to run. This should correspond to what
  we build with ``docker build``.

.. important::

   The container **requires** that ``/var/hg/source`` contain the Mercurial
   source code.

   Upon start, the container will attempt an install of the source in that
   directory. If the architecture of the host machine doesn't match that of
   the Docker host (e.g. when running Boot2Docker under OS X), Mercurial's
   Python C extensions will fail to run. Be sure to ``make clean`` your
   host's source tree before mounting it in the container to avoid this.

When starting the container, you should see some start-up actions (including
a Mercurial install) and some output saying Apache has started::

Now if you load ``http://localhost:8000/`` (or whatever interface Docker
is using), you should see hgweb running!

For your convenience, we've created an empty repository available at
``/repo``. Feel free to populate it with ``hg push``.

Customizing the Server
======================

By default, the Docker container installs a basic hgweb config and an
empty dummy repository. It also uses some reasonable defaults for
mod_wsgi.

Customizing the WSGI Dispatcher And Mercurial Config
----------------------------------------------------

By default, the Docker environment installs a custom ``hgweb.wsgi``
file (based on the example in ``contrib/hgweb.wsgi``). The file
is installed into ``/var/hg/htdocs/hgweb.wsgi``.

A default hgweb configuration file is also installed. The ``hgwebconfig``
file from this directory is installed into ``/var/hg/htdocs/config``.

You have a few options for customizing these files.

The simplest is to hack up ``hgwebconfig`` and ``entrypoint.sh`` in
this directory and to rebuild the Docker image. This has the downside
that the Mercurial working copy is modified and you may accidentally
commit unwanted changes.

The next simplest is to copy this directory somewhere, make your changes,
then rebuild the image. No working copy changes involved.

The preferred solution is to mount a host file into the container and
overwrite the built-in defaults.

For example, say we create a custom hgweb config file in ``~/hgweb``. We
can start the container like so to install our custom config file::

  $ docker run -v ~/hgweb:/var/hg/htdocs/config ...

You can do something similar to install a custom WSGI dispatcher::

  $ docker run -v ~/hgweb.wsgi:/var/hg/htdocs/hgweb.wsgi ...

Managing Repositories
---------------------

Repositories are served from ``/var/hg/repos`` by default. This directory
is configured as a Docker volume. This means you can mount an existing
data volume container in the container so repository data is persisted
across container invocations. See
https://docs.docker.com/userguide/dockervolumes/ for more.

Alternatively, if you just want to perform lightweight repository
manipulation, open a shell in the container::

  $ docker exec -it <container> /bin/bash

Then run ``hg init``, etc to manipulate the repositories in ``/var/hg/repos``.

mod_wsgi Configuration Settings
-------------------------------

mod_wsgi settings can be controlled with the following environment
variables.

WSGI_PROCESSES
   Number of WSGI processes to run.
WSGI_THREADS
   Number of threads to run in each WSGI process
WSGI_MAX_REQUESTS
   Maximum number of requests each WSGI process may serve before it is
   reaped.

See https://code.google.com/p/modwsgi/wiki/ConfigurationDirectives#WSGIDaemonProcess
for more on these settings.

.. note::

   The default is to use 1 thread per process. The reason is that Mercurial
   doesn't perform well in multi-threaded mode due to the GIL. Most people
   run a single thread per process in production for this reason, so that's
   what we default to.