INSTALL: Document how to integrate Lorry/LC with each Downstream Host type

Document how to configure Gerrit, Gitea, and GitLab for use with
Lorry and Lorry Controller, and vice versa.

For Gitano/Trove, refer to the Baserock documentation.

Relates to #2.

1 files changed, 140 insertions, 0 deletions

diff --git a/INSTALL b/INSTALL
index 57684e4..b3c8933 100644
--- a/INSTALL
+++ b/INSTALL
@@ -62,3 +62,143 @@ Controller on the host where they will run.
 
 Create an SSH key pair for Lorry, and install the *private* key in
 `.ssh` in Lorry's home directory.
+
+## Configuring the Downstream Host
+
+### Gerrit
+
+These instructions were written for Gerrit 3.1.
+
+1. Create a user for Lorry in Gerrit's authentication provider.
+   Add Lorry's SSH *public* key to the Gerrit user account.
+
+2. Create a group in Gerrit, or add the user to a group, that will be
+   permitted to create repositories and push changes to them.  The
+   Lorry user should be a member but not an owner of this group.
+
+3. (Optional but strongly recommended) Create a parent project for
+   the mirror repositories and make this group the owner.
+
+   Use the `gerrit create-project` command with the
+   `--permissions-only` option.  Alternately, in the web UI, create
+   a new project and fill out the form as follows:
+
+   * Set 'Repository name' as you wish.  This is independent of the
+     names of repositories that Lorry will create.
+   * Leave 'Rights inherit' blank
+   * Set Owner to the group
+   * Set 'Create initial empty commit' to 'False'
+   * Set 'Only server as parent for other repositories' to 'True'
+
+4. Give the group permission to create repositories,
+   [bypass review](https://gerrit-review.googlesource.com/Documentation/user-upload.html#bypass_review),
+   [skip validation](https://gerrit-review.googlesource.com/Documentation/user-upload.html#skip_validation),
+   and push tags that aren't on a branch:
+
+   * In 'All-Projects', give the group 'Create Project' permission.
+     In the web UI this is in the Global Capabilities section.
+   * In the parent project (or 'All-Projects'), give the group 'Forge
+     Author Identity', 'Forge Committer Identity', 'Forge Server
+     Identity', 'Push', and 'Push Merge Commit' permissions over
+     `refs/*`
+   * If you *did not* create a parent project, then in 'All-Projects'
+     also give the group 'Create Reference', 'Create Signed Tag', and
+     'Create Annotated Tag' permissions over `refs/*`
+
+5. In `lorry.conf`:
+
+   * Set `mirror-base-url-{fetch,push}` to
+   `git+ssh://`*username*`@`*hostname*`:29418`
+   * Set `push-option = skip-validation`
+
+6. In `webapp.conf`:
+
+   * Set `downstream-host-type = gerrit`
+   * Set `downstream-ssh-url = ssh://`*username*`@`*hostname*`:29418`
+   * Set `gerrit-parent-project =` *parent-project*
+
+7. Add Gerrit's SSH host public key to `.ssh/known_hosts` in Lorry's
+   home directory.
+
+### Gitano
+
+Gitano and Lorry Controller would normally be deployed together as
+part of a Trove: <http://wiki.baserock.org/Trove/reference/>.
+
+### Gitea
+
+These instructions were written for Gitea 1.11.
+
+1. Create a user for Lorry in Gitea (or its authentication provider).
+   Log in as the user and add Lorry's SSH *public* key to the user
+   account.  Generate an access token for the user.
+
+2. Set `mirror-base-url-{fetch,push}` in `lorry.conf` to
+   `git+ssh://git@`*hostname*
+
+3. In `webapp.conf`:
+
+   * Set `downstream-host-type = gitea`
+   * Set `downstream-visibility` to the desired visibility of
+     repositories: `private`, `internal`, or `public`
+   * Set `downstream-http-url` to the HTTPS or HTTP (not recommended)
+     URL of the Gitea server.
+   * Set `gitea-access-token =` *access-token*
+
+4. Add Gitea's SSH host public key to `.ssh/known_hosts` in Lorry's
+   home directory.
+
+Gitea requires all repositories to be organised under a user or
+organisation, and organisations cannot contain other organisations.
+You must therefore ensure that the CONFGIT specifies repository paths
+with exactly two path components.
+
+Lorry Controller will attempt to create organisations as needed to
+contain repositories.  If your Gitea configuration does not allow
+users to do this, you will need to create organisations in advance and
+give the Lorry user permission to create repositories under them.
+
+### GitLab
+
+These instructions were written for GitLab CE 12.10.
+
+1. Create a user for Lorry in GitLab (or its authentication provider).
+   Add Lorry's SSH *public* key to the user account.  Generate an
+   impersonation token for the user.
+
+2. Set `mirror-base-url-{fetch,push}` in `lorry.conf` to
+   `git+ssh://git@`*hostname*
+
+3. In `webapp.conf`:
+
+   * Set `downstream-host-type = gitlab`
+   * Set `downstream-visibility` to the desired visibility of
+     repositories: `private`, `internal`, or `public`
+   * Set `downstream-http-url` to the HTTPS or HTTP (not recommended)
+     URL of the GitLab server.
+   * Set `gitlab-private-token =` *impersonation-token*
+
+4. Add GitLab's SSH host public key to `.ssh/known_hosts` in Lorry's
+   home directory.
+
+GitLab requires all projects to be organised under a user or group.
+You must therefore ensure that the CONFGIT specifies repository paths
+with at least two path components.
+
+Lorry Controller will attempt to create groups as needed to contain
+projects.  If your GitLab configuration does not allow users to do
+this, you will need to create top-level groups in advance and give the
+Lorry user permission to create subgroups and projects under them.
+
+### Local filesystem
+
+1. Create a directory to contain the repositories, writable by
+   the Lorry user.
+
+2. Set `mirror-base-url-{fetch,push}` in `lorry.conf` to the directory
+   name.
+
+3. In `webapp.conf`:
+
+   * Set `downstream-host-type = local`
+   * Set `local-base-directory =` *directory*