INSTALL_HEPTAPOD.md 5.1 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53
# 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
54 55
[Dockerfile](https://dev.heptapod.net/heptapod/heptapod-docker/blob/branch/default/heptapod/pip-requirements.txt),
just use that, but be sure to take it from the same tag as the sources.
56

57
Then install from the following Mercurial URLs:
58 59

- https://mirror.octobus.net/heptapod/hg-git-heptapod
Pierre-Yves David's avatar
Pierre-Yves David committed
60
- https://mirror.octobus.net/octobus/hgext-loggingmod
61 62
- https://mirror.octobus.net/heptapod/py-heptapod

63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83
For each one, rather to use `pip install hg+https`, which is quite error
prone, the simplest best way looks like this:

```
hg clone -u $TAG https://mirror.octobus.net/heptapod/py-heptapod
$PIP install -e py-heptapod
```

where `$PIP` is `pip --user` or `some/virtualenv/bin/pip` according to your
choice.

Notes:

- these repositories are small enough than pull exactly the wanted
  revision is a needless complication.
- `hgext_loggingmod` is an exception of the tagging policy.
  After initial development, it just stayed untouched, version 0.1.2 is fine.
- the `-e` flag will make your subsequent updates easier: you'll just have
  to `hg pull -u NEW_TAG`, redo the `pip install -e` to account for package
  metadata changes (notably entry points if any) and restart relevant processes.

84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149


### 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`)