dev-support/release-vm/README.md

   1 <!---
   2 Licensed to the Apache Software Foundation (ASF) under one
   3 or more contributor license agreements.  See the NOTICE file
   4 distributed with this work for additional information
   5 regarding copyright ownership.  The ASF licenses this file
   6 to you under the Apache License, Version 2.0 (the
   7 "License"); you may not use this file except in compliance
   8 with the License.  You may obtain a copy of the License at
   9
  10   http://www.apache.org/licenses/LICENSE-2.0
  11
  12 Unless required by applicable law or agreed to in writing,
  13 software distributed under the License is distributed on an
  14 "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  15 KIND, either express or implied.  See the License for the
  16 specific language governing permissions and limitations
  17 under the License.
  18 -->
  19
  20 # HBase Release Env
  21
  22 This is a vagrant project that provides a virtual machine environment suitable
  23 for running an Apache HBase release.
  24
  25 Requires:
  26 * [VirtualBox](http://virtualbox.org)
  27 * [Vagrant](http://virtualbox.org)
  28 * The private portion of your signing key avilable in the local GPG agent
  29 * The private portion of your Github authentication key available in either the local GPG agent or
  30   local SSH agent
  31
  32 ## Usage
  33
  34 Unlock the local keyring before proceeding (this should prompt you for your GPG passphrase). For
  35 example, assuming you have an authentication key configured in your keyring, this will do the
  36 trick.
  37
  38 All terminal commands used below are assumed to be run with the current working directory as the
  39 location containing the `Vagrantfile`.
  40
  41 The term "Host" is used to mean the environment that runs the Vagrant process. The term "Guest" is
  42 used to mean the virtual machine managed by the Host.
  43
  44 ### Ensure credentials work from the Host OS
  45
  46 The ssh- and gpg-agent forwarding configuration used here assumes that your credentials work
  47 on the Host. Verify both are working before you proceed with the Guest. Additionally, using the
  48 credentials requires you to unlock the respective keyring, the state of which is persisted by the
  49 agent process or processes running on the Host.
  50
  51 See instructions in [`create-release`](../create-release/README.txt) regarding proper
  52 configuration of ssh- and gpg-agents.
  53
  54 Assuming the git repo origin is on GitHub, the following command will ensure that your ssh
  55 credentials are working. On the Host, run:
  56
  57 ```sh
  58 host:~$ ssh -T git@github.com
  59 Hi <you>! You've successfully authenticated, but GitHub does not provide shell access.
  60 ```
  61
  62 Likewise, ensure you have an encryption key that can be used to sign a file. Again, on the Host,
  63 run:
  64
  65 ```sh
  66 host:~$ gpg --detach --armor --sign Vagrantfile
  67 host:~$ gpg --verify Vagrantfile.asc
  68 gpg: assuming signed data in 'Vagrantfile'
  69 ...
  70 host:~$ rm Vagrantfile.asc
  71 ```
  72
  73 ### Make public keyring available to the VM
  74
  75 Export the public portion of your signing credentials where the Guest can access it. Vagrant
  76 (+VirtualBox) shares the directory of the `Vagrantfile` with the Linux Guest via the `/vagrant`
  77 mount point. Any files present in this working directory on the Host are available to the Guest.
  78
  79 From the Host, run:
  80
  81 ```sh
  82 host:~$ gpg --export <you>@apache.org > gpg.<you>.apache.pub
  83 ```
  84
  85 ### Launch the Guest VM
  86
  87 Launch the Guest VM by running
  88
  89 ```sh
  90 host:~$ vagrant up
  91 ```
  92
  93 If anything about the Vagrant or VirtualBox environment have changed since you last used this VM,
  94 it's best to `vagrant destroy -f` all local state and `vagrant up` a fresh instance.
  95
  96 ### Verify the Guest VM
  97
  98 Connect to the Guest. This should forward your ssh- and gpg-agent session, as configured in the
  99 `Vagrantfile`.
 100
 101 ```sh
 102 host:~$ vagrant ssh
 103 ```
 104
 105 Now that you're in the Guest VM, be sure that all `gpg` command you issue include the
 106 `--no-autostart` flag. This ensures that the `gpg` process in the Guest communicates with the
 107 agent running on the Host OS rather than launching its own process on the Guest OS.
 108
 109 From the Guest, verify that ssh-agent forwarding is working, using the same test performed on the
 110 Host,
 111
 112 ```sh
 113 guest:~$ ssh -T git@github.com
 114 Hi <you>! You've successfully authenticated, but GitHub does not provide shell access.
 115 ```
 116
 117 From the Guest, import your exported public identity and verify the gpg-agent passthrough is
 118 working correctly.
 119
 120 ```sh
 121 guest:~$ gpg --no-autostart --import /vagrant/gpg.<you>.apache.pub
 122 ...
 123 gpg: Total number processed: 1
 124 gpg:               imported: 1
 125 guest:~$ gpg --no-autostart --detach --armor --sign repos/hbase/pom.xml
 126 guest:~$ gpg --no-autostart --verify repos/hbase/pom.xml.asc
 127 gpg: assuming signed data in 'repos/hbase/pom.xml'
 128 ...
 129 guest:~$ rm repos/hbase/pom.xml.asc
 130 ```
 131
 132 ### Build a Release Candidate
 133
 134 Finally, you can initiate the release build. Follow the instructions in
 135 [`create-release`](../create-release/README.txt), i.e.,
 136
 137 ```sh
 138 guest:~$ mkdir ~/build-2.3.1-rc0
 139 guest:~$ cd repos/hbase
 140 guest:~/repos/hbase$ ./dev-support/create-release/do-release-docker.sh -d ~/build-2.3.1-rc0/ ...
 141 ```