gitian build README improvements

1 files changed, 78 insertions, 38 deletions

diff --git a/contrib/gitian/README.md b/contrib/gitian/README.md
index 3fc26354c..32aee5f56 100644
--- a/contrib/gitian/README.md
+++ b/contrib/gitian/README.md
@@ -26,12 +26,16 @@ Preparing the Gitian builder host
 
 The first step is to prepare the host environment that will be used to perform the Gitian builds.
 This guide explains how to set up the environment, and how to start the builds.
-Gitian offers to build with either `kvm`, `docker` or `lxc`. The default build
-path chosen is `lxc`, but its setup is more complicated. You need to be logged in as the `gitianuser`. 
-If this user does not exist yet on your system, create it. Gitian can use
-either kvm, lxc or docker as a host environment. This documentation will show
-how to build with lxc and docker. While the docker setup is easy, the lxc setup
-is more involved.
+
+* Gitian host OS should be Ubuntu 18.04 "Bionic Beaver".  If you are on a mac or windows for example, you can run it in a VM but will be slower.
+
+* Gitian gives you the option of using any of 3 different virtualization tools: `kvm`, `docker` or `lxc`. This documentation will only show how to build with `lxc` and `docker` (documentation for `kvm` is welcome). Building with `lxc` is the default, but is more complicated, so we recommend docker your first time.
+
+
+## Create the gitianuser account
+
+You need to create a new user called `gitianuser` and be logged in as that user.  The user needs `sudo` access.
+
 
 LXC
 ---
@@ -76,10 +80,17 @@ This setup is required to enable networking in the container.
 Docker
 ------
 
