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

Heptapod-source: installation guide

--HG--
branch : heptapod
parent 0ae5fd0aeaa9
# Heptapod installation guide
## Installing from source
Heptapod installation is similar to GitLab's except that
- some components have to be taken from our Mercurial repositories
- we have an additional component for Mercurial.
- some specific configuration has to be set in place.
- we have more constraints, many of which will be hopefully lifted in
forthcoming versions
### Limitations
the Rails application, GitLab Shell, Mercurial and the repositories must
be in a single system.
### Fetching the standard GitLab components
We try and maintain a consistent tagging policy across the various Mercurial
repositories. For example, in version 0.8.0rc1, all of them have a
`heptapod-0.8.0rc1` tag.
Please use the mirror URL for initial and repetitive clonings.
- Rails application (replacement for `gitlab`): https://mirror.octobus.net/heptapod/heptapod
- Heptapod Shell (replacement for GitLab Shell): https://mirror.octobus.net/heptapod/heptapod-shell
Example:
```
hg clone https://mirror.octobus.net/heptapod/heptapod
cd heptapod
hg update heptapod-0.8.0rc1
```
All other standard GitLab components (Workhorse, etc) have to be taken
from the canonical upstream locations, at the version specified at the root
of the Rails application sources (`GITLAB_WORKHORSE_VERSION` etc).
### Installing the Mercurial component
We need a specific Mercurial version, a WSGI server (usually Gunicorn), and
some additional Python packages from source.
For now, this is Python2 only.
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
`pip install --user` or in a virtualenv. What matters for proper operation is
that they are all importable from the final Mercurial executable.
The Python packages to be taken from pypi.org are already listed alongside the
[Dockerfile](TODO link), just use that, but be sure to take it from the same
tag as the sources.
Then install with pip from the following Mercurial URLs:
- https://mirror.octobus.net/heptapod/hg-git-heptapod
- https://mirror.octobus.net/heptapod/hgext_loggingmod
- https://mirror.octobus.net/heptapod/py-heptapod
Note: `hgext_loggingmod` is an exception of the tagging policy.
After initial development, it just
stayed untouched, version 0.2.1 is fine.
### Configuration
`py-heptapod` ships with a configuration file that perfoms most of the required
and default Mercurial settings for Heptapod
(using the `heptapod` extension, permission policy, etc.)
You'll need to use it and add your local installation details.
A simple way is to create a `heptapod.hgrc` file using the `%include` directive.
See the example in `py-heptapod/heptapod/heptapod.example.hgrc`.
Then edit the configuration files for the Rails application
(see `config/gitlab.yml.example`) and GitLab Shell (see `config.yml.example`),
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.
### Internal Mercurial service
Repository content is exposed to GitLab through an internal HTTP service.
Warning: do NOT have it listen to any other interface than the loopback:
its security model is to trust the Rails application blindly.
It also needs to load your hgrc file(s). Here's an example, assuming `gunicorn`
is on the path.
```
HEPTAPOD_HGRC=/path/to/your/heptapod.hgrc gunicorn -w 5 \
-b 127.0.0.1:8000 \
--error-logfile /tmp/gunicorn.log \
--capture-output \
heptapod.wsgi:hgserve
```
Again, this `gunicorn` must be able to load the Heptapod Python packages.
Notes:
- Heptapod is not able yet to use Unix domain sockets
- If you want to use another loopback URL, configure the Rails app
accordingly, in `config/gitlab.yml`.
### Validation with the functional tests
- start from an empty set of data (do not even set the instance root password)
- install tox (Python3)
- grab the functional tests:
`hg clone https://dev.heptapod.net/heptapod/heptapod-tests`
- run the tests as the same user as the GitLab components, with something
like:
```
tox -- --heptapod-ssh-port 2222 \
--heptapod-url http://localhost:3000 \
--heptapod-source-install \
--heptapod-repositories-root ~/heptapod/gdk/gl10-5/repositories
```
(for a quicker first test, you can add `-k push_basic`)
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