Add trove.configure.help

1 files changed, 116 insertions, 0 deletions

diff --git a/trove.configure.help b/trove.configure.help
new file mode 100644
index 00000000..158cc741
--- /dev/null
+++ b/trove.configure.help
@@ -0,0 +1,116 @@
+help: |
+    This is a "morph deploy" configuration extension to fully configure
+    a Trove instance at deployment time. It uses the following 
+    configuration variables:
+
+    * `TROVE_ID`
+    * `TROVE_HOSTNAME` (optional, defaults to `TROVE_ID`)
+    * `TROVE_COMPANY`
+    * `LORRY_SSH_KEY`
+    * `UPSTREAM_TROVE`
+    * `TROVE_ADMIN_USER`
+    * `TROVE_ADMIN_EMAIL`
+    * `TROVE_ADMIN_NAME`
+    * `TROVE_ADMIN_SSH_PUBKEY`
+    * `LORRY_CONTROLLER_MINIONS` (optional, defaults to 4)
+
+    The variables are described in more detail below.
+
+    A Trove deployment needs to know the following things:
+
+    * The Trove's ID and public name.
+    * The Trove's administrator name and access details.
+    * Private and public SSH keys for the Lorry user on the Trove.
+    * Which upstream Trove it should be set to mirror upon initial deploy.
+
+    These are specified with the configuration variables described in this
+    help.
+
+    * `TROVE_ID` -- the identifier of the Trove. This separates it from
+      other Troves, and allows mirroring of Troves to happen without local
+      changes getting overwritten.
+
+      The Trove ID is used in several ways. Any local repositories (those not
+      mirrored from elsewhere) get created under a prefix that is the ID.
+      Thus, the local repositories on the `git.baserock.org` Trove, whose
+      Trove ID is `baserock`, are named
+      `baserock/baserock/definitions.git` and similar. The ID is used
+      there twice: first as a prefix and then as a "project name" within
+      that prefix. There can be more projects under the prefix. For
+      example, there is a `baserock/local-config/lorries.git` repository,
+      where `local-config` is a separate project from `baserock`. Projects
+      here are a concept for the Trove's git access control language.
+
+      The Trove ID also used as the prefix for any branch and tag names
+      created locally for repositories that are not local. Thus, in the
+      `delta/linux.git` repository, any local branches would be called
+      something like `baserock/morph`, instead of just `morph`. The
+      Trove's git access control prevents normal uses from pushing
+      branches and tags that do not have the Trove ID as the prefix.
+
+    * `TROVE_HOSTNAME` -- the public name of the Trove. This is an
+      optional setting, and defaults to `TROVE_ID`. The public name is
+      typically the domain name of the server (e.g., `git.baserock.org`),
+      but can also be an IP address. This setting is used when Trove needs
+      to generate URLs that point to itself, such as the `git://` and
+      `http://` URLs for each git repository that is viewed via the web
+      interface.
+
+      Note that this is _not_ the system hostname. That is set separately,
+      with the `HOSTNAME` configuration setting (see the
+      `set-hostname.configure` extension).
+
+    * `TROVE_COMPANY` -- a description of the organisation who own the
+      Trove. This is shown in various parts of the web interface of the
+      Trove. It is for descriptive purposes only.
+
+    * `LORRY_SSH_KEY` -- ssh key pair that the Trove's Lorry will use to
+      access an upstream Trove, and to push updates to the Trove's git
+      server.
+
+      The value is a filename on the system doing the deployment (where
+      `morph deploy` is run). The file contains the _private_ key, and the
+      public key is in a file with the `.pub` suffix added to the name.
+
+      The upstream Trove needs to be configured to allow this key to
+      access it. This configuration does not do that automatically.
+
+    * `UPSTREAM_TROVE` -- public name of the upstream Trove (domain
+      name or IP address). The new Trove will be configured to mirror
+      that Trove.
+
+    * `TROVE_ADMIN_USER`, `TROVE_ADMIN_EMAIL`, `TROVE_ADMIN_NAME`,
+      `TROVE_ADMIN_SSH_PUBKEY` -- details of the Trove's (initial)
+      administrator.
+
+      Each Trove needs at least one administrator user, and one is created
+      upon initial deployment. `TROVE_ADMIN_USER` is the username of the
+      account to be created, `TROVE_ADMIN_EMAIL` should be the e-mail of
+      the user, and `TROVE_ADMIN_NAME` is their name. If more
+      administrators are needed, the initial person should create them
+      using the usual Gitano commands.
+
+    * `LORRY_CONTROLLER_MINIONS` -- the number of Lorry Controller worker
+     processes to start. This is an optional setting and defaults to 4.
+     The more workers are running, the more Lorry jobs can run at the same
+     time, but the more resources they require.
+
+    Example
+    -------
+
+    The following set of variables could be to deploy a Trove instance:
+
+        TROVE_ID: my-trove
+        TROVE_HOSTNAME: my-trove.example.com
+        TROVE_COMPANY: My Personal Trove for Me, Myself and I
+        LORRY_SSH_KEY: my-trove/lorry.key
+        UPSTREAM_TROVE: git.baserock.org
+        UPSTREAM_TROVE_USER: my-trove
+        UPSTREAM_TROVE_EMAIL: my-trove@example.com
+        TROVE_ADMIN_USER: tomjon
+        TROVE_ADMIN_EMAIL: tomjon@example.com
+        TROVE_ADMIN_NAME: Tomjon of Lancre
+        TROVE_ADMIN_SSH_PUBKEY: my-trove/tomjon.key.pub
+
+    These would be put into the cluster morphology used to do the
+    deployment.