summaryrefslogtreecommitdiff
path: root/trove.configure.help
diff options
context:
space:
mode:
authorLars Wirzenius <lars.wirzenius@codethink.co.uk>2014-06-25 16:04:50 +0000
committerLars Wirzenius <lars.wirzenius@codethink.co.uk>2014-06-25 16:04:50 +0000
commit7e43afacbae79ca20c45e26829e9e436e4993664 (patch)
tree971eb748df3b5f6d762f6421e2c267a9414148a6 /trove.configure.help
parentf26b5897d13df38d88c8de1ffc8d2cd4d37c2d09 (diff)
downloaddefinitions-7e43afacbae79ca20c45e26829e9e436e4993664.tar.gz
Add trove.configure.help
Diffstat (limited to 'trove.configure.help')
-rw-r--r--trove.configure.help116
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.