Commit b56742fc authored by Georges Racinet's avatar Georges Racinet 🦑
Browse files

INSTALL_HEPTAPOD: how to run safely with Python 3

Notably includes instructions for dual virtualenv setup

--HG--
branch : heptapod-0-13
parent f0635ad0c0dc
......@@ -66,12 +66,50 @@ All other standard GitLab components (Gitaly, etc) have to be taken
from the canonical upstream locations, at the version specified at the root
of the Rails application sources (`GITALY_SERVER_VERSION` etc).
### Installing the Mercurial component
### Installing Mercurial components
We need a specific Mercurial version, a WSGI server (usually Gunicorn), and
some additional Python packages from source.
For now, this is Python2 only.
#### Python versions
Before version 0.13.0, Heptapod runs with Python 2.7 only.
Heptapod 0.13.0 supports Python 2.7 and Python ≥ 3.7, with Python 3 still
considered a technology preview.
Python 3 will become default or even mandatory with Heptapod 0.14.
On Python 3, the preferred version should be 3.8.
In theory, the minimal Python 3 version should be 3.6.2, but it is completely
untested, whereas developer setups have routinely been running 3.7.
For the record the Docker images currently ship with 3.8.3.
#### Be ready to fallback to Python 2
We encourage you to run Heptapod with Python 3, but you must be aware that
this can cause some friction, especially in interactions with external
systems. Therefore you should **prepare the means to switch easily between
Python 2 and Python 3**. This way, if you encounter problems, you'll be able to qualify them (thank you in advance for the resulting bug report)
and you'll have a workaround.
An easy way to do that is to prepare a virtualenv for each Python version,
and point a symbolic link to the one to actually use.
Assuming you'll reference only that link in the
various configuration files (see below), to switch Python versions, you'll only
need to
1. change the link target
2. restart `gunicorn` (internal Mercurial service).
Almost no perceptible interruption.
3. restart the Rails application so that the Python version displayed in the
help page and admin dashboard is the right one. This is a noticeable
interruption of service, but you can delay it if that's a problem.
#### Install the Python packages
You can install them system-wide if that suits you (Mercurial has very few
dependencies, it's very unlikely it'll clash with system libraries) or with
......@@ -85,8 +123,7 @@ Install the Python packages to be taken from pypi.org using the
$PIP install -U -r python/requirements.txt
```
where `$PIP` is `pip --user` or `some/virtualenv/bin/pip` according to your
choice.
where `$PIP` is `pip --user` or `some/virtualenv/bin/pip` according to your choice (see above how to prepare for Python 3 with easy fallback onto Python 2).
### Configuration
......@@ -169,6 +206,8 @@ is on the path.
Again, this `gunicorn` must be able to load the Heptapod Python packages, so
you should use the one that's been installed with `requirements.txt`.
If you're using the dual virtualenv setup for Python 3 with fallback on
Python 2, then use the symbolic link in the path to gunicorn.
Notes:
......@@ -183,8 +222,12 @@ Edit the configuration files for the Rails application
to provide the full path to your `heptapod.hgrc` file, and the `hg` executable
in the `mercurial` section.
Note: in those YaML files, `hgrc` must always be a list. This is for separation
in several files with different persistence properties.
Notes:
- in those YaML files, `hgrc` must always be a list. This is for separation
in several files with different persistence properties.
- if you're using the double virtualenv approach to testing Python 3, remember
to use the symbolic link for the path to the `hg` executable.
### Validation with the functional tests
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment