src/docs/user/userguide/drydock_quick_start.diviner

   1 @title Drydock User Guide: Quick Start
   2 @group userguide
   3
   4 Guide to getting Drydock
   5
   6 Quick Start: Land Revisions
   7 ===========================
   8
   9 Quick start guide to getting "Land Revision" working in Differential. For
  10 a more detailed guide, see @{article:Drydock User Guide: Repository Automation}.
  11
  12 Choose a repository you want to enable "Land Revision" for. We'll call this
  13 **Repository X**.
  14
  15 You need to configure a staging area for this repository if you haven't
  16 already. You can do this in Diffusion in {nav Edit Repository > Edit Staging}.
  17 We'll call this **Staging Area Y**.
  18
  19 Choose or create a host you want to run merges on. We'll call this
  20 `automation001`. For example, you might bring up a new host in EC2 and
  21 label it `automation001.mycompany.com`. You can use an existing host if you
  22 prefer.
  23
  24 Create a user account on the host, or choose an existing user account. This is
  25 the user that merges will execute under: Drydock will connect to it and run a
  26 bunch of `git` commands, then ultimately run `git push`. We'll call this user
  27 `builder`.
  28
  29 Install `git`, `hg` or `svn` if you haven't already and set up private keys
  30 for `builder` so it can pull and push any repositories you want to operate
  31 on.
  32
  33 If your repository and/or staging area are hosted in Phabricator, you may want
  34 to create a corresponding bot account so you can add keys and give it
  35 permissions.
  36
  37 At this point you should be able to `ssh builder@automation001` to connect to
  38 the host, and get a normal shell. You should be able to `git clone ...` from
  39 **Repository X** and from **Staging Area Y**, and `git push` to **Repository
  40 X**. If you can't, configure things so you can.
  41
  42 Now, create a host blueprint for the host. You can find a more detailed
  43 walkthrough in @{article:Drydock Blueprints: Hosts}. Briefly:
  44
  45   - Create an Almanac device for the host. This should have the IP address and
  46     port for your host.
  47   - Create an Almanac service bound to the device. This should be a Drydock
  48     resource pool service and have a binding to the IP from the previous step.
  49   - Create a Drydock host blueprint which uses the service from the previous
  50     step. It should be configured with an SSH private key that can be used
  51     to connect to `builder@automation001`.
  52
  53 Then, create a new working copy blueprint which uses the host blueprint you
  54 just made. You can find a more detailed walkthrough in @{article:Drydock
  55 Blueprints: Working Copies}. Authorize the working copy blueprint to use the
  56 host blueprint.
  57
  58 Finally, configure repository automation for **Repository X**:
  59 {nav Edit Repository > Edit Automation}. Provide the working copy blueprint
  60 from the previous step. Authorize the repository to use the working copy
  61 blueprint.
  62
  63 After you save changes, click {nav Test Configuration} to test that things
  64 are working properly.
  65
  66 The "Land Revision" action should now be available on revisions for this
  67 repository.
  68
  69 Next Steps
  70 ==========
  71
  72 Continue by:
  73
  74   - returning to @{article:Drydock User Guide}.