-Building in docker does not require much setup. Install docker on your host, then type the following:
+Prepare for building with docker:
 
 ```bash
-sudo apt-get install git make curl
+sudo apt-get install git make curl docker.io
+```
+
+Consider adding `gitianuser` to the `docker` group after reading about [the security implications](https://docs.docker.com/v17.09/engine/installation/linux/linux-postinstall/):
+
+```bash
+sudo groupadd docker
+sudo usermod -aG docker gitianuser
 ```
 
 Optionally add yourself to the docker group. Note that this will give docker root access to your system.
@@ -88,7 +99,7 @@ Optionally add yourself to the docker group. Note that this will give docker roo
 sudo usermod -aG docker gitianuser
 ```
 
-Manual and Building
+Manual Building
 -------------------
 
 The instructions below use the automated script [gitian-build.py](gitian-build.py) which only works in Ubuntu. 
@@ -109,66 +120,95 @@ The `gitian-build.py` script will checkout different release tags, so it's best
 cp monero/contrib/gitian/gitian-build.py .
 ```
 
-Setup the required environment, you only need to do this once:
+### Setup the required environment
+
+Setup for LXC:
 
 ```bash
-./gitian-build.py --setup fluffypony v0.14.0
+GH_USER=fluffypony
+VERSION=v0.14.1.0
+
+./gitian-build.py --setup $GH_USER $VERSION
 ```
 
-Where `fluffypony` is your Github name and `v0.14.0` is the version tag you want to build. 
-If you are using docker, run it with:
+Where `GH_USER` is your Github user name and `VERSION` is the version tag you want to build. 
+
+Setup for docker:
 
 ```bash
-./gitian-build.py --setup --docker fluffypony v0.14.0
+./gitian-build.py --setup --docker $GH_USER $VERSION
 ```
 
-While gitian and this build script does provide a way for you to sign the build directly, it is recommended to sign in a seperate step. 
-This script is only there for convenience. Seperate steps for building can still be taken.
+While gitian and this build script does provide a way for you to sign the build directly, it is recommended to sign in a separate step. This script is only there for convenience. Separate steps for building can still be taken.
 In order to sign gitian builds on your host machine, which has your PGP key, 
-fork the gitian.sigs repository and clone it on your host machine, 
+fork the [gitian.sigs repository](https://github.com/monero-project/gitian.sigs) and clone it on your host machine, 
 or pass the signed assert file back to your build machine.
 
 ```bash
 git clone git@github.com:monero-project/gitian.sigs.git
-git remote add fluffypony git@github.com:fluffypony/gitian.sigs.git
+git remote add $GH_USER git@github.com:$GH_USER/gitian.sigs.git
 ```
 
-Build Binaries
------------------------------
-To build the most recent tag (pass in `--docker` after setting up with docker):
+Build the binaries
+------------------
+
+**Note:** if you intend to build MacOS binaries, please follow [these instructions](https://github.com/bitcoin-core/docs/blob/master/gitian-building/gitian-building-mac-os-sdk.md) to get the required SDK.
+
+To build the most recent tag (pass in `--docker` if using docker):
 
 ```bash
-./gitian-build.py --detach-sign --no-commit -b fluffypony v0.14.0
+./gitian-build.py --detach-sign --no-commit --build $GH_USER $VERSION
 ```
 
-To speed up the build, use `-j 5 -m 5000` as the first arguments, where `5` is the number of CPU's you allocated to the VM plus one, and 5000 is a little bit less than then the MB's of RAM you allocated. If there is memory corruption on your machine, try to tweak these values.
+To speed up the build, use `-j 5 --memory 5000` as the first arguments, where `5` is the number of CPU's you allocated to the VM plus one, and 5000 is a little bit less than then the MB's of RAM you allocated. If there is memory corruption on your machine, try to tweak these values.
 
-If all went well, this produces a number of (uncommited) `.assert` files in the gitian.sigs repository.
+If all went well, this produces a number of (uncommitted) `.assert` files in the gitian.sigs directory.
 
-If you do detached, offline signing, you need to copy these uncommited changes to your host machine, where you can sign them. For example:
+Checking your work
+------------------
+
+Take a look in the assert files and note the SHA256 checksums listed there. eg for `v0.14.1.0` you should get this checksum:
+
+```
+2b95118f53d98d542a85f8732b84ba13b3cd20517ccb40332b0edd0ddf4f8c62  monero-x86_64-linux-gnu.tar.gz
+```
+
+You should verify that this is really the checksum you get on that file you built.  You can also look in the gitian.sigs repo and / or [getmonero.org release checksums](https://web.getmonero.org/downloads/hashes.txt) to see if others got the same checksum for the same version tag.  If there is ever a mismatch -- **STOP! Something is wrong**.  Contact others on IRC / github to figure out what is going on.
+
+
+Signing assert files
+--------------------
+
+If you chose to do detached signing using `--detach-sign` above (recommended), you need to copy these uncommitted changes to your host machine, then sign them using your gpg key like so:
 
 ```bash
-export NAME=fluffypony
-export VERSION=v0.14.0
-gpg --output $VERSION-linux/$NAME/monero-linux-$VERSION-build.assert.sig --detach-sign $VERSION-linux/$NAME/monero-linux-$VERSION-build.assert
-gpg --output $VERSION-osx-unsigned/$NAME/monero-osx-$VERSION-build.assert.sig --detach-sign $VERSION-osx-unsigned/$NAME/monero-osx-$VERSION-build.assert
-gpg --output $VERSION-win-unsigned/$NAME/monero-win-$VERSION-build.assert.sig --detach-sign $VERSION-win-unsigned/$NAME/monero-win-$VERSION-build.assert
+GH_USER=fluffypony
+VERSION=v0.14.1.0
+
+gpg --detach-sign ${VERSION}-linux/${GH_USER}/monero-linux-*-build.assert
+gpg --detach-sign ${VERSION}-win/${GH_USER}/monero-win-*-build.assert
+gpg --detach-sign ${VERSION}-osx/${GH_USER}/monero-osx-*-build.assert
 ```
+<!-- TODO: Replace * above with ${VERSION} once gitian builds correct file name -->
+
+This will create a `.sig` file for each `.assert` file above (2 files for each platform).
+
+
+Submitting your signed assert files
+-----------------------------------
 
 Make a pull request (both the `.assert` and `.assert.sig` files) to the
 [monero-project/gitian.sigs](https://github.com/monero-project/gitian.sigs/) repository:
 
 ```bash
-git checkout -b v0.14.0
-git commit -S -a -m "Add $NAME v0.14.0"
-git push --set-upstream $NAME v0.14.0
+git checkout -b $VERSION
+# add your assert and sig files...
+git commit -S -a -m "Add $GH_USER $VERSION"
+git push --set-upstream $GH_USER $VERSION
 ```
 
-```bash
-gpg --detach-sign ${VERSION}-linux/${SIGNER}/monero-linux-*-build.assert
-gpg --detach-sign ${VERSION}-win-unsigned/${SIGNER}/monero-win-*-build.assert
-gpg --detach-sign ${VERSION}-osx-unsigned/${SIGNER}/monero-osx-*-build.assert
-```
+**Note:** Please ensure your gpg public key is available to check signatures by adding it to the [gitian.sigs/gitian-pubkeys/](https://github.com/monero-project/gitian.sigs/tree/master/gitian-pubkeys) directory in a pull request.
+
 
 More Build Options
 ------------------